Manpage generation

[Zack Weinberg]

I'm responding to two messages at once - sorry for any confusion.

On Mon, Apr 08, 2002 at 09:22:08AM +0300, Eli Zaretskii wrote:
> On 7 Apr 2002, Tom Tromey wrote:
> > >>>>> "Karl" == Karl Berry <address@hidden> writes:
> > Karl> Tom Tromey just suggested the same thing.  I haven't had a
> > Karl> chance to look at what you've done yet.  It seems impossible to
> > Karl> me that the same text can be used for man pages and real
> > Karl> manuals?  One or the other must surely suffer.

It turns out to be relatively easy.  The key realization is that a
manpage for a program isn't _supposed_ to contain the complete content
of its manual.  A couple of paragraphs of overview, plus a complete
list of command line options, is fine.

So, what my program does is interpret magic comments that select
chunks of the Texinfo source to be rendered into POD and thence
manpage troff.  (The maintainers of pod2man deserve a lot of credit; I
would never have been able to do this if I had had to generate troff
markup myself.)  So you have something like

@node Overview
@chapter Overview
@c man begin DESCRIPTION
The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor}
that is used automatically by the C compiler to transform your program
before compilation.  It is called a macro processor because it allows
you to define @dfn{macros}, which are brief abbreviations for longer
constructs.

[...]

@c man end

[... rest of manual here ...]

In some cases you have text that's irrelevant to the Info manual; this
is currently handled by putting a @c man block inside an @ignore
block.  The script doesn't pay any attention to markup outside its
magic comments.

This works very well in practice, as long as you're documenting
programs.  It wouldn't work for section 3 documentation (i.e. for
glibc) where you'd have to generate hundreds of individual manpages
from one document with large chunks of text repeated each time.

> I'm not sure I understand: are you suggesting that "@c man" be treated 
> specially?  If so, I'm not sure it's a good idea: comments should be left 
> alone, IMHO.  For example, some document could have a comment like this 
> that has nothing to do with man pages.

We currently use magic comments, because I wasn't in a position to
introduce changes to all the other Texinfo parsers.  This is one of
the reasons I described it as a dirty hack.  (Another is that the code
suffers from overgrown-perl-script-itis.)

To do it properly, I would suggest: @man <section> [<program>]... @end man
replacing the existing @c man begin <section> ... @c man end;
@mantitle <program> <description> replacing @c man title (maybe
@mantitle <program>, <description>?); and @if(not)man ... @end if(not)man
instead of the @ignore hack.

zw