Subject: Linux-Activists - DOC Channel digest. 93-2-2-14:2
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Tue, 2 Mar 1993 19:43:43 +0200

Topics:
	 Re: Re: Man Project

----------------------------------------------------------------------

From: [email-masked] (Michael Haardt)
Subject: Re: Re: Man Project
Date: Wed, 24 Feb 1993 20:37:58 +0200

> From: Matt Welsh <[email-masked]>

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

Last time I simply uploaded man2 to tsx-11.  I have access to an ftp
server in Cologne, Germany, due to the very friendly people there.  If
there are any people willing to help me, I could even provide weekly
upgrades which would be tiring to the tsx-11 maintainer I guess.

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

Agreed.  Let me add that I would like to see *one* site and all others
only mirroring it.

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

I don't know to who I said what with so much mail, but that was about my
strategy as well.  If there is a source code, then there is an author
who is responsible for the documentation.  Everybody who has the desire
to improve documentation to source code should contact the author or
current maintainer, e.g. you may find my name in some pages here and
there, but that's all.  The page is still only contained in the package.

It is *not* our task to document e.g. SLS, but Peter McDonald has the
task to grab all manual pages for the software he packages up, and
provide them.  Almost all *are* documented.

> 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 think that is not neccessary, if we work as above.  We could write
manual pages, however the author or current maintainer collects the
documentation, like Rick Faith does with many utilities right now.

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

I disagree here.  I think the manual pages alone are better, plus a
program to generate such an index.  Ok ok, I don't have such a program
and never saw one which really works, but that doesn't mean that it
can't be written.  You will need such a program anyway if you are going
to install additional manual pages.

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

That means we need n-1 other maintainers for roff pages, n being 8 or 9
depending on your taste.  I doubt there is much in other sections than
2, so if nobody else feels like called by heaven to do it, I will
maintain the other chapters as well.  (And if you feel so: Tell us LOAD
enough, and a mountain of work will happily run to you:)

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

Yes, they are documenting the whole GNU library using texinfo as far as
I know.  Like it or not, that's the way it is.  Nick, any further
comments?

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

Oh yes, I forgot section 4 in my former request for help.  Rick Faith
wrote a nice scsi(4) page, didn't you Rick?  It shows very nice how
manual pages about devices should be written--please release it, I seem
not to have saved it :(

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

And, as I said, I have a template which I use for writing.  It is just a
file where you insert the text and delete what you don't need.  I
already found quite some people who like to use it.  I would however
like to improve it a little (after reading the scsi(4) page which I
miss) before I release it to this channel.

I think a biweekly FAQ article containing an abstract of the used policy
with names and email addresses could help a lot, or perhaps even posting
to c.o.l.a.  It should be short enough for people to read it.

Michael

------------------------------

End of DOC Digest
*****************
-------