[Tfug] Another poser

[Bexley Hall]

--- Brian Murphy <murphy at coppershadow.com> wrote:

> Bexley Hall wrote:
> > Here's a silly poser -- undoubtedly with no
> "right"
> > answer! But, maybe, some "rational" answers??
> > 
> > By convention, *NIX commands are referenced with
> > the manual section appended parenthetically.  In
> > some cases, set in a different typeface, etc.
> > 
> > But, how should commands for which man pages do
> not
> > *exist* be referenced?  I.e., commands whose man
> > pages have not YET been written or are otherwise
> > unavailable?
> > 
> > E.g., for years, NetBSD (and all *BSD's?) were
> > lacking a tar(1) man page.  Of course, since
> tar(1)
> > is so ubiquitous (in the *NIX world), it didn't
> > take a rocket scientist to realize that you
> > *still* would refer to it as "tar(1)" -- on
> > the assumption that *most* Eunices would place
> > it in the "1" section of the manual and, thus,
> > *BSD would undoubtedly follow.
> <snip>
> > [I suspect this issue has only been encountered
> > by folks writing documentation?]
> 
> Well, if the man page hasn't been written yet there
> is little use to reference it.

True, you can't reference the *man* page.
But, my comment refers to the fact that the
"notational shorthand" of COMMAND(MANPAGE) is
used routinely to draw attention to the fact
that COMMAND is a "special word" (i.e. a *command*)
and not just a group of letters that resembles
a word, etc.

E.g., how would you write documentation describing
the use of the floobydust command to confragulate
your whatchamacallits?  Seeing "floobydust(1)"
(or "floobydust(whatever)") acts as a cue to
the reader that floobydust has some significance.
Sure, if you can play with typefaces, you could
set it in bold courier, etc. and, thus, set it
apart from "regular text".

But, if you have to resort to straight ASCII text
to document something (i.e. in your sources or
supporting documents w/o the benefit of web/tangle)
then that "notational shorthand" really is worth
its weight in lead!  :-)

> The numbers are conventional.  Here is an excerpt
> from the man page howto:
> 
> Section The human readable name
>     1    User commands that may be started by
> everyone.
>     2    System calls, that is, functions provided
> by the kernel.
>     3    Subroutines, that is, library functions.
>     4    Devices, that is, special files in the /dev
> directory.
>     5    File format descriptions, e.g. /etc/passwd.
>     6    Games, self-explanatory.
>     7    Miscellaneous, e.g. macro packages,
> conventions.
>     8    System administration tools that only root
> can execute.
>     9    Another (Linux specific) place for kernel
> routine documentation.
>     n    (Deprecated) New documentation, that may be
> moved to a more 
> appropriate section.
>     o    (Deprecated) Old documentation, that may be
> kept for a grace 
> period.
>     l    (Deprecated) Local documentation referring
> to this particular 
> system.

Note that this varies from OS to OS (e.g., Plan 9
has a slightly different scheme; Inferno has yet
another; etc.)

> As the author of the command and/or documentation
> you have some freedom 
> to choose where it fits because like I said, it's
> not set in stone.



 
____________________________________________________________________________________
Don't pick lemons.
See all the new 2007 cars at Yahoo! Autos.
http://autos.yahoo.com/new_cars.html