Re: Are UNIX manpages obsolete?

Subject: Re: Are UNIX manpages obsolete?
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Wed, 2 Oct 1996 06:42:19 PDT

Man pages traditionally give lots of scope for choosing an appropriate
level of detail. For things like function calls, they can either
be exhaustively complete, or not. Many people who look up a C
function can't remember whether an argument is a long or a double,
and that's all they want to know. A perfectly acceptable man page
could consist only of:

* A description of the format of the command/function/whatever.

* A one-line description of each command-line element.

* A one-sentence description of what the command/function/whatever does.

* A reference to the complete description, either on-line or off-line.

Such man pages are so short that you might as well compose them by hand.
So long as you keep the cross-references sensible, you will never have
to update such a man page. (Sensible cross-references refer either
to the name of a function in an alphabetized functional reference manual,
or to a section number. Page references always blow up from revision
to revision, but section numbers can be retained, and the alphabet always
works.)

-- Robert
--
Robert Plamondon, President/Managing Editor, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139


Previous by Author: Enormous Introductions
Next by Author: Re: Value of paper docs?
Previous by Thread: Re: Are UNIX manpages obsolete?
Next by Thread: asterisks in Frame, 'framers' listserv


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads