rdh@sun.uucp (Robert Hartman) (10/22/86)
A while back I posted a request for comments regarding
standards for man pages. Sorry for taking so long in posting
the results, but an urgent project came up that has been taking
up all of my time. Then I had problems with the news software that took
me a while to figure out, then ...
Anyway, here is a summary of the comments I received so far.
There were only about half a dozen respondents. A couple of people
sent style guides and templates. There are also some more general comments.
I'll be posting my suggestions for new standards in about a month. -bob.
----------------------------------------------------------
From goldberg@russell.stanford.edu Fri Aug 22 12:13:12 1986
Organization: Stanford University, CSLI
...
I would very much like to see and "EXAMPLES" section added to
...
-Jeff Goldberg
ARPA: goldberg@RUSSELL.STANFORD.EDU
UUCP: ...!hplabs!russell.stanford.edu!goldberg
From gatech!gitpyr!robert@seismo.CSS.GOV Fri Aug 22 20:02:13 1986
Organization: Office of Computing Services, Georgia Tech
...
I'd like to see is a more intelligent keyword generator so
that "man -k <keyword>" worked a little better. A cross reference
generator would be nice too, especially if it is used to automate the
creation and updating of the "SEE ALSO" section in each manual page.
robert
--
Robert Viduya 01111000
UUCP: ..gatech!gitpyr!robert
BITNET: CC100RV @ GITVM1
------------------------------------------------------------
From decwrl!ihnp4!hsi!stevens Mon Aug 25 12:29:57 1986
To: rdh@sun.uucp
Subject: Re: man pages and formatting standards: request for comments
...
I would personally
like to replace all the italic fonts on a manual page with a constant
width font.
...
I was surprised to see that Kernighan and Pike, after using a constant
width font throughout their book, go ahead and stick with the old
italic style in their manual pages. I would like to replace the
program names in the text and any program examples with a constant
width font, and replace the bold stuff at the top (function calls
with all arguments for Sections 2 & 3, for example) with a bold
constant width font.
Richard Stevens
Health Systems International, New Haven, CT
ihnp4 ! hsi ! stevens
------------------------------------------------------------
From rdh Mon Aug 25 13:55:59 1986
I agree with you. There is, however, a use for italic font in syntax
diagrams (synopsis lines). When an item, such as an argument or
parameter is to be replaced with the user's own text, I think it should
be in italics. When that same item is mentioned in the text, it should
also be in italics. Filenames, and any syntax literals, I feel, should
be in a fixed-width font. In syntax diagrams, I feel that only
grammatical symbols (like brackets and the elipsis, should be in roman
font). -bob.
------------------------------------------------------------
From mnetor!utcs!lamy@utai.ARPA Tue Aug 26 05:42:39 1986
I would really like a list of all options to be readily available
for every command, at a predictable place (so that I can find
which option turns on what real fast).
Hierarchical help a la VMS (eeeek!) would be most useful.
--
Jean-Francois Lamy
AI Group, Dept of Computer Science CSNet: lamy@ai.toronto.edu
University of Toronto EAN: lamy@ai.toronto.cdn
Toronto, ON, Canada M5S 1A4 UUCP: lamy@utai.uucp
------------------------------------------------------------
From: rdh (Robert Hartman)
To: mnetor!lamy@utai.ARPA
So would I. What I did at Sun was to define a new section, called USAGE
for any description beyond a summary of the shell-level syntax
and function of the command. We had already defined a section called
OPTIONS in which the options are listed in tagged-paragraph format.
Between the two changes, I can make sure that the options are easy to
find, and begin on the 1'st page (or within 2 or 3 screenfuls). -bob.
------------------------------------------------------------
From decwrl!decvax!wanginst!perlman Fri Aug 29 15:48:39 1986
Subject: Re: man pages and formatting standards: request for comments
This is not very well put together, but it has a lot of my ideas.
[Here I summarize -rdh]
...
Avoid justification in online constant-width manuals ... it only
[adds characters] and makes things harder to read.
...
Use wide page format.
...
Avoid using SYNOPSIS, SYNTAX (these are obscure words) for USAGE.
[Well, I don't know if I agree with this because of the need for
segregating the command-line syntax from the description of
interactive behavior and syntax of interactive commands. -rdh]
Avoid using NOTES, COMMENTS, COMMANDS for DESCRIPTION.
...
The first set
of sections provide successively more detail about the use of a
program.
...
USAGE: I use getopt, and follow the H&A standard option format in man
entries.
...
OPTIONS: I use the following nroff macro for all my options:
.de OP \"name [value]
.TP
.B -\\$1 \\$2
..
[This is a good idea, but doesn't handle italic fonts for
user-supplied parameters.]
...
Cross-References: AUTHOR(S) SOURCE REFERENCE ALGORITHMS SEE ALSO
KEYWORDS
...
Avoid Using:
NOTE use WARNING or put information in DESCRIPTION
CAVEAT use WARNING
BUG we do not use programs with bugs
...
WARNINGS DIAGNOSTICS: Error messages, Returned values
LIMITS: Problem size limits
RESTRICTIONS: Allowed users
STATUS: Development status of the program
...
Avoid Using ENVRONMENT (can be confused with environment variables)
[I think that the ENVIRONMENT section should document environment
vars and nothing else -rdh]
VARIABLES
FILES
HARDWARE
Examples
Avoid Using HINT(S) use EXAMPLE(S)
EXAMPLE(S)
------------------------------------------------------------
From mcvax!cs.qmc.ac.uk!liam@seismo.CSS.GOV Mon Sep 1 04:05:09 1986
Reply-To: mcvax!cs.qmc.ac.uk!liam@seismo.CSS.GOV
I think that sticking to troff is the only reasonable course if
you want to keep backward compatibility and option to use dumb
printers (use nroff instead).
The preprocessors that work well with this scheme are tbl and
eqn, both of which could go in as "naked" preprocessor source,
since manual page writing is not for amateurs.
I think pic would be good for diagrams, but it isn't distributed
with vanilla Unix systems in the same way that troff/tbl/eqn are
so you would have problems with some sites.
I have paged all the way through the online "csh" manual pages
*MANY times* and I am heartily sick of doing so!
...
I also find it irritating to have to remember that the manual
information on "fileno" has to be looked up under "ferror".
Both of these irritations could be solved with a scheme for
indicating keywords in a manual page and improving the indexing
scheme to handle this. There are lots of other ideas around,
for example having each section of the manual entry "folded" into
just a heading which can be opened/reclosed by the reader, but
none of them will fit awfully well with the troff scheme.
William Roberts ARPA: liam@cs.qmc.ac.uk (gw: cs.ucl.edu)
Queen Mary College UUCP: liam@qmc-cs.UUCP
LONDON, UK Tel: 01-980 4811 ext 3900
------------------------------------------------------------
From hplabs!munnari!physiol.su.oz!daved Mon Sep 1 19:03:08 1986
I'd like to see included a non-cryptic statement as to how each man
file should be formatted, preferably in the first line, e.g.
.\" pic | tbl | troff -man
or whatever. I've seen a number of local variants that have been
superimposed on distributed files, suggesting others desire such
information, but it appears to me standardization is needed.
------------------------------------------------------------
From rdh Tue Sep 2 09:57:16 1986
To: hplabs!munnari!physiol.su.oz!daved
Agreed. How about on a directory basis with a ".manrc" file or some such.
The directory entry could be overridded by an entry in a particular file
(as with the eqn.1 and eqnchar.7 pages). -bob.
------------------------------------------------------------
From decwrl!decvax!wanginst!perlman Wed Sep 3 06:12:00 1986
.TH @PROGRAM "@1local" "Created: Tue 02 Sep 1986" "Wang Institute, Tyngsboro, MA 01879 USA" "UNIX User's Manual"
.\" Runoff $Compile: iroff -man %f
.\" RCS $Header: Manual,v 1.2 86/06/03 14:11:59 perlman Exp $
.SH NAME
@program \- @purpose of @program
.SH USAGE
.I @program
[@options] [-] [files]
.SH OPTIONS
.de OP\" option-letter [optional value]
.TP
.B -\\$1 \\$2
..
.OP a
@Here is the
.B -a
flag.
.OP x value
@Here is the
.B -x
flag that takes a value.
.SH DESCRIPTION
.SS Input
.SS Output
.SH EXAMPLES
.nf
.ta 2i\"suggested format for short examples
@name @options # @comment
.ta .5i\"suggested format for long-lined examples
@comment:
@name @options
.fi
.SH VARIABLES
.SH FILES
.SH DIAGNOSTICS
.SH "SEE ALSO"
.SH AUTHOR(S)
Gary Perlman
.SH STATUS
.SH WARNINGS
------------------------------------------------------------
From hplabs!munnari!physiol.su.oz!daved Fri Sep 5 10:00:25 1986
To: hplabs!sun!abraxas!rdh
Subject: Re: man pages and formatting standards: request for comments
> How about on a directory basis with a ".manrc" file or some such.
The problem I had in mind was manual pages (and indeed documents) that get
distributed with the sources to which they pertain. If the file requires
any preprocessing, it is will be most valuable if the requirements are stated
in the file.
...
I would regard
.\" e
as bordering on cryptic for many users, whereas
.\" eqn | troff -man
is likely to mean enough to get started. This is a moderatedly trivial
example, but when we get to something like
.\" pic | refer -e | tbl | eqn | troff -ms
it is not,...
In summary, I'd vote for putting the info in each file, concisely but
non-cryptically in a manner that would serve the manual page requirments,
but be a style that could extend as a standard for all text files.
...
Dave
------------------------------------------------------------
From rdh Fri Sep 5 11:15:35 1986
To: hplabs!munnari!physiol.su.oz!daved
I agree, but I'm also thinking about the problem of people who want to add
the online documentation for some add-on software package. That package
may be written in Tex, or what-have-you, which for the supplier is the
normal environment -- but not necessarily for the user. If there is a
file in the directory that describes the "normal" formatting case for all
"uncommented" files, this would eliminate the need for adding comments to
all those man pages.
-bob.
To: rdh@sun.com
Organization: Data Resources/McGraw-Hill, Lexington, MA
One important aspect to consider when thinking about updating the manual
presentation is the universality of the -man macros. For better or worse,
I can sit here on my brain-damaged Zilog machine and format man pages that
came from people with SVR3, 4.3Bsd, or Sun 3.2. Of course, you could
put in compatibility mode, but many would not use it, or be sympathetic to
those that need it. Witness the recent discussion (in net.sources.d, I
think) of posting something using 16 bit compression.
...
---
Craig Jackson
UUCP: {harvard,linus}!axiom!drilex!dricej
BIX: cjackson