Re: [Groff] manpages, manpages everywhere

[Larry Kollar]

Meg McRoberts wrote:

> ... having been on the writing end of the game, I am astounded at
> how many API writers (ergo, programmers themselves) seem to have no idea
> how to document a function/routine/system call.  The big challenge is 
> that
> one really needs examples, but it's not always easy to come up with a 
> small
> code fragment that really illustrates how the function is used and it's
> inordinately difficult to maintain those code fragments in the 
> documentation
> over time.

Way back when, I documented a GKS-style graphics library.
Examples were easy to come by for many of the functions,
because I wrote a couple of demos to get a feel for how to
use the library. I tried to include at least a trivial example
for each function.

I'm not sure how maintaining the code fragments would be
a problem, unless the function itself was evolving (and as
you know, documenting a moving target is a tech writer's
nightmare). Maybe loom would be useful if you're extracting
examples from a working program... I kind of wish I'd thought
of it myself when I was documenting that API.


> The big problem I have these days is the different section names 
> between Linux
> and UNIX systems.  Sections 1, 2, and 3 are the same for both but what 
> is 1M
> on UNIX is 8 in Linux and I still have to look up with 4, 5, and 7 are 
> for
> Linux -- they are mixed up from what they are on UNIX.  I'm documenting 
> products
> that run on both UNIX and Linux and a single manpage could easily serve 
> both
> platforms except for the bloody section numbers.  I can do common 
> source for
> the two but it's a bit of a chore and you have to do separate builds.

Huh, I didn't realize that. I think the BSDs are very similar
to Linux in section usage. Maybe it's SysV that went its own
way? Anyway, if it's only the section numbers that change,
that shouldn't be too hard to set up & control via make.

I can relate about the common source, but I'd rather do that
than maintain two (or more) separate doc bases -- having
done it both ways, I know which one *I* prefer. At least *roff
makes it easy to do, easier than FrameMaker anyway (which
itself is magnitudes more suited than Word for that kind of
thing).

I also had a look at the SCO sites you suggested... I think I
like the mnemonic section names. It's too bad that Linux didn't
do something similar, although you'd still be in the same boat
you are now. :-)


But I digress. What I was getting at was that if you look at
documentation for a product with an embedded command
line, it's without exception a set of manpages -- perhaps
with different heading names and decorative changes, usually
using something other than *roff these days, but in all this
time nobody has come up with a better way to do it.

--
Larry Kollar        k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
Unix Text Processing: the Revival
http://www.alltel.net/~kollar/utp