Subject: Linux-Activists - DOC Channel digest. 93-2-9-18:28
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Wed, 10 Mar 1993 00:35:51 +0200

Topics:
	 Man pages: Summary with man page template
	 ANNOUNCE: *DEVELOPMENT* man page directory trees now set up

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

From: [email-masked] (Michael Haardt)
Subject: Man pages: Summary with man page template
Date: Tue, 9 Mar 1993 14:26:00 +0200

There were too many articles for individual responses, sorry.

The program to generate index files is called makewhatis(1).  I have two
versions, none of them works really well.  The perl man package is said
to contain a well working one.

                            ----------

Rik offered same as me, setting up an ftp directory for easy access of
manual pages and central storage of the current experimental version.
Since his site is in US and most probably better than the poor small vax
in Cologne, I think this is decided.  I already mailed him my current
set of manual pages.

I agree to the mentioned way of having *one* central archive for the
current, experimental and exploded tree.  From time to time it could be
packaged up and moved to the official places, packed as one tar file
containing man[23457] (plus cola announce).

Since Rik will run this archive, I think he just got the current
maintainer of manual pages.  Congratulations! :)

I see no more needs for extra maintainers, it just creates more
confusion.  Using the above way, you look at the archive and write
missing pages or update pages, sending the new files to Rik.

Matt, I don't know of there is already a FAQ about this channel, but I
think we could need one, telling about ftp addresses (with IP#,
PLEASE!!) and directories, the existing man(1) packages (just where to
find them plus maintainer), email addresses and such things.  Instead of
authors (coauthors, people providing later fixes...) of the pages at the
head of each page, the FAQ can contain authors in general to keep pages
short.  Ok?  I hope that some more people start helping with manual
pages if they see a FAQ, an existing archive etc.

                            ----------

A last word from me about roff and info: info will never (== next few
years) make roff obsolete, caused by the mass of roff pages floating
around.  Personally, I think that having one documentation system is
great, and that will be info.  As Nick already said, a roff2info
converter is a good solution.  Unfortunately, I lost his email address :(
Since there already is info2roff, I don't see any problems with people
who prefer roff.  (like me)

                            ----------

I use the folding editor Origami for writing manual pages, the .\"{{{
and .\"}}} are folding marks.  I will omit the usual advertising of
folding editors today :)  Please leave these marks inside.  I think my
current template is ok now, so here it is:

