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

[ted creedon]

I didn't select the format - the users did after a mailing list discussion.

Anyway, I have documentation that suits my needs and others in the afs
community. Sounds like there will be 2 or 3 source formats to keep in sync.

Feel free to produce what you will. I have something I can edit and will
share it with the community either on SourceForge or elsewhere if not on the
afs site.

Keep me posted about content changes.

tedc

-----Original Message-----
From: openafs-doc-admin@openafs.org [mailto:openafs-doc-admin@openafs.org]
On Behalf Of Russ Allbery
Sent: Monday, June 27, 2005 2:17 PM
To: openafs-doc@openafs.org
Subject: Re: [OpenAFS-Doc] Final (from Latex) pdf's and html's available

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/>
_______________________________________________
OpenAFS-doc mailing list
OpenAFS-doc@openafs.org
https://lists.openafs.org/mailman/listinfo/openafs-doc