Re: Manpage generation

[Zack Weinberg]

On Mon, Apr 08, 2002 at 11:39:50AM -0400, Karl Berry wrote:
> 
> As Eli surmised, I was thinking more about the list of options, which
> can be spread over many, many nodes.  Does your script translate
> @itemize and the like?

Yes.

> We're talking about implementing another output format, it would
> seem.  Sigh.

Well, yeah, except that the work is largely done already - it's just a
matter of (a) cleaning up the existing script, (b) deciding on the
official syntax for the markup, (c) making minor modifications to the
other Texinfo processors to handle the markup.

> What about the author, reporting bugs, see also, etc., sections?
> Those texts seem like they would not work at all in the context of a
> manual.  

Hence @ifman.  But keep in mind that you can select just a tiny
fragment of a Texinfo node for a manual section -- for instance, just
the sentence

        See http://gcc.gnu.org/bugs.html for bug reporting instructions.

out of the lengthy "How to Report Bugs" node of the GCC manual (which
largely duplicates the content of the webpage).

> Those "ancillary" things are the main reason that using the
> --help output seems better to me.  There is a much closer match
> between --help and man pages than Texinfo and man pages.

I disagree.  The content of --help is usually inadequate to create a
manpage.  It doesn't contain an overview description, anything to
create the SEE ALSO section out of, or even complete documentation of
the options.

> @mantitle [<section>] <programname>
> @manpart synopsis ... @endmanpart synopsis
> @manpart description ... @endmanpart description

Which is basically what I had, only with @man synopsis ... @end man
instead of your @manpart ... @endmanpart.

zw