[OpenAFS] Documentation project comments

[Russ Allbery]

ted creedon <tcreedon@easystreet.com> writes:

> Here's what you won't have in the POD's:

Please note that all I'm trying to do is produce man pages.  That means a
man page for each command or subcommand and a man page for each
configuration file.  I'm not trying to duplicate the installation
instructions or any of the other documentation manuals, just the reference
pages.

However, you're also uninformed about POD.

> 1. Verbatim text - particularly multiline (very useful). The verbatim text
> has multiple fonts and boldface to emphasize the point being made in the
> text.

POD does verbatim text, it just doesn't allow markup in verbatim text.
I'm not that worried about that.

> 2. Hyperlinks

POD does hyperlinks just fine.

> 3. Color

This is a function of your style sheets; if you want that in HTML, you can
get it.  Heck, you can get that on the console terminal if you want too;
that's why I wrote Pod::Text::Color eons ago.

> 4. Indexing and tables of contents

Correct, POD doesn't have real indexing support.  There are ways to get
tables of contents, but it's a hack.

> 5. Any other feature Latex supports that POD doesn't (quite a few).
> 6. We will be dealing with POD, xdvi, pdf, html outputs. Long term we need
> to figure out how to generate acceptable output from one set of latex files.

I think LaTeX is a reasonable format for the main manuals, although
personally I'd use texinfo.  (The info format is not very appealing, but
texinfo itself is quite nice -- it produces nice printed manuals and
adequate HTML output, as well as being quite easy to write and more widely
used in free software projects than straight LaTeX.)

> You can extract the appropriate text from the IBM.htm files by looking
> at the included html2latex.pl and Latex.pm files and modifying
> accordingly.  Latex.pm builds a parse tree of the IBM.htm and emits from
> there. (Note: the .xml setup file has been omitted, using __DATA__ at
> the end of the file instead. In particular <ban foo /ban> turns off
> parsing of undesired <foo xxxx /foo> fields.

> One might also read the POD documentation - I removed it from the
> sources to speed up editing - its in the perl release.

LaTeX is a non-starter for the problem that I'm trying to solve, which is
old-fashioned regular Unix man pages readable with "man command".  Having
those man pages is a requirement for Debian and something that I
personally much prefer, so that's the problem I'm going to work on
solving.

If you want my advice, I would focus on using LaTeX for the regular
documentation manuals and leave the current administrator's reference
largely alone, in the expectation that it's going to turn into a
collection of Unix man pages with corresponding HTML pages and won't need
to be maintained in the current format.

If you want to see HTML output from POD manual pages, look at, for
instance:

    <http://www.eyrie.org/~eagle/software/frak/docs.html>
    <http://www.eyrie.org/~eagle/software/mvto/docs.html>

or any of the pages linked from:

    <http://www.eyrie.org/~eagle/software/inn/docs/>

Those pages are all maintained in POD and converted automatically to HTML.

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