This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: Generation process for cpp.1
On Fri, Nov 10, 2000 at 04:42:43PM +0000, Joseph S. Myers wrote:
> The manpage cpp.1 is created from cpp.texi using contrib/texi2pod.pl plus
> pod2man and hand adjustments, but the precise process (including details
> of the adjustments needed) doesn't seem to be documented.
This is because the amount of hand adjustment needed varies depending
on which version of pod2man you have. I've been in touch with the
pod2man maintainer; the version in perl 5.6 supposedly only has
cosmetic issues, and 5.6.1-to-be shouldn't need any adjustment at all.
Anyway, you just do
contrib/texi2pod.pl < cpp.texi >cpp.pod
pod2man --center="GNU" --release="gcc-3.0" --section=1 cpp.pod > cpp.new.1
and then you run the result through nroff and see if it's okay. If it
isn't, you edit it.
> I'm wondering about the possibility of using this script to replace
> the hopelessly out of date gcc.1 manpage with something generated
> from invoke.texi.
Cool idea.
The key to making this work is magic comments in cpp.texi. If you
have
@c man begin DESCRIPTION
...
@c man end
around a chunk of text, that chunk becomes the DESCRIPTION section of
the manpage. In some cases, you don't want it showing up in the Info
file; then you just put @ignore ... @end ignore around the magic
comments. (The SYNOPSIS and SEE ALSO sections of cpp.1 are done thus.)
> would it be possible for the exact process to be documented,
> e.g. with an appropriate Makefile target to regenerate cpp.1 and
> another script in contrib to do what were the hand adjustments to
> the output?
I've been waiting for a version of pod2man that doesn't need any hand
editing to turn up in Debian unstable. Then I'll put in a Makefile
target.
It hasn't historically been possible to automate the edits, they
usually involve aesthetic problems that a script can't really detect.
zw