----------------------------------------------------------------------
.\' X
.\" where X can be e (eqn), r (refer), t (tbl) or v (vgrind)
.\" This man macro manual was first written by Tom Christiansen
.\" and posted to comp.unix.misc
.\"{{{}}}
.\"{{{  Notes
.\" All literals should be written using a \fBbold\fP fonts, all
.\" variables using a \fIitalic\fP font.  Remember the following
.\" characters: 
.\"
.\"  \e    backslash
.\"  \-    Minus
.\"  -     Hyphen
.\"  \(en  En-dash, typically used in things like "page 11\(en15"
.\"  \(em  Em-dash
.\"
.\" Don't use quotes in the usual text for god's sake, italic and bold 
.\" are better to read and you have to define strings for opening and 
.\" closing quotes to keep nroff and troff output nice.
.\"}}}
.\"{{{  Title
.TH NAME SECTION DATE SOURCE MANUAL
.\" NAME should be all caps
.\" SECTION should be 1-8
.\" DATE is optional and should be like "January 1, 1970"
.\" SOURCE is optional, e.g. GNU
.\" MANUAL is optional, e.g. "LINUX Programmer's Manual"
.\"}}}
.\"{{{  Name
.SH NAME
.\" shouldn't that \- be an \(em ??
foo, bar \- programs to do something
.\"}}}
.\"{{{  Synopsis
.SH SYNOPSIS
.ad l
.\" commands only
.B name
.RB [ \-option ]
.RB [ \-option
.IR parameter ]
.I file ...
.\" C functions
.nf
.B #include <something.h>
.sp
.B int foo(int bar);
.fi
.\" both
.ad b
.\"}}}
.\"{{{  Config
.SH CONFIG
This section explains how a device is configured: major/minor numbers,
their meanings and the meaning of the device name.
.\"}}}
.\"{{{  Description
.SH DESCRIPTION
long drawn out discussion of the program.  It's a good idea
to break this up into subsections using the .SS macros, like
.SS "Section Selection"
To seperate a paragraph, use 
.PP
Don't use .LP, it isn't part of all man macros.
.SS "Online Problem Reports"
.\"}}}
.\"{{{  Options
.SH OPTIONS
.IP \fB\-option\fP
Some people make this separate from the description.
.IP "\fB\-option\fP \fIfile\fP"
You can also use .TP, but I like .IP much more. 
.\"}}}
.\"{{{  Return value
.SH "RETURN VALUE"
What the program or function returns if successful.
.\"}}}
.\"{{{  Errors
.SH ERRORS
Return codes, either exit status or errno settings.
.\"}}}
.\"{{{  Examples
.SH EXAMPLES
give some example uses of the program
.\"}}}
.\"{{{  Environment
.SH ENVIRONMENT
envariables this program might care about
.\"}}}
.\"{{{  Files
.SH FILES
all files used by the program.  typical usage is like this:
.nf
/usr/man	default man tree
/usr/man/man*/*.*	unformatted (nroff source) man pages
.fi
.\"}}}
.\"{{{  Conforming to
.SH "CONFORMING TO"
SVID [EXT], AT&T, POSIX, X/OPEN, BSD 4.3
.\"}}}
.\"{{{  See also
.SH "SEE ALSO"
other man pages to check out, like man(1), man(7), makewhatis(8), catman(8)
.\"}}}
.\"{{{  Notes
.SH NOTES
miscellaneous commentary
.\"}}}
.\"{{{  Warnings
.SH WARNINGS
things to take special care with
.\"}}}
.\"{{{  Diagnostics
.SH DIAGNOSTICS
all the possible error messages the program can print out, and
what they mean.
.\"}}}
.\"{{{  Bugs
.SH BUGS
things that are broken
.\"}}}
.\"{{{  Restrictions
.SH RESTRICTIONS
bugs you don't plan to fix :-)
.\"}}}
.\"{{{  Author
.SH AUTHOR
who wrote it (or AUTHORS if multiple)
.\"}}}
.\"{{{  History
.SH HISTORY
programs derived from other sources sometimes have this.
.\"}}}
----------------------------------------------------------------------

Any comments?

Michael ([email-masked])

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

From: Rik Faith <[email-masked]>
Subject: ANNOUNCE: *DEVELOPMENT* man page directory trees now set up
Date: Tue, 9 Mar 1993 20:27:05 +0200

Tue Mar  9 13:05:50 1993

This document describes ftp.cs.unc.edu:/pub/faith/linux/man.{bsd,linux}

NOTE: This project deals *ONLY* with section 2, 3, 4, 5, 7, and 9.
      Do *NOT* send me man pages for other sections.
      Do *NOT* send me info pages.
      Do *NOT* start a man page vs. info page flame war.
      The point is to *WRITE* initial documentation, not to fight about it.

Section 2 = system calls
Section 3 = libc calls
Section 4 = devices (e.g., hd, sd)
Section 5 = file formats (e.g., /etc/wtmp, /etc/passwd)
Section 7 = macro packages, etc. (e.g., nroff, ascii)
Section 9 = internal kernel routines (for kernel hackers)

The man.bsd directory contains man pages from the 4.3bsd-reno distribution,
as found on wuarchive.wustl.edu:/mirrors/4.3bsd-reno.
These man pages can provide a starting point for starting work on the Linux
man pages.  The idea is that you would pick up a man page that you want to
work on.  Work on it.  And then send it back.

man.bsd.DATE.tar.z is this complete tree in gzip tar format.

The man.linux directory contains man pages which have been specifically
modified for Linux.  This usually means that someone actually read the man
page and checked out the current Linux source (kernel or library).  Most of
the man pages present were written by Michael Haardt
([email-masked]).  I encourage other people to
email me new Linux-specific man pages.

man.linux.DATE.tar.z is this complete tree in gzip tar format.

STANDARDS:

1) Whenever you modify a man page, add a timestamp and your name.
2) Change the date: for BSD man pages, this is the .Dd macro.
                    for normal man pages, this is part of the .TH macro.
3) Change the OS: for BSD man pages, for example, put "Linux 0.99" after .Os
                  for normal man pages, this is part of the .TH macro.
4) See man(7) for more details on how to write man pages from scratch.
5) Please keep the introductory parts (.TH, NAME, SYNOPSIS, etc.) *very*
   standard -- these parts are used by makewhatis to make the whatis
   database. 
6) If you are not sure of some behavior, state that: the initial man pages
   don't need to be complete, they just need to be correct.
7) Send new man pages (one at a time)  and corrections to [email-masked]
8) If you have dozens of man pages, please send uuencoded, gzip'd tar files.

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

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