Re: [TUHS] man-page style

[Clem Cole <clemc@ccc.com>]

[-- Attachment #1: Type: text/plain, Size: 3781 bytes --]

As is often in these disagreements, I suspect agree more than disagree.
But some of the absolute edges/where you start or stop is where we pick
different things.

On Mon, Nov 19, 2018 at 12:39 PM Theodore Y. Ts'o <tytso@mit.edu> wrote:

>
>
> For what it's worth, that's a Debian packaging standard.  All
> executables are supposed to have a man page.

Right, thank you and I applaud them for that...   As you and others have
pointed out, Debian != Gnu



> In some cases it may be
> no more than a short summary of the options and then a reference to
> the info manual if you want to learn more.

I think that's somewhat backwards in he spirit of 'UNIX'...  the man and
info pages should reference the manual in /usr/doc/foo/
I think the question really comes to what we see 'info' as.    It >>seems<<
to me that you look at info as the 'manual' for the program which many of
us do not; to me info, like man is a quick reference.




>
> I'm not convinced the original BSD man page for, say, "make" is really
> sufficient to learn how to use make effectively w/o the expanded,
> non-man page write up in BSD Unix's Programmers Supplementary
> Documents.

On this we agree, and it is how I learned make in ~77/78 timeframe when
make came to us (I think via UNIX/TS), modulo staring at makefiles and
copying them.
Truth is I did not read Feldman's paper to start because it was not online
and we don't have the storage for it.  I mostly learned make by duplicating
makefiles I found and if I did not understand something - reading the
code.   I did read the paper at some point and mostly understood it.  But
it was not until Steve Talbot set out to write the original Tektronix Make
manual (which later became the first 'Unix in a NutShell' book for Tim
O'Rielly) that I really 'got it.'   Talbot would pester me, Steve Glaser,
Steinhart, Zuhl and the other UNIX jockeys at Tektronix asking how things
worked.  Then he wrote it down and wrote a wonderful book.  It's simple, to
the point -- make in a nutshell -- what you need to know to use it.  To
this day, when someone asks me about make I loan then a copy of the Steve's
book as the starting point.   Once they understand that, I show the Gnu
extensions ;-)

So I dare say the goal that the man page should be the
> primary manual was a bit of an aspiration goal as well.
>
Ah, I think this is were you not hearing what I'm saying...   the 'primary
manual' as you call it is the document in /usr/doc/make in this case.  But
[as others have pointed out, writing that >well<< can be hard]. FWIW:
Feldman's description of make in /usr/doc of Seventh Edition pales compared
to Steve Talbots - but Talbiot was a professional tech writer and while
Feldman's writing is better than my own, he does not write as well as
Talbot IMO.

Anyway, the man page is the reference as Doug pointed out to start this
thread.  It needs to be complete but succinct -> the facts and what I, the
user of the program, need quickly.   Which when done well, is exactly what
it should be.  It can teach, but does probably if the tool is complex,
should not. If the command is simple (cat or maybe the original tr), it
really only a page or so in lenth, because it does not need to be.  If its
more complex, say make or sh; there needs to be the /usr/doc/{make,sh}/*
files that example it.

info should just be a different interface to man.  No more, not less -- the
reference - not the manual.




>
> That being said, I'm not convinced nroff is powerful enough to be a source
> language for info files and HTML files.
>
Mumble, I'll not go down rat hole.  Others, like Larry already have. Truth
is I've never found something I could not do with roff.

Clem
ᐧ
ᐧ

[-- Attachment #2: Type: text/html, Size: 6650 bytes --]