Subject: Linux-Activists - DOC Channel digest. 93-2-2-21:20
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Wed, 3 Mar 1993 02:43:49 +0200

Topics:
	 Re: Man Project
	 Re: Man Project/ texinfo vs. man
	 Re: Linux-Activists - DOC Channel digest. 93-2-2-14:2
	 Man pages
	 TCP/IP documentation

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

From: [email-masked] (Michael K Johnson)
Subject: Re: Man Project
Date: Tue, 2 Mar 1993 20:12:31 +0200

   From: [email-masked] (Michael Haardt)

   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.

Not in the least.  Man pages are worth putting up.  I can say that,
since I do the work... ;-)  I created tsx-11's .../docs/man/ directory
about a year ago, and it's nice to see it will finally get some use.

michaelkjohnson

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

From: [email-masked] (Steven Dick)
Subject: Re: Man Project/ texinfo vs. man
Date: Tue, 2 Mar 1993 20:59:30 +0200

On Feb 24,  8:37pm, Michael Haardt wrote:
[...]
} > 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,

huh?  I thought 'makewhatis' did this kind of thing...

Personally, I use the perl man package.  It contains a makewhatis that
is more complete and robust than any other that I've seen.  (The same can
be said for the man page reader itself.)  If you want, I'll give you
an ftp site to pick up the original package.  I don't have it handy at this
instant.

} 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?

I've had a minor disagreement/discussion with people within the FSF on this 
point as well.  Upon further thinking, I partially agree with them.  My
personal conclusion was that:
  1. Man pages are an excellent cross reference, especially when they are no
     more than 2 physical pages, preferably closer to one physical page
  2. TeXinfo is a much better medium for documentation for exceedingly long
     document files.  Good examples of this are the Perl TeXinfo file and
     the Taylor UUCP TeXinfo file.

My feeling is that there should be a man page for _every_ command and function.
For more complicated items, there should also be a texinfo file, and the
man page should definately refer to the texinfo file.  For large libraries,
it should be possible to pick up the function prototype from a man page,
and the verbose description of the family of functions from the info file.

This may or may not be appropriate for all packages.  Again, Taylor uucp
demonstrates this pretty well.  The info file describes the package as a whole,
and has many internal cross references, which would be a pain in a man page.
Each individual command has its own man page describing options and general
workings.  (It might be nice of more of the man pages were duplicated in the
texinfo file, though.)

	Steve
[email-masked]
[email-masked]

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

From: Rik Faith <[email-masked]>
Subject: Re: Linux-Activists - DOC Channel digest. 93-2-2-14:2
Date: Tue, 2 Mar 1993 22:03:41 +0200

"Linux Activists" wrote (Tue,  2 Mar 1993 19:42:40 +0200):
> 
> From: [email-masked] (Michael Haardt)
> Subject: Re: Re: Man Project
> Date: Wed, 24 Feb 1993 20:37:58 +0200

[stuff deleted]

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

I did both sd(4) and man(7).  They are both in docs/man/rik-man.tar.Z on
tsx-11, along with all the man pages I've written before January 11.

I've written a lot of the man pages for Linux-specific utilities and try to
forward them to the author of the program, as well as distribute them with
my util*.taz and util*.src.tar.Z packages (which, BTW, contain most
standard Linux-specific utilities, ALL WITH MAN PAGES -- the development
stuff [like for networking, mail, daemons] is not included).

***************************************************************************

The best way to get man pages written is to just write them.  It is very
unlikely that someone else will be duplicating your work.

Would it help things if I agreed to set up a man tree on ftp.cs.unc.edu for
the man page project and had everyone send me man pages when they were
finished?  If I did this, I'd like to maintain *ONLY* sections 2, 3, 4, 5,
7, and 9.  All programs (section 1), games (section 6), and system
utilities (section 8) should have man pages bundled with the binary.  (I
think it would be silly to maintain copies of section 1, 6, and 8 man pages
which might diverge from the binary distributions.  These man pages should
be written and given back to the authors, where necessary, as has already
been discussed on this channel.)

Is there already a man page coordinator?  I don't want to step on any toes. . .

Also, note that I am only talking about MAN PAGES.  I don't want to get
into a man vs. texinfo flame war.  *I* am interested in man pages, have
written a bunch of man pages, and want more man pages.  Those interested in
doing texinfo should go ahead an do it.  It seems that this "how should
Linux be documented" discussion just goes around and around.  I really
don't much care how the documentation comes, as long as I have it online.

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

From: Matt Welsh <[email-masked]>
Subject: Man pages
Date: Tue, 2 Mar 1993 23:55:04 +0200

Michael Haardt sounds gung-ho to do man pages. :) Unless he (or anyone else)
objects, I'd like him to take care of the man page project for now.
A few others have expressed interest, including Ian Jackson 
([email-masked]). Since I don't have time right now to deal with
man page issues, if Michael and/or Ian wants to take care of it, please
do.

I think Michael had some good ideas--- you should send out your man page
template (possibly with some short instructions on formatting using groff).
Apropos or makewhatis should be able to generate the listing of man pages
in a given section, for use by man -k. 

I contend that each section of man pages should be in a seperate tar file
and kept in ALPHA/doc-project on nic.funet.fi until a given section is
ready. This file should contain all of the nroff sources for the man pages
in that section so we can just drop it into /usr/man. You can also
generate an index file (as above) which will be nice so we can keep track
of what man pages are there and what needs to be written.

When man pages are ready to be released we can put them up on tsx-11 and
sunsite. tsx-11 seems to mirror to more places. The man page collection
filenames should be obvious: so we should end up with
	man-1.tar.Z (or .z, if you want to use gzip)
	man-2.tar.Z
	man-3.tar.Z 
and so on.

Before a section is released I'd like to see it in ALPHA/doc-project first,
and then it can be uploaded after we've all had a chance to take a look.

Please let me know what you think about this. I'd cc this to Michael Haardt
but "[email-masked]" doesn't seem to be fully qualified. Please send
me your address. I'd like for someone to take care of the man pages and
one or more other people to handle individual sections.

Thanks!
mdw

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

From: Matt Welsh <[email-masked]>
Subject: TCP/IP documentation
Date: Wed, 3 Mar 1993 00:01:50 +0200

I'm in the process of writing up the LDP "Manifesto". :) This will
just keep tabs on where we are, what exactly we're doing and how, include the 
addresses of everyone involved, etc. I need to have these organizational
things worked out...

Olaf Kirch proposed that we split the system admin's and networking
documentation. I think this might be a good idea--- add another manual
to our set, "Linux Networking Setup Guide". This would allow Olaf to
take care of the issues of coordinating that manual. True, networking 
IS system administration, but we don't want 2/3 of the system admin's guide
to be on UUCP and TCP/IP. 

I suggest that we have an intro chapter to TCP/IP configuration (the
simple stuff, more or less cooked from the NET-FAQ) in the System Admin's
guide, with pointers to the Networking Setup Guide. That way the
information can be maintained seperately, with basic overview and TCP/IP
setup (the required stuff) in the system admin's, with more in-depth
coverage by Olaf in the network setup. 

What does everyone think? If this is a bad idea we'll just allocate more
chapters in System Admin's for all of the networking stuff, but most real
UNIX systems have a seperate networking guide with overview in the system
admin's.

mdw

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

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