www.delorie.com/gnu/docs/gcc/gccint_20.html

search

	Buy the book!

GNU Compiler Collection (GCC) Internals

5.3.7.2 Man Page Generation

Because of user demand, in addition to full Texinfo manuals, man pages are provided which contain extracts from those manuals. These man pages are generated from the Texinfo manuals using `contrib/texi2pod.pl' and pod2man. (The man page for g++, `cp/g++.1', just contains a `.so' reference to `gcc.1', but all the other man pages are generated from Texinfo manuals.)

Because many systems may not have the necessary tools installed to generate the man pages, they are only generated if the `configure' script detects that recent enough tools are installed, and the Makefiles allow generating man pages to fail without aborting the build. Man pages are also included in release distributions. They are generated in the source directory.

Magic comments in Texinfo files starting `@c man' control what parts of a Texinfo file go into a man page. Only a subset of Texinfo is supported by `texi2pod.pl', and it may be necessary to add support for more Texinfo features to this script when generating new man pages. To improve the man page output, some special Texinfo macros are provided in `doc/include/gcc-common.texi' which `texi2pod.pl' understands:

@code{}

Use in the form `@table @code{' for tables of options,} where for printed output the effect of `@code' is better than that of `@option' but for man page output a different effect is wanted.

@smallexample

Use for summary lists of options in manuals.

Use at the end of each line inside `@smallexample '. This is necessary to avoid problems with differences in how the `@smallexample ' macro is handled by different Texinfo formatters.

FIXME: describe the `texi2pod.pl' input language and magic comments in more detail.