The generate-man script is currently a shell script which invokes the
pod2man command for each pod file to be converted into a man page. This
makes the pod conversion slow, since we load Perl and create a Pod::Man
parser for each pod file. In addition to being slow, generate-man
leaves behind a partially created man page when an error is
encountered during the pod2man execution.
To fix these issues, rewrite generate-man as a Perl script which uses
the Pod::Man module directly. The Pod::Man parser is created only once
and is reused to generate each man page. The Pod::Man module supports
this type of batch mode operation by clearing its internal state after
each man page is created.
We have some special processing to determine the man page names for the
pages in section 3, so create a sub class to handle the pod filename to
man page title determination, and add a helper function to support
processing more than one section with a single parser instance.
Be sure to cleanup any partially created man pages if an error is
encountered during the pod to man conversion. This will let us use this
script in the Makefiles in the future.
Change-Id: I8d3cce1edc62c490e93d05f72609dfde4b599a1b
Reviewed-on: https://gerrit.openafs.org/15774
Reviewed-by: Mark Vitale <mvitale@sinenomine.net>
Tested-by: Mark Vitale <mvitale@sinenomine.net>
Tested-by: BuildBot <buildbot@rampaginggeek.com>
Reviewed-by: Cheyenne Wills <cwills@sinenomine.net>
Reviewed-by: Michael Meffie <mmeffie@sinenomine.net>
The pod2man tool determines a man page title (set in the .TH macro) from
the input filename, unless the -n (--name) option is specified.
Our AFS::ukernel man page input file is named AFS.ukernel.pod to avoid
colons in the filename (since colon characters are not supported on
Windows), so the generated man page contains the title "AFS.ukernel"
instead of "AFS::ukernel".
Use the pod2man -n (--name) option when converting section 3 man pages
to override the automatic title naming. This fixes the .TH macro in the
generated AFS::ukernel.3 file. Fortunately, the -n (--name) option is
only needed for section 3 man pages.
Specifying the pod2man -n (--name) option is simpler and less invasive than
renaming pod3/AFS.ukernel.pod to pod3/lib/AFS/ukernel.pod (which would
also fix the embedded title).
Change-Id: I495ea2d30ce1b34698519ffa34a39362c449ba09
Reviewed-on: https://gerrit.openafs.org/15363
Reviewed-by: Cheyenne Wills <cwills@sinenomine.net>
Reviewed-by: Mark Vitale <mvitale@sinenomine.net>
Tested-by: BuildBot <buildbot@rampaginggeek.com>
Reviewed-by: Benjamin Kaduk <kaduk@mit.edu>
Generate and install man pages (and their HTML versions) for library
reference documentation in section 3.
Change-Id: I500818097c6880e0412794661393351ab14461dc
Reviewed-on: http://gerrit.openafs.org/3898
Reviewed-by: Derrick Brashear <shadow@dementia.org>
Tested-by: Derrick Brashear <shadow@dementia.org>
Move man page generation out into a separate script that's just invoked
from regen.sh, so that someone can run that separate script later if they
wish. Make that script more robust against problems such as empty podN
directories. Diagnose a missing pod2man and warn about old versions of
Pod::Man.
Also, remove the old programs used to do the initial conversion from HTML.
Enough post-conversion editing was done that they're no longer necessary
except for historical curiosity, and for that purpose they can be pulled
out of CVS.
