Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!mnetor!seismo!think!nike!lll-crg!lll-lcc!pyramid!decwrl!sun!rdh From: rdh@sun.uucp (Robert Hartman) Newsgroups: net.text Subject: Man Page Standards, Comments Received (long) Message-ID: <8357@sun.uucp> Date: Tue, 21-Oct-86 17:21:26 EDT Article-I.D.: sun.8357 Posted: Tue Oct 21 17:21:26 1986 Date-Received: Wed, 22-Oct-86 22:38:33 EDT Reply-To: rdh@sun.UUCP (Robert Hartman) Distribution: net.text,net.unix-wizards Organization: Sun Microsystems, Inc. Lines: 298 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 " 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