[OpenAFS-devel] man pages: a modest proposal

[Russ Allbery]

Derrick J Brashear <shadow@dementia.org> writes:

> The question is, what format should we be using for the master copies of
> documents? Assume it's desirable to at least be able to generate man
> pages for e.g. afsd, fs, vos, bos, pts, kas, etc...

> Right now the answer would seem to be one of the DocBook formats. Does
> this sound like a reasonable proposal? Is this another project for my
> "copious spare time" or does anyone have an interest in doing this?

I'm a big fan of the principle that the person who wants to do the work on
the documentation should pick the format, and I don't have time at
present, but let me suggest POD as something to think about.  It has the
advantage of being very close to plain text which would make it pretty
easy to convert the existing catman pages into it, and it generates pretty
good manual pages (that being what the converters are designed to do).

I find it a lot easier to work with than DocBook, although it's not as
formal and fully specified.

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