[OpenAFS-devel] man pages: a modest proposal

[Derrick J Brashear]

Currently we have only "catman" man pages which are out of date and not
very useful. It would be more desirable to have some source format to
maintain that man pages can be generated from (presumably at release time
so people don't need whatever tools installed to get man pages)

During an off-line discussion earlier Jeff Hutzelman found:
http://www.pixware.fr/download/aptconvert.tgz

which looks like it could be used to convert existing text to something
which could then be used to bootstrap a man page infrastructure. (It can
convert to LaTeX, PS, PDF, HTML, SGML or XML/DocBook, RTF)

We also have HTML documentation from IBM, also out of date. 

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?

-D