POD converters

Russ Allbery rra at stanford.edu
Sat Sep 25 21:32:34 UTC 1999


For those who wish to write INN documentation in POD, here's some
information on the available converters and what I'm currently using to
get the best results.  Unless there are any objections, I'm also going to
start a document on INN internals and maintenance issues like this and
include most of this information there, probably to be called HACKING at
the root level of the INN distribution.  (It would also be a good place to
document conclusions that have been reached on coding style and the like.)

For conversion of POD to text and *roff, I'm using pod2text and pod2roff
respectively from my podlators distribution.  podlators requires
Pod::Parser; both can be obtained from /pub/CPAN/modules/by-modules/Pod on
your local CPAN mirror (such as ftp.perl.org).  In addition, Perl 5.004
will need File::Spec from /pub/CPAN/modules/by-module/File; that module
comes with Perl 5.005 and later.  (The translators won't work with
versions of Perl earlier than 5.004, but then neither will parts of INN.)

For conversion of POD to Docbook SGML, I'm using Pod::DocBook, also
available from /pub/CPAN/modules/by-modules/Pod.

The current versions as of this writing are Pod::DocBook 0.05, Pod::Parser
1.084, and podlators 0.07.

For pod2text, I'm using:

        pod2text -s -l file.pod > out

to generate the files we distribute as text (README, INSTALL, etc.).  -s
preserves two spaces after periods and -l adds a blank line after major
headings.

For pod2roff, I'm using:

        pod2roff -c "InterNetNews Documentation" -r "INN 2.3" file.pod > out

-c sets the centered header and -r sets the centered footer.  For some
documentation, you also have to provide -s <section> to set the correct
manual section.  It's best to run pod2roff from the doc/pod directory,
directing the output to the appropriate file in the doc/man directory,
since it does some tricks with the name of the file to determine the title
of the man page and can be confused by longer paths.

When I get a chance, I'll throw this stuff into some (not reached by
default) Makefile rules.

The versions of pod2man and pod2text that come with Perl will do a
passable but not ideal job; the pod2man output suffers more than the
pod2text output.  The pod2text in podlators will be the default pod2text
in the next release of Perl, and the pod2roff may be the default pod2man
depending on how much time I find to polish it up.

pod2roff produces output that's friendly to both nroff and troff, and
fairly nice printed documentation of INN could be produced by running all
of the manual pages through troff (probably with something like:

        troff -man -rC1 -rD1 *.1 *.3 *.5 *.8 | dpost > manual.ps

with the right path for dpost; turning on the C and D registers will yield
contiguous page numbering and even/odd paging in some versions of the man
macros).  It will get things like fixed-width fonts, typographic quotes,
and small caps right under troff.

For the benefit of those maintainers who have direct access to the CVS
machine, I have pod2text and pod2roff installed in ~rra/bin there and set
to look at the correct modules (also locally installed in my account).

-- 
Russ Allbery (rra at stanford.edu)         <URL:http://www.eyrie.org/~eagle/>


More information about the inn-workers mailing list