lkml.org 
[lkml]   [1999]   [Aug]   [4]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
SubjectRe: info format (was Re: Linux 2.2.11pre4)
Date
H. Peter Anvin wrote:
> Followup to: <199908040413.WAA07796@ellpspace.math.ualberta.ca>
> By author: Michal Jaegermann <michal@ellpspace.math.ualberta.ca>
> In newsgroup: linux.dev.kernel
> >
> > torvalds> The "info" interface makes sense only to people who grok GNU
> > torvalds> emacs,
> >
> > I do not get it.
>
> OTOH, it is even more ridiculous to not maintain the man page for
> "cp". If there was a dvi browser which would preserve the hyperlinks,
> that would perhaps be another issue...

(In his best south Texas drawl)
You guys just don't get it, do ya?

I think I know where Linus is coming from, and having watched the
evolution of what passes for UN*X documentation since 1978, I think
I can speak to this issue.

Man pages aren't meant to be tutorials: they should document in a
concise manner three things -- WHAT a command does, HOW it is invoked,
and *briefly* explain its OPTIONS. The beauty of a man page other than
its presumed brevity is the fact you don't need a GUI or a 16MB
operating environment masquerading as an editor to read it.

What I *don't* expect from a man page is enough information to be able
to use a given command to full effect: that's a bonus if everything that
can be said about a command can be said *briefly*, but I don't expect it.
The man pages for various shells are notable exceptions to the rule of
brevity, but that's a matter of historical precedent: at the time the
Bourne Shell man page appeared, you could produce documentation using
any tool you wanted as long as the output was either plaintext or
"n/troff" constructs :-).

For those commands where a quick summary isn't enough, additional
documentation in whatever format the author feels comfortable generating
is reasonable and appropriate, but I STILL WANT THE #$%@! man PAGE, and
it should be kept up to date. If you insist on producing your
ADDITIONAL documentation in "info" format, I'll remember you less than
fondly until your dying day for choosing that format, but I'll cave in
and read what you have to say if I need that information badly enough.

--
Bob Tracy | "They couldn't hit an elephant at this dist- "
Firewall Security Corp. | - Last words of Union General John Sedgwick,
rct@frus.com | Battle of Spotsylvania Court House, U.S. Civil War
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/

\
 
 \ /
  Last update: 2005-03-22 13:53    [from the cache]
©2003-2011 Jasper Spaans