Re: [Groff] manpages, manpages everywhere

[Meg McRoberts]

> Yes. And when you look at API references written by people who obviously
> have never read a section three man page, you almost always find them vastly
> inferior to an average man page.

Indeed!  But 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.  I always thought it would be cool if the API came with some big
code samples and one could just click from the manpage to the section of code
where it was called, then scroll around to see more of the context...

But you're right -- the man page format is pretty good.

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.

meg

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