From: "Linux Activists" <linux-activists@Niksula.hut.fi>
To: "Linux-Activists" <linux-activists@Niksula.hut.fi>
Reply-To: "Linux-Activists" <linux-activists@Niksula.hut.fi>
Subject: Linux-Activists - DOC Channel digest. 93-1-24-7:11
Sender: owner-linux-activists@Niksula.hut.fi
Message-Id: <93Feb24.115025eet.62231-3@niksula.hut.fi>
Date: Wed, 24 Feb 1993 11:50:22 +0200
Status: RO


Topics:
	 Re: Man Project


----------------------------------------------------------------------

From: Matt Welsh <mdw@TC.Cornell.EDU>
Subject: Re: Man Project
Date: Wed, 24 Feb 1993 09:06:38 +0200



> I was just wondering what was happening in the world of man pages, and what
> the relationship is (if any) between the Kernel documentation and the
> notable lack of man pages for section 2.

I was going to send out something on the direction we might want to head
for man pages soon. I guess I'll go ahead with this, although I think
man pages are, at this point, and auxilliary concern until we get the
Alpha versions of the books ready. 

If a subset of folks on the Doc Project want to start working on 
man pages (I know some already are) please let me know. I want to get this
shoe on the road. :)

Here's what I think we need to do with man pages. First, we need to get
all of our ducks in a row. This means have FTP space (ALPHA/doc-project
on nic is the best bet) in which we keep the "official" collection of
Linux man pages, which the LDP (that's us) is supposed to be handling.

We should keep man pages in sets by section number; that's obvious:
man-1.tar.Z, man-2.tar.Z, and so on. Once a particular section is ready
for release we upload it everywhere: eventually I want there to be a
"man" subdirectory under "docs" on the major Linux FTP sites.

It is not feasible or desirable for us to try to accumulate all of the
section 1 (user/application commands) man pages. Since responsibility
individual programs is so widely distributed, we should make it the job
of whoeever is releasing a program to provide their own man(1) pages.

The LDP should, however, manage a subset of man(1) pages--- those being
the Linux-specific setup programs, such as mkfs, fdisk, and so on. I suppose
that most of these will actually go in section 8. However, we should keep
in mind that some section 1 pages will fall into our domain and we should
handle those. I don't even want to take care of man pages for Rik Faith's
util distributions--- those man pages are both written by him and by the
GNU folks. Instead of the LDP running around trying to keep track of the
most recent version of all of the man(1) pages out there, we just won't
provide them ourselves. Man(1) pages will come from the individual
programs and accumulated on any major release (such as SLS), but won't be
available seperately from us. What does everyone think about this?

For all other sections, we should start gathering all of the man pages
we can, putting them into sets, and uploading them to ALPHA/doc-project.
There should be two files for each section: a tar file containing all of
the man pages (roff source only) as well as another file giving a listing
of all of the pages in the set (i.e. an apropos listing of the "NAME" line
in each page). 

Then we simply go down the lists, see what pages need to be written, and
write them. Whoever maintains each section will accumulate them, tar them
up, and upload them periodically. For example, Michael can take section 2,
and whenever someone writes a section 2 page, they mail it to him. He'll
add it to the man-2 set and upload it.

I don't think man pages should be too difficult to churn out. Almost all
of the man(3) pages are written by the GNU folks. man(1) isn't for the
most part our concern. HOWEVER I think we on the LDP should volunteer to
help write man pages for new packages as they come out. For example,
if someone releases a program for Linux with missing/insufficient man
pages, it would be nice for the "experts" here to write a man page and mail
it to the author of the program so they can include it with the next 
release.

Any ideas or suggestions? I'm not taking man pages to be priority right now,
but I do want to gather the Linux-specific man(8) pages (fdisk, fsck, etc.)
and make those available. There are a number of these system programs out
there that are so basic that no single party releases them. We should also
offer to write man pages (for any section) for programmers who don't have
time to write them for their own softs (take for example: xiafs, poeigl, etc).

The man pages we will take care of will mostly be those inherent to the
Linux system: sections 2, 3, 4 (important!), 5, 7, and 8. Although many
section 8 pages are handled by individual programmers, I think they're more
or less standard across the board. We can worry about the details later.

So, does anyone want to volunteer? I want to concentrate on the books
for now. However, I know there are folks out there who want to do 
something NOW, and would rather do man pages than write books. If you'd
like to volunteer to head the man page project, or volunteer to coordinate
a particular section of the manual (from those listed above), let me know.
The coordinator of each section will basically just accumulate all of the
pages for that section (and write some, we hope). :) 

Also: I can write up a quick tutorial on writing man pages if you've
never done it before. It's very easy and groff works great under Linux.
See man(7) on your system if you have it.

mdw




------------------------------

End of DOC Digest
*****************
-------

.