[OpenAFS-Doc] docbook conversion update

[Russ Allbery]

"chas williams - CONTRACTOR" <chas@cmf.nrl.navy.mil> writes:

> it doesnt bother me as long as you preserve enough information to
> convert back to docbook meaningfully so a full hardcopy of all the man
> pages can be printed.  this means keeping the index information.  pod
> does have some support for this with via X<>.  it cant handle the
> primary/secondary index terms but judicious use of commas would probably
> be sufficient.

I'm personally not horribly interested in this.  What matters to me is
having really solid man pages; I don't find that sort of index to be that
useful, or printing out large sheafs of man pages that useful.  That being
said, you can certainly get good printed output via nroff, and it
shouldn't be too difficult to do a translation to DocBook.

For the sort of index entries that are actually useful, I doubt you want
to use X<>; indexing the page names will give you 90% of what's actually
of interest for the man pages.

> refentry looks complicated at first, but its not too awful.

No, refentry really is awful in my opinion; I've used it.  XML is not a
good language for humans to work in.

> pod seems more procedural, like *roff, instead of being a true markup
> language.  but for man pages, i dont think that really matters.

It's *so* much easier to use.

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