deb wrote:
> It has recently come to my attention that there are a -large- number of
> Linux programs/commands that do not have man pages. As many of you know,
> man pages are the first place that most people look when they need help
> and documentation. In the most recent release of RH, for example, there
> are 744 such man pages that are missing. This, in my opinion, is a big
> problem.
>
> So, in an effort to do some good and to give some of you a chance to get
> your feet wet in the open-source documentation world, I've initiated a
> project (with the uninspired title "Man Page Project") to get these man
> pages written, converted to the appropriate format, and sent off to the
> appropriate people.
This is a fine idea, but I'm not certain it is the right one.
I like the idea of man pages. Methinks distributing any Unix program
without them is a mistake. On the other hand, AT&T at one point shipped
System V without them, providing a "user-friendly help system" instead,
and the GNU project long ago dropped them in favour of info format
documentation. I think both those decisions were serious errors, and
I'm likely not alone, but that doesn't matter much.
For a 1970's design design, man pages were wonderful. Available online
or printed (I'd been using Unix for weeks before I discovered that
printed manuals existed), with an effective system of cross-references.
To me, those are basic criteria for any worthwhile documentation, and
I'm continually amazed that people still produce things that don't
meet them.
But we've got some man pages, some info docs, LDP docs mostly in SGML,
some mini-HowTos in HTML, various web documents also in HTML, no doubt
some XML and TeX somewhere in the mix, ...
And we need a common format. You are absolutely right on that point!
But I think that format should be HTML, not nroff man pages.
If FSF say they'll maintain the info docs but not man pages, then an
automatic info2man tool makes sense (does one exist?), but manually
writing man pages doesn't, at least not for any program that changes
much.
There are open source man2html tool and info2html tools already out
there. We use man2html in FreeS/WAN; it works fine. One of the formats
that the LDP's SGML can be output as is HTML. I think there's a
Latex-to-HTML tool available.
We can likely build a more-or-less complete HTML documentation suite
by translating all the existing stuff. Then point writers at the gaps.
For many of the newer users, this would be an easier format to use
than man pages, and it becomes easier to put on the net. Put the
whole thing up on OSWG or LDP and let folk browse?
Of course automated translations may not get the crosslinks right,
or build indexes, or ... We'll need tools for that. I'll volunteer
some effort on that, small awk or sed scripts to jiggle formattting.
If major work is required I may not have the skills and am almost
certain not to have the time.
