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
ᐧ