man pages

[Stuart Burnfield <slb -at- FS -dot- COM -dot- AU>]

Hi John -

I seem to recall there's an O'Reilly book that covers nroff and troff.
If so, I recommend it sight unseen. All the O'Reilly UNIX books I've
seen have been excellent. I can't check it out right now but you should
be able to find out from their Web site.

I also recommend their 'UNIX in a Nutshell' book. It has three chapters
on nroff/troff, the macro packages, and the preprocessors. The Nutshell
book is absolutely indispensible if you expect to work with UNIX
commands, shells and editors.

Some advice: as with programming languages, it's possible for different
people to achieve the same effects in nroff using very diferent styles.
I updated several man pages that had been written and maintained by three
people. They were a real mishmash of styles and very hard to follow. By
contrast, another set of man pages written by a fourth person were a
delight -- clean and simple. The difference was that they were new, and
so only had a single author.

So, if you'll be maintaining man pages from several authors, give some
thought to how you'll keep them reasonably consistent. An standard
macro library, a style guide, and some templates or skeleton pages
would be a good start.

If you're doing all the writing and tagging, then of course you can use
whatever tools and tags you like.

This problem i why I'm interested in using Frame to maintain our man
page set. If the filters are good (I haven't tested them thoroughly)
I can take our existing messy pages and maintain them centrally.

Finally, you might want to check out PolyglotMan (formerly called
RosettaMan or rman). It's a man page filter that supports lots of useful
formats (HTML, SGML, LaTex, ASCII, . . .) I think you can get it (and
a swag of other HTML converters) from:

        http://ann.nrg.com.au/nrg/sites/htmlconvert.html


Regards
---
Stuart Burnfield                "Fun, fun, fun
Functional Software Pty Ltd     In the sun, sun, sun. . ."
mailto:slb -at- fs -dot- com -dot- au