Re: [Groff] manpages, manpages everywhere

[Meg McRoberts]

Sorry I didn't respond sooner -- I was out of town for a few days.

--- Larry Kollar <address@hidden> wrote:

> 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).

I was documenting the kernel functions and structures used for
implementing device drivers.  So meaningful code examples included
lots of general kernel stuff in addition to the specific API and
all of that stuff is constantly evolving between releases.  The
most egregious example happened before I joined SCO.  The first
releases of SCO UNIX that included STREAMS took the SysV STREAMS
interface and used it without modification, so they also took the
SysV STREAMS documentation and used it without modification.  The
code examples were full of entry points and functions that didn't
even exist in our kernel.

> 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.

I'm not familiar with loom -- I should look into it.

> 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'm a writer more than a tools person, but it seems nontrivial
to handle this through make -- it's not just the page name but
all the cross-references embedded in the text that have to be
handled.  It's probably doable if one is satisfied with handling
90% of the doc, which is reasonable.  There are always a few
anomolies along the way -- some stuff that goes into the "drivers"
section on one system is in "miscellaneous" on another, some systems
have a "signals" page in the miscellaneous section to list all the
signal numbers whereas others list them on the signal(2) or other
system call page.
> 
> 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.

Yup.  I don't think anyone who has tried to maintain the same info
in two different places has much good to say about the experience.

> 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).

Ah yes, *roff certainly works better than the alternatives!
> 
> 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. :-)

Yes, I did a consolidated doc set for the driver interfaces on SCO OpenServer
(aka SCO UNIX) and UnixWare (aka the outgrowth of the original SysV) so had to
deal with the section name incompatibilities.  The mnemonics were kind of nice
as long as one stuck with the basics -- commands, files, routines.  It got
gnarly as sections proliferated -- I never could remember what PADM versus ADMP
were, for example.

It seemed that whichever system one learned first was the one that made most
sense and I first learned manpage sections at Bell Labs in the 80's.  I like
the numeric system, then you can use lowercase mnemonics for subsections.
For example, if 1M are the administrative commands (require superuser 
privleges),
the 1Mtcp can be administrative commands for TCP.
> 
> 
> 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.

You are quite right.  There are, of course, drawbacks to the manpage format
but in general it is quite elegant, especially when done right.  

Meg

__________________________________________________
Do you Yahoo!?
Yahoo! Shopping - Send Flowers for Valentine's Day
http://shopping.yahoo.com