[OpenAFS-Doc] Final (from Latex) pdf's and html's available

[Russ Allbery]

Jeffrey Altman <jaltman@columbia.edu> writes:

> While I am a strong believer that those who do the work get significant
> points, there has been a significant lack of consensus on the tools you
> selected to perform this work.  There have been complaints that the
> tools are too hard to use and that they cannot be used to produce one of
> the required outputs:  man pages.

> There have been suggestions made that other tools are better suited for
> this effort including:

>  * POD files
>  * DocBook
>  * HTML

> Of these my preference is either POD or DocBook.  I prefer DocBook
> because it has been used extensively by other open source projects to
> generate both man pages and online documentation.

> I like DocBook because it can be used to produce Windows HtmlHelp files
> as well as HTML and PDF.

I think it's worth separating the format discussion somewhat between the
man pages (aka the Administrators Reference Manual, since that's pretty
much what that manual could be turned into and since it's already in a
man-like format) and the other documentation such as the install and
user's guide.

POD is inappropriate for the install and user's guide and I would never
suggest its use for that sort of a manual.

DocBook could do all of these, certainly.  I will argue for POD over
DocBook *only* for the man pages, solely on the grounds of ease of editing
the raw source.  DocBook, being XML-based, suffers from the standard XML
editing problems, and while those problems can be dealt with, I know that
I personally can proofread and edit POD several times faster than DocBook
and it's more amenable to simple tools like vi.  I think this is a fairly
compelling argument, although I do understand why people might want to use
DocBook.

Another nice argument in favor of POD is that most of the work is already
done, although I expect the conversion script could be adapted to DocBook.

Speaking from a somewhat biased position as the maintainer of the POD to
man conversion tools, I also believe that POD produces noticably better
nroff than DocBook, resulting in nicer formatting in the final man page.

I only have a strong preference for the man page format; for the regular
manual format, I'm happy to help with whatever format people find the most
appealing.  I know TeX, I know DocBook somewhat, I know HTML, and I know
texinfo, and I'm willing to help edit documents in any of those formats.
Going from straight TeX or LaTeX to man pages is not something I'd like to
attempt, though.

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