[TUHS] man-page style

[TUHS] man-page style

[Doug McIlroy]

Regardless of standards considerations, if there's any advice
that needs to be hammered into man authors, it's to be concise
and accurate, but not pedantic. As Will Strunk commanded,
"Omit needless words."

The most needless words of all are promotional. No man page
should utter words like "powerful", "extraordinarily versatile",
"user-friendly", or "has a wide range of options".

As another instance of the rule, it would be better to recommend
short subtitles than to help make them long by recommending
quotes. If anything is said about limited-length macros, it
would best be under BUGS.

As editor for v7-v10, I would not offer v7 as a canonical
model. It owed its use of boldface in SYNOPIS to the limited
number of fonts (Typically R,F,I,S) that could be on our
typesetter at the same time. For v9 we were able to follow
Kernighan and adopt a distinct literals font (L, which happened
to be Courier but could have been identified with bold had we
wished). I still think this is the best choice.

As for options, v7 is a very poor model. It has many pages
that describe options in line, just as v1 had done for its
few options (called flags pre-v7). By v10 all options were
displayed in a list format.

For nagging reasons of verbal continuity, the options displays
were prefaced by *needless words* like, "The following options
are recognized". A simple OPTIONS heading would be better.

Unfortunately, an OPTIONS heading would intrude between the
basic description and less important details that follow
the options. (I don't agree that it would come too closely
after DESCRIPTION; a majority of man pages already have even
shorter sections.)  OPTIONS could be moved to the end of
DESCRIPTION. However, options may well be the biggest reason
for quick peeks at man pages; they should be easy to spot. It
has reasonably been suggested that OPTIONS should be a .SS
subsection.  That might be followed by .SS DETAILS.

Doug

Re: [TUHS] man-page style

[Larry McVoy]

From my quotes page:

How good is good enough: documentation

    Looking at Sun man pages versus Linux man pages is like looking at a Van
    Gogh or Monet after studying the work of the high school football player
    taking art as an "easy" elective. 

Amy Graf, BitMover 


On Thu, Nov 15, 2018 at 07:03:48PM -0500, Doug McIlroy wrote:
> Regardless of standards considerations, if there's any advice
> that needs to be hammered into man authors, it's to be concise
> and accurate, but not pedantic. As Will Strunk commanded,
> "Omit needless words."
> 
> The most needless words of all are promotional. No man page
> should utter words like "powerful", "extraordinarily versatile",
> "user-friendly", or "has a wide range of options".
> 
> As another instance of the rule, it would be better to recommend
> short subtitles than to help make them long by recommending
> quotes. If anything is said about limited-length macros, it
> would best be under BUGS.
> 
> As editor for v7-v10, I would not offer v7 as a canonical
> model. It owed its use of boldface in SYNOPIS to the limited
> number of fonts (Typically R,F,I,S) that could be on our
> typesetter at the same time. For v9 we were able to follow
> Kernighan and adopt a distinct literals font (L, which happened
> to be Courier but could have been identified with bold had we
> wished). I still think this is the best choice.
> 
> As for options, v7 is a very poor model. It has many pages
> that describe options in line, just as v1 had done for its
> few options (called flags pre-v7). By v10 all options were
> displayed in a list format.
> 
> For nagging reasons of verbal continuity, the options displays
> were prefaced by *needless words* like, "The following options
> are recognized". A simple OPTIONS heading would be better.
> 
> Unfortunately, an OPTIONS heading would intrude between the
> basic description and less important details that follow
> the options. (I don't agree that it would come too closely
> after DESCRIPTION; a majority of man pages already have even
> shorter sections.)  OPTIONS could be moved to the end of
> DESCRIPTION. However, options may well be the biggest reason
> for quick peeks at man pages; they should be easy to spot. It
> has reasonably been suggested that OPTIONS should be a .SS
> subsection.  That might be followed by .SS DETAILS.
> 
> Doug

-- 
---
Larry McVoy            	     lm at mcvoy.com             http://www.mcvoy.com/lm 

Re: [TUHS] man-page style

[Dave Horsfall]

On Thu, 15 Nov 2018, Larry McVoy wrote:

> How good is good enough: documentation
>
>    Looking at Sun man pages versus Linux man pages is like looking at a Van
>    Gogh or Monet after studying the work of the high school football player
>    taking art as an "easy" elective.
>
> Amy Graf, BitMover

The Unix manpage format is the epitome of perfection; they tell you 
everything you need to know, and in the right order.  Frequently I cannot 
recall a particular flag (but I know what it does), and it's right there 
at the start.

-- Dave

Re: [TUHS] man-page style

[Grant Taylor via TUHS]

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

On 11/15/2018 10:32 PM, Dave Horsfall wrote:
> The Unix manpage format is the epitome of perfection; they tell you 
> everything you need to know, and in the right order.  Frequently I 
> cannot recall a particular flag (but I know what it does), and it's 
> right there at the start.

I think man pages make a great reference.  But I don't think they are a 
good teaching source for someone that doesn't know the material or what 
the components are for.



-- 
Grant. . . .
unix || die


[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 3982 bytes --]

Re: [TUHS] man-page style

[Jim Capp]

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

It was man pages that first caught my eye, placing me on a life-long path of working 
with Unix and its derivatives. 


I was working on a project for a telephone company, converting IBM 2780 Bisync to 
async, and was given a manual and root access to a Xenix machine. I had cut my 
teeth on a Radio Shack TRS-80 and knew BASIC and Z80 machine code. 


The machine had BASIC, so that is where I started. I had spent an afternoon 
writing a hex dump program before I discovered "od". I spent the next day reading 
all the man pages. I was amazed with their simplicity and clarity. 


Having finished the man pages, I read the Unix Programmer's Manual cover to cover. 
I re-wrote the hex dump in C just for fun. I was sold. 


The remarkable simplicity of Unix, the kernel, the commands, the documentation, 
is a beautiful thing. And I was fortunate to have found it early in my career. 


It was also a time, when the manuals were concise enough to read them all 
in a few day's time. 



To put that into perspective, it took me weeks to acquire a copy of the documentation 
for IBM 2780 Bisync, and even then it left me with more questions. 


I was simply amazed to have found such an elegant system. That it came with 
documentation on every aspect of the system was almost to good to be true. 


For a young programmer starting out in the world, man pages were like gold. 


Jim 





From: "Grant Taylor via TUHS" <tuhs@minnie.tuhs.org> 
To: tuhs@minnie.tuhs.org 
Sent: Friday, November 16, 2018 1:03:37 AM 
Subject: Re: [TUHS] man-page style 

On 11/15/2018 10:32 PM, Dave Horsfall wrote: 
> The Unix manpage format is the epitome of perfection; they tell you 
> everything you need to know, and in the right order. Frequently I 
> cannot recall a particular flag (but I know what it does), and it's 
> right there at the start. 

I think man pages make a great reference. But I don't think they are a 
good teaching source for someone that doesn't know the material or what 
the components are for. 



-- 
Grant. . . . 
unix || die 


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

Re: [TUHS] man-page style

[WIlliam Cheswick]

 I agree, and would like to add that Lorinda Cherry’s permuted index of the Unix commands was a perfect
match to those succinct man pages, easing me into the world of all those filters.

Re: [TUHS] man-page style

[Clem Cole]

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

+1
ᐧ

On Fri, Nov 16, 2018 at 10:44 AM WIlliam Cheswick <ches@cheswick.com> wrote:

>  I agree, and would like to add that Lorinda Cherry’s permuted index of
> the Unix commands was a perfect
> match to those succinct man pages, easing me into the world of all those
> filters.
>
>

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

Re: [TUHS] man-page style

[Tom Manos]

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

Unlike many of us here, I started with UNIX a bit later, at Naval
Postgraduate School, in the mid '80s. It was a relatively early BSD, and I
didn't learn it much except to know that I wanted to understand it better,
but didn't have time. Mostly I had to write C programs.

Just a bit later I had the opportunity to purchase and run Microport
SysV/AT on 286 hardware, and was an immediate convert. I continued using
Microport systems through SVR4. Like others, I found the manuals' thickness
and terseness a turn-off until I bought a book.

I think it was "Introducing the UNIX System" by Henry McGilton and Rachel
Morgan (I still have my copy). A little over 500 pages of UNIX goodness
that taught me all the basics. My experience was that once you know the
basic commands you need for day to day life in UNIX, the manuals become
very helpful. If you can work with sh, ls, awk, find, grep, ps, an editor,
and a few others, the manuals supplement that knowledge with everything
else you need. Additionally, the manuals make a little more sense each time
you read them. Of course, actually administering a UNIX system without
prior knowledge, OJT or a book, using just the manual pages, is next to
impossible.

BTW, I still run SVR4/MP here at home on period hardware. It's a joy to use.

Tom

---

On Fri, Nov 16, 2018 at 10:44 AM WIlliam Cheswick <ches@cheswick.com> wrote:

>  I agree, and would like to add that Lorinda Cherry’s permuted index of
> the Unix commands was a perfect
> match to those succinct man pages, easing me into the world of all those
> filters.
>
>

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

Re: [TUHS] man-page style

[Andy Kosela]

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

On Friday, November 16, 2018, Jim Capp <jcapp@anteil.com> wrote:

> It was man pages that first caught my eye, placing me on a life-long path
> of working
> with Unix and its derivatives.
>
> I was working on a project for a telephone company, converting IBM 2780
> Bisync to
> async, and was given a manual and root access to a Xenix machine.  I had
> cut my
> teeth on a Radio Shack TRS-80 and knew BASIC and Z80 machine code.
>
> The machine had BASIC, so that is where I started.  I had spent an
> afternoon
> writing a hex dump program before I discovered "od".  I spent the next day
> reading
> all the man pages.  I was amazed with their simplicity and clarity.
>
> Having finished the man pages, I read the Unix Programmer's Manual cover to
> cover.
> I re-wrote the hex dump in C just for fun.  I was sold.
>
> The remarkable simplicity of Unix, the kernel, the commands, the
> documentation,
> is a beautiful thing.  And I was fortunate to have found it early in my
> career.
>
> It was also a time, when the manuals were concise enough to read them all
> in a few day's time.
>
>
Yup.  Things were much more simple at that time.  Now try to do the same
with modern "Unix": more than 15 millions lines of code in Linux, more than
10 millions in FreeBSD, some man pages are literally pages and pages of
bizarre options, and userland is just a complicated mess of hundreds of
commands that you never used in your entire life... Add some spice in the
form of systemd and you got the modern "Unix".

Enjoy programming in such a "simple" and "concise" environment now...

--Andy

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

Re: [TUHS] man-page style

[Paul Winalski]

On 11/16/18, Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:
> On 11/15/2018 10:32 PM, Dave Horsfall wrote:
>> The Unix manpage format is the epitome of perfection; they tell you
>> everything you need to know, and in the right order.  Frequently I
>> cannot recall a particular flag (but I know what it does), and it's
>> right there at the start.
>
> I think man pages make a great reference.  But I don't think they are a
> good teaching source for someone that doesn't know the material or what
> the components are for.
>
I agree with Grant.  If you want to know what a particular command
does and what its options are, man pages are fantastic.  If you are a
new or casual user trying to find out what command(s) to use to
accomplish a particular task, the man pages are an exercise in
frustration and futility.  Other OSes have done a better job in that
area (the VMS and DTSS HELP commands come to mind).  IMO ideally one
should have both--a generalized "help" command for those trying to
find out what command to use, and "man" as reference material.  UNIX
and Linux have never had a proper help facility.  Or at least I never
was able to find it.

-Paul W.

Re: [TUHS] man-page style

[Larry McVoy]

On Fri, Nov 16, 2018 at 11:55:28AM -0500, Paul Winalski wrote:
> On 11/16/18, Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:
> > On 11/15/2018 10:32 PM, Dave Horsfall wrote:
> >> The Unix manpage format is the epitome of perfection; they tell you
> >> everything you need to know, and in the right order.  Frequently I
> >> cannot recall a particular flag (but I know what it does), and it's
> >> right there at the start.
> >
> > I think man pages make a great reference.  But I don't think they are a
> > good teaching source for someone that doesn't know the material or what
> > the components are for.
> >
> I agree with Grant.  If you want to know what a particular command
> does and what its options are, man pages are fantastic.  If you are a
> new or casual user trying to find out what command(s) to use to
> accomplish a particular task, the man pages are an exercise in
> frustration and futility.  Other OSes have done a better job in that
> area (the VMS and DTSS HELP commands come to mind).  IMO ideally one
> should have both--a generalized "help" command for those trying to
> find out what command to use, and "man" as reference material.  UNIX
> and Linux have never had a proper help facility.  Or at least I never
> was able to find it.

I think there was a help at one point but it got lost.  PWB maybe?
There is still apropos which can be useful.

What helped me starting out was one of those trifold summaries of
common commands.

ls for directory listings?  Very poor choice for newbies but pleasant
once you know it is there.  Short is nice for common stuff.

I just remember a steep learning curve initially.  But you got over
it pretty quickly and then things were pleasant.  I found the Unix
docs to be great but hard to figure where things were at first. 
Once you were past that, smooth sailing.

Re: [TUHS] man-page style

[Paul Winalski]

On 11/16/18, Larry McVoy <lm@mcvoy.com> wrote:
>
> I think there was a help at one point but it got lost.  PWB maybe?
> There is still apropos which can be useful.
>
Except for two things:

(1) You have to know to type "apropos" in the first place.  Completely
non-obvious to the newbies who really need it.

(2) I don't know how apropos is implemented, but it appears to be a
rather simple-minded (as opposed to the DWIM-style search of Google
and its friends) textual search engine for man pages.  I never got the
hang of it.  For me it always either turned up nothing or produced
reams of hits--too big a haystack to find the needle of info I was
looking for.

Very much a stylistic thing, and a matter of taste IMO.  As you say,
the command interface to Unix has a steep learning curve, but it is a
system designed by experts for experts.

-Paul W.

Re: [TUHS] man-page style

[Dave Horsfall]

On Fri, 16 Nov 2018, Paul Winalski wrote:

> (1) You have to know to type "apropos" in the first place.  Completely
> non-obvious to the newbies who really need it.

I don't think I've ever used "apropos" in my life; "man -k" works for me.

-- Dave

Re: [TUHS] man-page style

[Jim Capp]

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

>On Fri, Nov 16, 2018 at 11:55:28AM -0500, Paul Winalski wrote: 
>> On 11/16/18, Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote: 
>> > On 11/15/2018 10:32 PM, Dave Horsfall wrote: 
>> >> The Unix manpage format is the epitome of perfection; they tell you 
>> >> everything you need to know, and in the right order. Frequently I 
>> >> cannot recall a particular flag (but I know what it does), and it's 
>> >> right there at the start. 
>> > 
>> > I think man pages make a great reference. But I don't think they are a 
>> > good teaching source for someone that doesn't know the material or what 
>> > the components are for. 
>> > 
>> I agree with Grant. If you want to know what a particular command 
>> does and what its options are, man pages are fantastic. If you are a 
>> new or casual user trying to find out what command(s) to use to 
.> accomplish a particular task, the man pages are an exercise in. 
>> frustration and futility. Other OSes have done a better job in that 
>> area (the VMS and DTSS HELP commands come to mind). IMO ideally one 
>> should have both--a generalized "help" command for those trying to 
>> find out what command to use, and "man" as reference material. UNIX 
>> and Linux have never had a proper help facility. Or at least I never 
>> was able to find it. 
> 
>I think there was a help at one point but it got lost. PWB maybe? 
>There is still apropos which can be useful. 
> 
>What helped me starting out was one of those trifold summaries of 
>common commands. 
> 
>ls for directory listings? Very poor choice for newbies but pleasant 
>once you know it is there. Short is nice for common stuff. 
> 
>I just remember a steep learning curve initially. But you got over 
>it pretty quickly and then things were pleasant. I found the Unix 
>docs to be great but hard to figure where things were at first. 
>Once you were past that, smooth sailing. 



PWB was great too, but what was most useful to me was the 
"UNIX programmer's manual" from Bell Telephone Laboratories (c) 1979, 1983 


The first volume included all the man pages, a quick reference, and an index. 


The second volume contained all the "how to" guides, including concise summaries 
of the facilities available on UNIX, the original UNIX paper from Ritchie and Thompson, 
UNIX for Beginners from Kernighan, NROFF/TROFF User's Manual, TROFF Tutorial, 
C Programming Language, Lint, Make, YACC, LEX, AWK, and on and on. 


The combination of those two volumes was invaluable. 




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

Re: [TUHS] man-page style

[Larry McVoy]

On Fri, Nov 16, 2018 at 12:33:15PM -0500, Jim Capp wrote:
> PWB was great too, but what was most useful to me was the 
> "UNIX programmer's manual" from Bell Telephone Laboratories (c) 1979, 1983 
> 
> The first volume included all the man pages, a quick reference, and an index. 
> 
> The second volume contained all the "how to" guides, including concise summaries 
> of the facilities available on UNIX, the original UNIX paper from Ritchie and Thompson, 
> UNIX for Beginners from Kernighan, NROFF/TROFF User's Manual, TROFF Tutorial, 
> C Programming Language, Lint, Make, YACC, LEX, AWK, and on and on. 
> 
> The combination of those two volumes was invaluable. 

I still have the BSD versions of those, I think it expanded to 3 with 
a systems admin volume.  I agree, super useful.

Re: [TUHS] man-page style

[Dave Horsfall]

On Fri, 16 Nov 2018, Jim Capp wrote:

> PWB was great too, but what was most useful to me was the "UNIX 
> programmer's manual" from Bell Telephone Laboratories (c) 1979, 1983

[...]

That sounds remarkably like the "Unix Documention" [sic] that Dr. John 
Lions had printed, way before his famous books.  The two manuals contained 
all the man pages, an intro to "ed", "roff", C etc, which is how I taught 
myself Unix and C before he started teaching it (I was originally hired to 
support RSX-11D!).

-- Dave

Re: [TUHS] man-page style

[Jon Steinhart]

Thanks Doug for accidentally starting this thread :-)

I'm a big fan of the "original-style" man pages.  Brevity was really
important when working remote and having to look things up via a
TI Silent 700 at 30 characters per second.

I feel like the GNU project is responsible for destroying the usefulness
of man pages with their "info" stuff.  Nothing more helpful than getting
a man page that says that it's not the man page and that one should look
elsewhere using a different and very clunky program.  Started the decline
of being able to find everything in one place in a consistent manner.

And just to rant, I really hate documentation that begins with how to get,
build, and install software.  I think that most folks looking at docs are
wanting to know how to use it, and having to skip over the least-important
stuff which is first is annoying, especially when one gets past it to
discover that the rest of the doc was never written.

Anyway, the sake of argument, I'm gonna postulate that the more recent,
useless man pages are a sympton of poor software design.  I'll make the
claim that the loss of the "do one thing and do it well and make it
composable" UNIX philosophy is exposed in many of the very complex
utilities with huge numbers of dash options.

Jon

Re: [TUHS] man-page style

[Clem Cole]

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

On Fri, Nov 16, 2018 at 1:40 PM Jon Steinhart <jon@fourwinds.com> wrote:

> Thanks Doug for accidentally starting this thread :-)
>
+1


> I feel like the GNU project is responsible for destroying the usefulness of
> man pages with their "info" stuff.
>
Come on Jon - don't you live in emacs all day long ;-)  .. sigh....


>  I'll make the claim that the loss of the "do one thing and do it well
> ..."

Actually I blame the VAX and larger address spaces for much of that and no
enough real teaching of what I refer to as 'good taste.'   When you had to
think about keeping it small and decomposable, you did.   My own sisters
and brothers at UCB started us down this path I fear.

Truth is, it is a tough call, learning when 'good enough' is all you need.
 When its easy to add to things to something you have, you get GNU (or cat
-v as Rob pointed out years ago or my least favorite - sendmail - there is
>>no<< reason why SMTPD was part of sendmail as an example).

I've meantion before on this list, the day I showed Dennis that fact that
the System V boot system was larger than the 6th edition kernel, you knew
we had a problem.   The argument of course is - "well look how well it
works and I can do this X" -- sorry not good enough.

In the late 70s, Mashy had a wonderful ACM lecture called 'Small is
Beautiful' and he had some excellent pictures that demonstrated the problem
visually.   I love to see him resurect that talk and try to get 'modern'
programmers try to understand his message.

That said, I admit I do like many things on my moderm MBP and I would not
want to go back to running 6th Edition, but I swear there is a happy ground
somewhere in between.

Clem
ᐧ

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

Re: [TUHS] man-page style

[Toby Thain]

On 2018-11-16 11:55 AM, Paul Winalski wrote:
> On 11/16/18, Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:
>> On 11/15/2018 10:32 PM, Dave Horsfall wrote:
>>> The Unix manpage format is the epitome of perfection; they tell you
>>> everything you need to know, and in the right order.  Frequently I
>>> cannot recall a particular flag (but I know what it does), and it's
>>> right there at the start.
>>
>> I think man pages make a great reference.  But I don't think they are a
>> good teaching source for someone that doesn't know the material or what
>> the components are for.
>>
> I agree with Grant.  If you want to know what a particular command
> does and what its options are, man pages are fantastic.  If you are a
> new or casual user trying to find out what command(s) to use to
> accomplish a particular task, the man pages are an exercise in
> frustration and futility.  Other OSes have done a better job in that
> area (the VMS and DTSS HELP commands come to mind).  IMO ideally one
> should have both--a generalized "help" command for those trying to
> find out what command to use, and "man" as reference material.  UNIX
> and Linux have never had a proper help facility.  Or at least I never
> was able to find it.

GNU understood the difference, and wrote separate manuals (e.g. `info
bash`, `info bison`, etc).

> 
> -Paul W.
> 

Re: [TUHS] man-page style

[Dave Horsfall]

On Fri, 16 Nov 2018, Toby Thain wrote:

> GNU understood the difference, and wrote separate manuals (e.g. `info 
> bash`, `info bison`, etc).

GNU "info" is one of the most non-intuitive interfaces that I've ever had 
the displeasure to use.  Or maybe that's just me...

-- Dave

Re: [TUHS] man-page style

[Larry McVoy]

On Sat, Nov 17, 2018 at 07:52:18AM +1100, Dave Horsfall wrote:
> On Fri, 16 Nov 2018, Toby Thain wrote:
> 
> >GNU understood the difference, and wrote separate manuals (e.g. `info
> >bash`, `info bison`, etc).
> 
> GNU "info" is one of the most non-intuitive interfaces that I've ever had
> the displeasure to use.  Or maybe that's just me...
> 
> -- Dave

It's not just you, it's anyone who prefers vi to emacs.
-- 
---
Larry McVoy            	     lm at mcvoy.com             http://www.mcvoy.com/lm 

Re: [TUHS] man-page style

[Chet Ramey]

On 11/16/18 3:52 PM, Dave Horsfall wrote:
> On Fri, 16 Nov 2018, Toby Thain wrote:
> 
>> GNU understood the difference, and wrote separate manuals (e.g. `info
>> bash`, `info bison`, etc).
> 
> GNU "info" is one of the most non-intuitive interfaces that I've ever had
> the displeasure to use.  Or maybe that's just me...

If you don't use emacs, you won't like it.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Jim Capp]

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

> If you don't use emacs, you won't like it. 


Let's not start any new emacs vs. vi flame wars. 



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

Re: [TUHS] man-page style

[Kurt H Maier]

On Fri, Nov 16, 2018 at 04:05:41PM -0500, Jim Capp wrote:
> > If you don't use emacs, you won't like it.
>
>
> Let's not start any new emacs vs. vi flame wars.
       
Nobody said anything about vi.  emacs integration is an explicit design
parameter for GNU texinfo.  It's almost impossible to answer any
questions about its design without starting your answer by saying "well,
in emacs..."
           
khm

Re: [TUHS] man-page style

[Chet Ramey]

On 11/16/18 4:05 PM, Jim Capp wrote:
>> If you don't use emacs, you won't like it.
> 
> Let's not start any new emacs vs. vi flame wars.

No flames; no vi vs. emacs. Info is explicitly designed to emulate emacs
info mode.


-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Lars Brinkhoff]

Chet Ramey wrote:
> No flames; no vi vs. emacs. Info is explicitly designed to emulate emacs
> info mode.

It's even better.  I believe it's designed to emulate something that
existed before Emacs.

Re: [TUHS] man-page style

[Chet Ramey]

On 11/19/18 12:59 AM, Lars Brinkhoff wrote:
> Chet Ramey wrote:
>> No flames; no vi vs. emacs. Info is explicitly designed to emulate emacs
>> info mode.
> 
> It's even better.  I believe it's designed to emulate something that
> existed before Emacs.

Emacs info mode emulates something that existed before ITS/TENEX EMACS.
When Brian wrote Info, he emulated gnu emacs.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Jon Steinhart]

Chet Ramey writes:
> On 11/16/18 3:52 PM, Dave Horsfall wrote:
> > On Fri, 16 Nov 2018, Toby Thain wrote:
> > 
> >> GNU understood the difference, and wrote separate manuals (e.g. `info
> >> bash`, `info bison`, etc).
> > 
> > GNU "info" is one of the most non-intuitive interfaces that I've ever had
> > the displeasure to use.  Or maybe that's just me...
>
> If you don't use emacs, you won't like it.

Well, not wanting to start a flame war here, but I don't use emacs.  While
it's a good piece of software, I just want a text editor.  Emacs sort of
violates my UNIX-sense as it does many things instead of doing one thing
well.

But really the issue is that info introduced a new interface on a system
that already had one that people were accustomed to.  This is something
that perpetually annoys me in the software world; people introducing new
ways of doing things that aren't improvements, just different.  Just makes
life harder for everyone else.

As an example, I recently did a deep dive trying to figure out why promises
were added to JavaScript.  Actually has nothing to do with the first
10000000000 search results.  They were done for a particular reason that I
don't agree with but were an excuse for someone to force their preferred
coding style on others.  And the details are not a topic for this list.

Jon

Re: [TUHS] man-page style

[Clem Cole]

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

On Fri, Nov 16, 2018 at 4:40 PM Jon Steinhart <jon@fourwinds.com> wrote:

> Emacs sort of violates my UNIX-sense as it does many things instead of
> doing one thing well.
>
Exactly -- the idea is emacs is its own 'system' and you need to view the
world through it.

The funny thing is I had learned emacs >>before<< ed when I was PDP-10
hacking (i.e when it was a set of TECO macros).  But ed for UNIX, was what
we had and I learned it.   It got the job done.  I was happy.    When emacs
later appeared on UNIX, it really was not any better than what I had.. I
could use both, but I quickly discovered I did not want to be inside of
emacs all the time on UNIX (too slow and cranky).  Since I followed the old
UNIX rule of 'type of the cshell and program the bourne'   -- I was
unwilling to give into the emacs way, it made no sense to me to continue.
I'm happy for those that like it and hey to each her/his own.

As was discussed a few days ago in the ed/qed history -- ed was fine.  And
UNIX was SO much faster than the PDP-10s to do almost anything I wanted to
do.   And, when 'fred' and other video front ends for ed appeared, they
made perfect sense - they were just ed with some way to move the 'soft'
cursor since it was video not paper.  They too were fast and simple.  Which
really was no different than the vi subcommand for ex, when it came along
(FWIW: fred was the Cornell video front end for ed that I first saw on 6th
edition I think, although it might have been 5th edition.   Fred was 'hard
coded' for the few terminals we had - DEC vt52, PE 'fox, and the Lear
Siegler ADM3A').  I switched to vi later really because of termcap and ease
of adding terminal support.

But really the issue is that info introduced a new interface on a system
> that already had one that people were accustomed to.  This is something
> that perpetually annoys me in the software world; people introducing new
> ways of doing things that aren't improvements, just different.  Just makes
> life harder for everyone else.
>
The rule of 'least astonishment' -- instead of making UNIX like ITS or
whatever, 'info' seems like it is trying to force a new world on to someone
because that programmer likes some other way bettter. i.e.
https://xkcd.com/927/

I would not have minded having the 'info' interface so much if Gnu had kept
'man' as the high order bit and created the 'info' pages by 'mining' the
man ones -- *i.e.* offering a second interface to the same information.
But instead, they tried to force people to use 'info' instead of man and
left the rela information out of man - trying to force you to their
perfered interface.   The believe that under the rule of 'Gnu is not Unix'
- rms felt licensed to do so.  Except the Gnu >>team<< cloned the UNIX
interface and all of the UNIX tools - hence violating the rule of least
astonishment.

I think this is not a lot different than saying since Gnu is not Unix, we
want a different (better) interface and we will not use read/write -- in
Gnu we will have open/close/mmap ---  just think what what have happenned.
 Not saying it might not have been 'better' but it would not have been
'Unix' -- same 'license' - Gnu is Not Unix -- but code would not have
worked.    So instead rms tries to force a new human interface and guess
what, you have to reprogram a lot of people.

Clem
ᐧ

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

Re: [TUHS] man-page style

[Lars Brinkhoff]

Jon Steinhart wrote:
> Emacs sort of violates my UNIX-sense as it does many things instead of
> doing one thing well.

It probably should!  Emacs is very much divorced from the Unix
philosopy.  However, it's perfectly in synch with how things are done in
ITS.  I'd like to argue that if you use Emacs, you're actually using a
piece of ITS.

Clem Cole:
> Exactly -- the idea is emacs is its own 'system' and you need to view
> the world through it.

Yes, much like a Lisp machine.  Stallman worked on ITS and Lisp machines
before developing GNU Emacs (from Gosling's version), and it clearly
shows.

I happen to like ITS and Lisp, so Emacs is a perfect fit for me.

Re: [TUHS] man-page style

[Chet Ramey]

On 11/16/18 4:13 PM, Jon Steinhart wrote:

> Well, not wanting to start a flame war here, but I don't use emacs.  While
> it's a good piece of software, I just want a text editor.  Emacs sort of
> violates my UNIX-sense as it does many things instead of doing one thing
> well.

That's fine. Everyone gets to use whatever they want.

> But really the issue is that info introduced a new interface on a system
> that already had one that people were accustomed to.

Improvement is in the eye of the beholder. RMS and other folks consider
info, with its hyperlinks, indexes, and tree-based navigation the superior
alternative.  Not just different, but better.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Jon Steinhart]

Chet Ramey writes:
> On 11/16/18 4:13 PM, Jon Steinhart wrote:
> > But really the issue is that info introduced a new interface on a system
> > that already had one that people were accustomed to.
>
> Improvement is in the eye of the beholder. RMS and other folks consider
> info, with its hyperlinks, indexes, and tree-based navigation the superior
> alternative.  Not just different, but better.

Well, of course it is.  And as long as one doesn't care much about existing
community one can do what one wants.  Sort of like Americans expecting others
to speak to them in English when they travel instead of understanding that
they're in a different environment and it makes more sense to learn the culture
as it's unlikely that everybody is gonna change just for you.  This is not a
unique problem with man vs info.  I see it in the large number of different
make utilities, package managers, and so on that really don't provide new
functionality but do make it much harder to be a practicioner since one has a
lot more stuff to learn for no real benefit.

So were it me, I would have looked at the current culture in the UNIX environment
and figured out how it gracefully extend it for new functionality.  To me, that's
a mark of good engineering instead of being a bull in a china shop.  A good example
of that in a different field is the way in which FM stereo was finessed in such a
way as to not break existing mono receivers.  Would have been easy to just toss it
and make everybody buy new gear, but I prefer the more elegant solution.

Jon

Re: [TUHS] man-page style

[George Michaelson]

Mike Lesk had a really good rap about his work on Library information
systems and the work they did at Bell (or maybe one of the schools of
library sciences).

The principle was, that "simple" users wanted nested menu and "power"
users wanted commands. They did A/B testing and a bunch of work to
show that if you trained people in the keystrokes for the commandline,
they got significantly more productive.

Mike also said (I may be mis-remembering, but this is what I took from
the conversation) that people's prior experiental sense of what they
wanted had as much influence on what they thought, as the quality of
the system.

So if (like me) you walked into the SOS room at the lab, on a
Dec-10... you wound up wired to go with ed/ex/vi family interaction.
If you walked into the teco room you came out more wired for emacs. I
think this is very probably true, purely on my own sample of one. If
I'd walked into the LISP room, I would probably now be a lowly paid
quant in a small bank, failing badly instead of having walked into the
pascal room, and being an imperative language person earning the huge
bucks coding menu systems. No wait.. thats not right..
On Mon, Nov 19, 2018 at 1:11 PM Jon Steinhart <jon@fourwinds.com> wrote:
>
> Chet Ramey writes:
> > On 11/16/18 4:13 PM, Jon Steinhart wrote:
> > > But really the issue is that info introduced a new interface on a system
> > > that already had one that people were accustomed to.
> >
> > Improvement is in the eye of the beholder. RMS and other folks consider
> > info, with its hyperlinks, indexes, and tree-based navigation the superior
> > alternative.  Not just different, but better.
>
> Well, of course it is.  And as long as one doesn't care much about existing
> community one can do what one wants.  Sort of like Americans expecting others
> to speak to them in English when they travel instead of understanding that
> they're in a different environment and it makes more sense to learn the culture
> as it's unlikely that everybody is gonna change just for you.  This is not a
> unique problem with man vs info.  I see it in the large number of different
> make utilities, package managers, and so on that really don't provide new
> functionality but do make it much harder to be a practicioner since one has a
> lot more stuff to learn for no real benefit.
>
> So were it me, I would have looked at the current culture in the UNIX environment
> and figured out how it gracefully extend it for new functionality.  To me, that's
> a mark of good engineering instead of being a bull in a china shop.  A good example
> of that in a different field is the way in which FM stereo was finessed in such a
> way as to not break existing mono receivers.  Would have been easy to just toss it
> and make everybody buy new gear, but I prefer the more elegant solution.
>
> Jon

Re: [TUHS] man-page style

[Larry McVoy]

I'm in the middle of a family / college mess.  So I have no deep reply,
but every day this list gives me more insight into how we got here.
Just wanted to say thanks and tell people to keep popping up and tell
their stories.

On Mon, Nov 19, 2018 at 01:21:24PM +1000, George Michaelson wrote:
> Mike Lesk had a really good rap about his work on Library information
> systems and the work they did at Bell (or maybe one of the schools of
> library sciences).
> 
> The principle was, that "simple" users wanted nested menu and "power"
> users wanted commands. They did A/B testing and a bunch of work to
> show that if you trained people in the keystrokes for the commandline,
> they got significantly more productive.
> 
> Mike also said (I may be mis-remembering, but this is what I took from
> the conversation) that people's prior experiental sense of what they
> wanted had as much influence on what they thought, as the quality of
> the system.
> 
> So if (like me) you walked into the SOS room at the lab, on a
> Dec-10... you wound up wired to go with ed/ex/vi family interaction.
> If you walked into the teco room you came out more wired for emacs. I
> think this is very probably true, purely on my own sample of one. If
> I'd walked into the LISP room, I would probably now be a lowly paid
> quant in a small bank, failing badly instead of having walked into the
> pascal room, and being an imperative language person earning the huge
> bucks coding menu systems. No wait.. thats not right..
> On Mon, Nov 19, 2018 at 1:11 PM Jon Steinhart <jon@fourwinds.com> wrote:
> >
> > Chet Ramey writes:
> > > On 11/16/18 4:13 PM, Jon Steinhart wrote:
> > > > But really the issue is that info introduced a new interface on a system
> > > > that already had one that people were accustomed to.
> > >
> > > Improvement is in the eye of the beholder. RMS and other folks consider
> > > info, with its hyperlinks, indexes, and tree-based navigation the superior
> > > alternative.  Not just different, but better.
> >
> > Well, of course it is.  And as long as one doesn't care much about existing
> > community one can do what one wants.  Sort of like Americans expecting others
> > to speak to them in English when they travel instead of understanding that
> > they're in a different environment and it makes more sense to learn the culture
> > as it's unlikely that everybody is gonna change just for you.  This is not a
> > unique problem with man vs info.  I see it in the large number of different
> > make utilities, package managers, and so on that really don't provide new
> > functionality but do make it much harder to be a practicioner since one has a
> > lot more stuff to learn for no real benefit.
> >
> > So were it me, I would have looked at the current culture in the UNIX environment
> > and figured out how it gracefully extend it for new functionality.  To me, that's
> > a mark of good engineering instead of being a bull in a china shop.  A good example
> > of that in a different field is the way in which FM stereo was finessed in such a
> > way as to not break existing mono receivers.  Would have been easy to just toss it
> > and make everybody buy new gear, but I prefer the more elegant solution.
> >
> > Jon

-- 
---
Larry McVoy            	     lm at mcvoy.com             http://www.mcvoy.com/lm 

Re: [TUHS] man-page style

[Lars Brinkhoff]

Jon Steinhart wrote:
> Chet Ramey wrote:
>> Improvement is in the eye of the beholder. RMS and other folks consider
>> info, with its hyperlinks, indexes, and tree-based navigation the superior
>> alternative.  Not just different, but better.
> So were it me, I would have looked at the current culture in the UNIX
> environment and figured out how it gracefully extend it for new
> functionality.

Yes, that's would have been very reasonable.

But I have the impression that GNU from the outset was supposed to go
beyond Unix.  My vague memory is that the phrase "GNU's not Unix" kind
of implied "we're making a copy of Unix... but we'll change it any way
we see fit".  The announcement figured things like a Lisp-based
windowing system and Chaosnet.

Remember that Stallman came from a dozen years of working with ITS and
Lisp machines.  It seems likely he wanted to pick the best parts and
transplant them on top of Unix, making GNU.  To some degree, he
succeeded: Emacs is EMACS, unexec is PDUMP, Emacs Lisp is Maclisp, Info
is INFO, GCC internals kind of wants to be Lisp.

Not arguing for or against here, just trying to provide some historical
background as I see it.

Re: [TUHS] man-page style

[Chet Ramey]

On 11/19/18 1:13 AM, Lars Brinkhoff wrote:
> Jon Steinhart wrote:
>> Chet Ramey wrote:
>>> Improvement is in the eye of the beholder. RMS and other folks consider
>>> info, with its hyperlinks, indexes, and tree-based navigation the superior
>>> alternative.  Not just different, but better.
>> So were it me, I would have looked at the current culture in the UNIX
>> environment and figured out how it gracefully extend it for new
>> functionality.
> 
> Yes, that's would have been very reasonable.

It was an explicit goal. From the GNU manifesto:

"GNU will be able to run Unix programs, but will not be identical to Unix.
We will make all improvements that are convenient, based on our experience
with other operating systems."

and

"Unix is not my ideal system, but it is not too bad. The essential features
of Unix seem to be good ones, and I think I can fill in what Unix lacks
without spoiling them."

Of course, one man's graceful extension is the next man's graceless
pillaging.


-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Clem Cole]

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

On Sun, Nov 18, 2018 at 10:11 PM Jon Steinhart <jon@fourwinds.com> wrote:

> Sort of like Americans expecting others to speak to them in English when
> they travel instead of understanding that they're in a different
> environment and it makes more sense to learn the culture as it's unlikely
> that everybody is gonna change just for you.

Amen, brother Jon, can we get another Amen..




> This is not a unique problem with man vs info.  I see it in the large
> number of different make utilities, package managers, and so on that
> really don't provide new functionality but do make it much harder to be a
> practitioner since one has a lot more stuff to learn for no real benefit.
>
Exactly!!


>
> So were it me, I would have looked at the current culture in the UNIX
> environment and figured out how it gracefully extend it for new
> functionality.  To me, that's
> a mark of good engineering instead of being a bull in a china shop.

I referred to this previously as the principle of 'least astonishment.'

Again - the argument for doing what he (and his followers did was) 'Gnu is
Not Unix' - but my reply is that they created UNIX when they were done.
They road the research train, then BSD rode the same UNIX train to start
and now ride the UNIX look/work alike, Linux, rides it still.    And
because it was incremental on the past, we get more behind it.

A much as I'm live and left live, and to each her/his own -- if GNU had
been a new system, then I might be a lot more willing to accept that the
argument.  But what was build was (and is) not.  GNU is just the current
and expanded UNIX implementation.  And the so its have the man page being
useless and expecting people to use info in just wrong.   Even if you are
used it it (ok, so you found English speakers when you travelled).

And Ted is not that I don't use the unix documents (full papers) - hey I
do.   That is how I learned to use 'make' when it appeared (or C for that
matter) from documents in /usr/doc. \

What started this whole thread was Doug's comment about how succinct and
to the point man was.  If was a fine interface for >>UNIX<<.   Man (using
roff) was what people expect.  It's not about better or worse -- it worked
and worked well.

As I said, if man had been maintained as the primary >>manual<< style
interface and /usr/doc/<PROG>/foo.ms as the primary scheme (which >>IS<<
what BSD did), then you don't fail the rule of least astonishment.  Then
create a *roff -Tinfo | info_create backend, that produced the info files;
those that want it, get it and love it.   Those that >>expect<< man to work
because its UNIX, get what they expect.  No one is 'astonished.'

A good example of that in a different field is the way in which FM stereo
> was finessed in such a
> way as to not break existing mono receivers.  Would have been easy to just
> toss it
> and make everybody buy new gear, but I prefer the more elegant solution.
>
Yep.   Metcalfe's Law -- adding too and improving on the past; makes more
people happy.   Yep, it is sometimes 'harder ' for the developer and some
compromises do result.   But the result is a bigger pie and happier group
in total.  Think of the contemporary system to Linux (including Plan9 for
the matter) -- which were 'better' and which are we still using.   Its not
that there are not good ideas.

The 'better than' argument fails when the difference ('betterness') is
shallow and not something that really is remarkable (I like it and use it
is not good enough).   Respecting the past and ensuring the 'old ways' work
is good business.  And that is the problem.   When you are the creator of
the alternate scheme, its hard to not understand how much better something
is.  Being different and better >>sometimes<< can pay off (check out:  –Bret
Victor’s: The Future of Programming:
https://www.youtube.com/watch?v=8pTEmbeENF4 –His talk in 2013, but set and
presented it as if he were talking in the 1970s); but if you look each of
these things he is talking about is remarkably different --  man vs. info
(or ed/vi vs teco/emacs for that matter, I'm not sure really are/were).

Clem
ᐧ
ᐧ

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

Re: [TUHS] man-page style

[David]

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


> On Nov 19, 2018, at 7:35 AM, Clem Cole <clemc@ccc.com> wrote:
> 
> 
> 
> On Sun, Nov 18, 2018 at 10:11 PM Jon Steinhart <jon@fourwinds.com <mailto:jon@fourwinds.com>> wrote:
> Sort of like Americans expecting others to speak to them in English when they travel instead of understanding that they're in a different environment and it makes more sense to learn the culture as it's unlikely that everybody is gonna change just for you.
> Amen, brother Jon, can we get another Amen..
> 
As a recent traveller overseas, Amen to that.

> 
> What started this whole thread was Doug's comment about how succinct and  to the point man was.  If was a fine interface for >>UNIX<<.   Man (using roff) was what people expect.  It's not about better or worse -- it worked and worked well.
> 
> 
> Clem
> ᐧ
> ᐧ

The problem, as we have all converged on, is that writing well is hard. Writing concise, targeted prose, is even harder. So we get bloat in man pages or the info system which is just (IMHO) more bloat because people don’t want to spend the time writing well.

	David


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

Re: [TUHS] man-page style

[Jon Steinhart]

David writes:
> The problem, as we have all converged on, is that writing well is hard. Writing
> concise, targeted prose, is even harder. So we get bloat in man pages or the
> info system which is just (IMHO) more bloat because people don’t want to spend
> the time writing well.

I'm going to be a bit contrary here.  Yes, writing is hard, but not that hard.
Designing is what's harder.  I'm gonna make the claim that a lot of projects
today aren't designed.  They're implemented, and when someone gets something
that sort of works they write down a few notes about what was hard for them
(if we're lucky) and passes that off as documentation.  We're in an era in
which it is so easy to just try things that many don't bother which what I'd
call design.  No surprise that "documentation" from "undesigned" isn't good.

Re: [TUHS] man-page style

[Theodore Y. Ts'o]

On Mon, Nov 19, 2018 at 10:35:05AM -0500, Clem Cole wrote:
> And Ted is not that I don't use the unix documents (full papers) - hey I
> do.   That is how I learned to use 'make' when it appeared (or C for that
> matter) from documents in /usr/doc. \
> 
> What started this whole thread was Doug's comment about how succinct and
> to the point man was.  If was a fine interface for >>UNIX<<.   Man (using
> roff) was what people expect.  It's not about better or worse -- it worked
> and worked well.

For what it's worth, that's a Debian packaging standard.  All
executables are supposed to have a man page.  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.  If the upstream package
does not provide a man page, Debian maintainers are supposed to create
a man page, and hopefully contribute it back upstream.

This isn't always the case; but if there isn't a man page, that's
always grounds for filing a Debian bug report.

> As I said, if man had been maintained as the primary >>manual<< style
> interface and /usr/doc/<PROG>/foo.ms as the primary scheme (which >>IS<<
> what BSD did), then you don't fail the rule of least astonishment.  Then
> create a *roff -Tinfo | info_create backend, that produced the info files;
> those that want it, get it and love it.   Those that >>expect<< man to work
> because its UNIX, get what they expect.  No one is 'astonished.'

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.  So I dare say the goal that the man page should be the
primary manual was a bit of an aspiration goal as well.

That being said, I'm not convinced nroff is powerful enough to be a
source language for info files and HTML files.  For one thing, it
doesn't have the ability to specify hyperlinks.  The GNU an-ext.tmac
extensions does define macros to provide *external* hyperlinks to WWW
URL's.  However, even that doesn't have the ability to specify
*internal* hyperlinks to other sections of the document.

Cheers,

						- Ted

Re: [TUHS] man-page style

[Clem Cole]

[-- 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 --]

Re: [TUHS] man-page style

[Theodore Y. Ts'o]

On Mon, Nov 19, 2018 at 01:40:43PM -0500, Clem Cole wrote:
> 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.
> 
> > 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

Well, technically Debian's Linux is named "Debian GNU/Linux".  It's
not recognized by the FSF as free (Debian cares about allowing users
to have Laptops which aren't paperweights, even if it does mean making
available firmware for which source is not available), so they
recommend distributions such as gNewSense, which is a Debian-based
fork that is now inactive.

Personally, I find debates about whether or not Debian != GNU to be
much like the bickering between the Judean People's Front versus
People's Front of Judea, the latter of which sends a crack squad to
commit mass suicide at the end of the movie "Life of Brian".  :-)

Unless the claim is the only thing which is GNU is HURD?

> > 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.

The info pages are *in* /usr/share/doc/... on a Debian system.  And if
you were to take a look at the info files for, say, GNU Make, it very
much is a full manual.

Note: In Debian, "info make" will show the man page if you don't have
the info pages installed, which are part of the make-doc package.
Perhaps this is why you think info is a quick reference?

> 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.

In the case of the info pages for make, the FSF may very well have
been able to engage a professional tech writer to help with writing
the GNU make manual.  The FSF does make money selling dead-tree
editions of the make manual.  It doesn't make a lot of money, since
the exact same version is installed in /usr/share/doc/... as as an
info file, but there are those who prefer thumbing through a dead-tree
copy of a manual instead of reading it a screen.

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

Info is optimized for significantely large pieces of documentation
than man pages.  So for example, Perl tries to document everything via
multiple man pages, but since man uses a simple text pager, and it
deosn't have hyperlinks, I don't actually find Perl's attempt to be
either a reference *or* a manual to be terribly useful.  I would much
*prefer* if the perl manual were available as a set of info pages,
since having internal hypertext links and a real indexing mechanism
would make it far superior than trying to navigate perl's man page
hierarchy.

As it is, I tend to just give up and use Google plus various web
pages, including StackExchange, but that doesn't work well if I'm
off-line.  Info pages work just *fine* off-line.  Or, as you've
pointed out many people do, I'll take existing perl scripts and copy
snippets out of them, using the cargo-cult school of programming.  But
using perl's man pages is mostly an exercise in frustration.

						- Ted

Re: [TUHS] man-page style

[arnold]

Clem Cole <clemc@ccc.com> wrote:

> I think that's somewhat backwards in he spirit of 'UNIX'...  the man and
> info pages should reference the manual in /usr/doc/foo/

The goal for Info was to *be* the equivalent of /usr/doc/foo. Along the
way the default for Info changed to go to the 'invoking' section of a
manual so that you saw the options, arguably the most immediately
useful part of a man page, attempting to give the user the best of both
worlds.

All that said, I think this topic has been beaten to death. Info
did not successfully replace man pages.  As a file format, I think
that Info has very little left to offer.

What I do *love* is the Texinfo markup language, which is wonderful
for producing book-style documents.  And what's nice is that a
single input file can produce PDF, HTML and DocBook (as well as Info).

Arnold

Re: [TUHS] man-page style

[Otto Moerbeek]

On Mon, Nov 19, 2018 at 11:52:38PM -0700, arnold@skeeve.com wrote:

> Clem Cole <clemc@ccc.com> wrote:
> 
> > I think that's somewhat backwards in he spirit of 'UNIX'...  the man and
> > info pages should reference the manual in /usr/doc/foo/
> 
> The goal for Info was to *be* the equivalent of /usr/doc/foo. Along the
> way the default for Info changed to go to the 'invoking' section of a
> manual so that you saw the options, arguably the most immediately
> useful part of a man page, attempting to give the user the best of both
> worlds.
> 
> All that said, I think this topic has been beaten to death. Info
> did not successfully replace man pages.  As a file format, I think
> that Info has very little left to offer.
> 
> What I do *love* is the Texinfo markup language, which is wonderful
> for producing book-style documents.  And what's nice is that a
> single input file can produce PDF, HTML and DocBook (as well as Info).
> 
> Arnold

I'd like to mention mandoc. It takes mdoc or man pages and produces
output in various formats. See e.g. http://man.openbsd.org/mandoc. The
formatting and links are derived from the semantic info in the source
pages.x

	-Otto

[TUHS] man-page style

[Eric Allman]

[I sent this almost a week ago, but it never showed up, probably because
my From address didn't match my subscription address.  Apologies if this
is a dup.]

On 2018-11-19 07:35 , Clem Cole wrote:
> As I said, if man had been maintained as the primary >>manual<< style
> interface and /usr/doc/<PROG>/foo.ms <http://foo.ms> as the primary
> scheme (which >>IS<< what BSD did), then you don't fail the rule of
> least astonishment. 

On 2018-11-19 09:39 , Theodore Y. Ts'o wrote:
> 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.  So I dare say the goal that the man page should be the
> primary manual was a bit of an aspiration goal as well.

The /usr/doc/<PROG>/... convention started at least as far back as 7th
Edition (and I think 6th as well).  There was no attempt to make the man
page for yacc or troff document everything you needed to know --- they
basically listed the command line arguments and gave you a pointer to
the real manual, which went into far more depth than would be feasible
in a man page, sometimes including things like tables and figures (using
tbl and fig, of course).

Speaking of troff, that was interesting documentation.  Ossanna's
documentation told you exactly what all of the commands did, but didn't
say why they did it.  Many of the features seemed absolutely crazy at
first.  I probably read that document 50 times when writing the -me
macros, every time having a light bulb go off in my head.  I finally
concluded that _everything_ was needed to do something useful, and you
could do pretty much _anything_ with the available tools (including
things like page balancing).  A master work of design, and blissfully
complete documentation (even if a bit obscure to the newbie).

eric

Re: [TUHS] man-page style

[G. Branden Robinson]

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

At 2018-11-27T16:09:12-0800, Eric Allman wrote:
> Speaking of troff, that was interesting documentation.  Ossanna's
> documentation told you exactly what all of the commands did, but didn't
> say why they did it.  Many of the features seemed absolutely crazy at
> first.  I probably read that document 50 times when writing the -me
> macros, every time having a light bulb go off in my head.  I finally
> concluded that _everything_ was needed to do something useful, and you
> could do pretty much _anything_ with the available tools (including
> things like page balancing).  A master work of design, and blissfully
> complete documentation (even if a bit obscure to the newbie).

Hi Eric,

I've been working on groff, and a while back, amid tidying up the
groff_me(7) man page, I added the following to the Notes section:

.
It is not known for certain what the \(lqe\(rq in \(lqme\(rq stands for,
but one can infer a derivation from the first initial of Eric P.\&
Allman (then of the University of California), who wrote the original
technical papers documenting the package.
.

I've done some digging but could not locate an authoritative statement.
Would you like to make one?

This list has been helpful in clearing up some other historical
inaccuracies in the groff man pages, though surely some remain.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [TUHS] man-page style

[Eric Allman]

On 2018-11-27 4:36 PM, G. Branden Robinson wrote:
> Hi Eric,
> 
> I've been working on groff, and a while back, amid tidying up the
> groff_me(7) man page, I added the following to the Notes section:
> 
> .
> It is not known for certain what the \(lqe\(rq in \(lqme\(rq stands for,
> but one can infer a derivation from the first initial of Eric P.\&
> Allman (then of the University of California), who wrote the original
> technical papers documenting the package.
> .
> 
> I've done some digging but could not locate an authoritative statement.
> Would you like to make one?

That's basically correct, but there is a back story.  When I started
writing the -me macros it began as something in my private tree (I don't
remember what I called it).  Then some other folks on the INGRES project
wanted to use it, but our system admin at the time didn't want to dicker
with the system namespace at the behest of a mere undergraduate, so he
didn't like anything that was actually descriptive lest people think it
was "official".  He finally consented to "-meric" (which I always
hated), since it was obviously non-official.  By the time my macros
became popular around Berkeley it got shortened to "-me", much to my relief.

Of course, if AT&T had been willing to let Berkeley have -ms then most
likely -me would never have happened at all.  Without a macro package,
nroff/troff is basically unusable; -me stepped into the vacuum.

Amusingly enough, one of the most popular features of -me was ".th"
mode, which set all the parameters to match the official constraints for
a U.C. Berkeley Ph.D. thesis.  It was guaranteed to get past the "dragon
lady" who would reject the thesis if the margins were wrong.

eric

Re: [TUHS] man-page style

[G. Branden Robinson]

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

At 2018-11-27T16:57:43-0800, Eric Allman wrote:
> > It is not known for certain what the \(lqe\(rq in \(lqme\(rq stands for,
> > but one can infer a derivation from the first initial of Eric P.\&
> > Allman (then of the University of California), who wrote the original
> > technical papers documenting the package.
[...]
> That's basically correct, but there is a back story.  When I started
> writing the -me macros it began as something in my private tree (I don't
> remember what I called it).  Then some other folks on the INGRES project
> wanted to use it, but our system admin at the time didn't want to dicker
> with the system namespace at the behest of a mere undergraduate, so he
> didn't like anything that was actually descriptive lest people think it
> was "official".  He finally consented to "-meric" (which I always
> hated), since it was obviously non-official.  By the time my macros
> became popular around Berkeley it got shortened to "-me", much to my relief.

The shortening also prevented associations with an ignominious character
in an episode of the original _Star Trek_[1], which would surely have
been especially bad marketing in the geek culture of the time.

> Of course, if AT&T had been willing to let Berkeley have -ms then most
> likely -me would never have happened at all.  Without a macro package,
> nroff/troff is basically unusable; -me stepped into the vacuum.

I'm thinking it was an even larger example of silly cussedness because
by then, weren't the mm macros considered the new hotness at AT&T?

> Amusingly enough, one of the most popular features of -me was ".th"
> mode, which set all the parameters to match the official constraints for
> a U.C. Berkeley Ph.D. thesis.  It was guaranteed to get past the "dragon
> lady" who would reject the thesis if the margins were wrong.

It takes a computer to beat a computer.  :)

Thank you!  I'll update the man page.  We seem to be finally be on the
precipice of a groff 1.22.4 release (knock touchpad).

Regards,
Branden

[1] "Bread and Circuses"

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [TUHS] man-page style

[arnold]

Eric Allman <tuhs@eric.allman.name> wrote:

> [I sent this almost a week ago, but it never showed up, probably because
> Speaking of troff, that was interesting documentation.  Ossanna's
> documentation told you exactly what all of the commands did, but didn't
> say why they did it.  Many of the features seemed absolutely crazy at
> first.  I probably read that document 50 times when writing the -me
> macros, every time having a light bulb go off in my head.  I finally
> concluded that _everything_ was needed to do something useful, and you
> could do pretty much _anything_ with the available tools (including
> things like page balancing).  A master work of design, and blissfully
> complete documentation (even if a bit obscure to the newbie).

Any chance you, or someone else, could write that missing manual that
explains the "why" of the various troff features?

I've been through CSTR 54 a few times too, although I haven't tried
to write a macro package from scratch, and I have to admit that there
are things that mystify me.

Thanks!

Arnold

Re: [TUHS] man-page style

[Eric Allman]

On 2018-11-28 23:25 , arnold@skeeve.com wrote:

> Any chance you, or someone else, could write that missing manual that
> explains the "why" of the various troff features?
> 
> I've been through CSTR 54 a few times too, although I haven't tried
> to write a macro package from scratch, and I have to admit that there
> are things that mystify me.

At this point it's been so many years since I was actively working on
troff that it would require more-or-less starting from zero.  Perhaps
when I retire I'll have that kind of time.

eric

Re: [TUHS] man-page style

[Larry McVoy]

On 2018-11-28 23:25 , arnold@skeeve.com wrote:
> Any chance you, or someone else, could write that missing manual that
> explains the "why" of the various troff features?
> 
> I've been through CSTR 54 a few times too, although I haven't tried
> to write a macro package from scratch, and I have to admit that there
> are things that mystify me.

There is a lot to be mystified about in *roff but there is a lot to like
as well.  If you are going to start to look into one, I'd strongly urge
you to look at groff & friends.  It's by far the most actively developed
tool in the roff family.

I'm happy to answer what questions I can (though there is stuff that's
faded like the whole environment stack thing).  I've not written an
entire macro package either, but I've written a bunch of macros.  And
done a bunch of stuff in pic, I love pic.  I got James to put the

`i'th last <whatever>

construct into pic.  Super useful.

Re: [TUHS] man-page style

[arnold]

Eric Allman <tuhs@eric.allman.name> wrote:

>
> On 2018-11-28 23:25 , arnold@skeeve.com wrote:
>
> > Any chance you, or someone else, could write that missing manual that
> > explains the "why" of the various troff features?
> > 
> > I've been through CSTR 54 a few times too, although I haven't tried
> > to write a macro package from scratch, and I have to admit that there
> > are things that mystify me.
>
> At this point it's been so many years since I was actively working on
> troff that it would require more-or-less starting from zero.  Perhaps
> when I retire I'll have that kind of time.

OK, we'll hold you to it. :-)

Thanks,

Arnold

Re: [TUHS] man-page style

[Steffen Nurpmeso]

Chet Ramey wrote in <e8810295-5146-e126-a4d8-65e814f4b431@case.edu>:
 |On 11/16/18 4:13 PM, Jon Steinhart wrote:
 |
 |> Well, not wanting to start a flame war here, but I don't use emacs. \
 |>  While
 |> it's a good piece of software, I just want a text editor.  Emacs sort of
 |> violates my UNIX-sense as it does many things instead of doing one thing
 |> well.
 |
 |That's fine. Everyone gets to use whatever they want.
 |
 |> But really the issue is that info introduced a new interface on a system
 |> that already had one that people were accustomed to.
 |
 |Improvement is in the eye of the beholder. RMS and other folks consider
 |info, with its hyperlinks, indexes, and tree-based navigation the superior
 |alternative.  Not just different, but better.

roff, however, does provide the power to support all that: all
you need to do is to write the macros that do this for you.
One thing i have never understood is that.  Just do it.  I always
wondered at first when i saw coming along the blue links in the
man markup that the Linux world introduced.  Which is very
half-assed!

Mind you, i have to say, i actually have written such a thing for
the mdoc(7) manual macros (called mdocmx), and it gives you
interactivity on a normal terminal, or in HTML, or in PDF, it
gives you TOC and it could give you more.  I couldn't even live
without it no more, it improves living with the large manual of
the MUA i maintain tremendously.

Half-assed, too, is that even after fourty or more years of Unix
manual pages you cannot even search properly in a displayed manual
page, or at least you will not find anything that uses the usual
and old-style BS formatting sequences (that my mdocmx uses to
embed the informations, for example).  I never thought about that,
but Jörg Schilling mentioned that his pager (as simply as it may
be) is capable of doing so (by reduction, he said, though).

But the largest pain is non-existent, incomplete, or unfindable
documentation.  This cannot be said about bash or mksh, not about
tmux or screen, not about the documentation of Plan9, and not
over the MUA i maintain i hope.  But i have just moved over to
Linux on bare metal, and even though the Linux man-page project
has made an _immense_ effort and has achieved equal improvements,
it took a long time to get all this going (on a minimal
Distribution which does not do all of that automatically for you,
because years of experience have created an internal database full
of hints which are used to do-the-right-thing).

I could actually enumerate a scary long list of problems (on two
old notebooks, a MacBook Air and an Acer Aspire, external Seagate
USB disk, USB WLAN), but from back in the Eighties or even older
is that US keyboard do not honour "ISO_Level3_Shift" unless
setxkbmap 'us(intl)' is called.  I mean, you use xev(1) and the
event flies by, but the driver does not do anything with it.  How
do you find that out.  Just like with many other things you have
to face a lot of those toilet writings that make up the internet
before you get something good.  The ArchLinux wiki is very often
a useful and helpful source, but better not look in the web
support forums of the large distributions, who get paid, if you
can look into them at all.

It seems the wonderful tradition of HOWTOs or good things
including documentation under /usr/share (on BSDs) has been
entirely lost.

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)

Re: [TUHS] man-page style

[Donald ODona]

At 19 Nov 2018 03:11:00 +0000 (+00:00) from Chet Ramey <chet.ramey@case.edu>:
>
> The man page for bash includes everything. The info manual includes more
> examples. I think other authors should follow that model, but I'm not going
> to tell a volunteer what he has to do, and I understand how difficult it is
> to maintain parallel content.

'info' is technologically spoken 'superior'. However replacing 'info' by html, what someone recommended for 'emacs'(sic!), is even more superior.

However superior isn't really of great importance. nroff is good enough, its used by millions of *NIX users since more than 40 years, whereas 'info' is only used by a small sect.
Hence, I recommend to stop using 'info' at all, avoiding the maintenance of parallel and unused contents.

Re: [TUHS] man-page style

[Warner Losh]

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

On Fri, Nov 16, 2018 at 2:40 PM Jon Steinhart <jon@fourwinds.com> wrote:

> Emacs sort of
> violates my UNIX-sense as it does many things instead of doing one thing
> well.


I'd argue that's not a bad thing. When people tried to add macros to make
or sendmail, you wound up with crazy like imake or the crazy sendfile.m4
stuff. Of course, sendmail and one thing aren't mates, but sometimes you
need to do a few, well chosen things well to avoid the crazy that trying to
misuse something will bring to the table.

Warner

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

Re: [TUHS] man-page style

[Bakul Shah]

On Mon, 19 Nov 2018 00:05:08 -0700 Warner Losh <imp@bsdimp.com> wrote:
>
> On Fri, Nov 16, 2018 at 2:40 PM Jon Steinhart <jon@fourwinds.com> wrote:
>
> > Emacs sort of
> > violates my UNIX-sense as it does many things instead of doing one thing
> > well.

This is only half the story. Unix also provides a way to
assemble these tools to carry out a specific task.

> I'd argue that's not a bad thing. When people tried to add macros to make
> or sendmail, you wound up with crazy like imake or the crazy sendfile.m4
> stuff. Of course, sendmail and one thing aren't mates, but sometimes you
> need to do a few, well chosen things well to avoid the crazy that trying to
> misuse something will bring to the table.

The problem was sendmail didn't have a decent builtin glue
language to customize it. More generally, you can't just
provide domain specific objects, you have to provide a domain
specific algebra as well, so to speak. And you don't have to
provide domain specific syntax.

Re: [TUHS] man-page style

[Jon Steinhart]

Warner Losh writes:
> On Fri, Nov 16, 2018 at 2:40 PM Jon Steinhart <jon@fourwinds.com> wrote:
>
> > Emacs sort of
> > violates my UNIX-sense as it does many things instead of doing one thing
> > well.
>
>
> I'd argue that's not a bad thing. When people tried to add macros to make
> or sendmail, you wound up with crazy like imake or the crazy sendfile.m4
> stuff. Of course, sendmail and one thing aren't mates, but sometimes you
> need to do a few, well chosen things well to avoid the crazy that trying to
> misuse something will bring to the table.
>
> Warner

Funny that you bring this up as I was just talking to Eric about this.
I was telling him that someone had recently asked me why sendmail was
so complicated, and I explained to them that it was because email wasn't
always like it is today; that there were many disparate email systems and
sendmail glued them all together.  Eric said something like yeah, and I
would have liked to have a better syntax but memory was too constrained
at the time to let me do anything better.

[TUHS] man-page style

[Eric Allman]

[I sent this almost a week ago, but it never showed up, probably because
my From address didn't match my subscription address.  Apologies if this
is a dup.]

I confirm Jon's observation.  It's true, sendmail wasn't "designed" in
the waterfall model sense, because at the time the email world was a
disaster, with new networks appearing seemingly daily, each of which
seemed to feel a need to come up with a new syntax for addresses.  Some
of those syntaxes were left-associative and some right-associative, and
there was no "correct" answer --- different sites wanted to parse the
same email address differently.  For example, consider:

	decvax!research!foo@berkeley

If you're on decvax you should send this to research.  If you're at
Berkeley you should send this to decvax.  And if you're on some other
site with an ARPAnet connection but without UUCP, you should send it to
Berkeley.  I concluded that something arbitrarily flexible (which meant
Turing Complete) was necessary.  Also, since some sites didn't
understand things like "@" signs in addresses, it was necessary to
rewrite the header so "reply" would work.  And all of this had to fit
into a 16-bit address space.

Life is easier today: the world has agreed on "user@domain", the
multitude of networks (e.g., UUCP, DECnet, CSNet, Berknet, ChaosNet,
PurdueNet, and possibly my favorite, a network out of the UK that used
"user@domain" but with the domain reversed, e.g., eric@edu.berkeley.cs
instead of eric@cs.berkeley.edu) is down to effectively one, and the
only 16-bit machines out there are not-very-powerful microcontrollers.
If I were building sendmail in this very different world, it would look
very different.

eric


On 2018-11-19 08:48 , Jon Steinhart wrote:
> Warner Losh writes:
>> On Fri, Nov 16, 2018 at 2:40 PM Jon Steinhart <jon@fourwinds.com> wrote:
>>
>>> Emacs sort of
>>> violates my UNIX-sense as it does many things instead of doing one thing
>>> well.
>>
>>
>> I'd argue that's not a bad thing. When people tried to add macros to make
>> or sendmail, you wound up with crazy like imake or the crazy sendfile.m4
>> stuff. Of course, sendmail and one thing aren't mates, but sometimes you
>> need to do a few, well chosen things well to avoid the crazy that trying to
>> misuse something will bring to the table.
>>
>> Warner
> 
> Funny that you bring this up as I was just talking to Eric about this.
> I was telling him that someone had recently asked me why sendmail was
> so complicated, and I explained to them that it was because email wasn't
> always like it is today; that there were many disparate email systems and
> sendmail glued them all together.  Eric said something like yeah, and I
> would have liked to have a better syntax but memory was too constrained
> at the time to let me do anything better.
> 

Re: [TUHS] man-page style

[Larry McVoy]

> If I were building sendmail in this very different world, it would look
> very different.
> 
> eric

Indeed.  Sendmail got a lot of hate but mostly from people in pure
user@host.domain worlds.  I lived in the UUCP / BitNet / Arpanet
world and while sendmail was definitely not the easiest thing to
configure, once you got it right it just kept working (unlike UUCP
that seemed to need constant babysitting).

Re: [TUHS] man-page style

[Grant Taylor via TUHS]

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

On 11/29/2018 11:48 AM, Larry McVoy wrote:
> Indeed.  Sendmail got a lot of hate but mostly from people in pure 
> user@host.domain worlds.

Do you have any idea why the user@host.domain community hated on 
Sendmail more than other communities?

> I lived in the UUCP / BitNet / Arpanet world and while sendmail was 
> definitely not the easiest thing to configure, once you got it right it 
> just kept working (unlike UUCP that seemed to need constant babysitting).

I think that's still fair to say.

Though simple Sendmail configurations are relatively easy to set up.



-- 
Grant. . . .
unix || die


[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4008 bytes --]

Re: [TUHS] man-page style

[Larry McVoy]

On Thu, Nov 29, 2018 at 12:13:53PM -0700, Grant Taylor via TUHS wrote:
> On 11/29/2018 11:48 AM, Larry McVoy wrote:
> >Indeed.  Sendmail got a lot of hate but mostly from people in pure
> >user@host.domain worlds.
> 
> Do you have any idea why the user@host.domain community hated on Sendmail
> more than other communities?

I can't back this up with a citation but my belief is that was just that
everything worked for them, it was a simple system, you could write an
SMTP server in a tiny perl script, so why all the complexity?

If you live in a simple world you see things as being simple.  Sendmail
was not living in a simple world.

> >I lived in the UUCP / BitNet / Arpanet world and while sendmail was
> >definitely not the easiest thing to configure, once you got it right it
> >just kept working (unlike UUCP that seemed to need constant babysitting).
> 
> I think that's still fair to say.
> 
> Though simple Sendmail configurations are relatively easy to set up.

Yeah, it's been easy since whoever did the macros so you picked a config
close to yours, changed a couple of host names and off you go.

It's surprisingly similar to troff.  Writing docs in raw troff is doable,
I've done it a bunch of times, but it's more pleasant with a macro 
package (I'm a fan of -ms, tried the others, just keep coming back to
-ms because it hits the sweet spot of enough stuff without being overly
complicated).

Re: [TUHS] man-page style

[Chet Ramey]

On 11/29/18 11:13 AM, Grant Taylor via TUHS wrote:
> On 11/29/2018 11:48 AM, Larry McVoy wrote:
>> Indeed.  Sendmail got a lot of hate but mostly from people in pure
>> user@host.domain worlds.
> 
> Do you have any idea why the user@host.domain community hated on Sendmail
> more than other communities?

They didn't need its flexibility, so they had all kinds of bones to pick
with the architecture.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Warner Losh]

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

On Thu, Nov 29, 2018 at 12:33 PM Chet Ramey <chet.ramey@case.edu> wrote:

> On 11/29/18 11:13 AM, Grant Taylor via TUHS wrote:
> > On 11/29/2018 11:48 AM, Larry McVoy wrote:
> >> Indeed.  Sendmail got a lot of hate but mostly from people in pure
> >> user@host.domain worlds.
> >
> > Do you have any idea why the user@host.domain community hated on
> Sendmail
> > more than other communities?
>
> They didn't need its flexibility, so they had all kinds of bones to pick
> with the architecture.
>

The problem we had at the university was that it got things almost right.
Almost. And to track down WTF the macros were doing that caused the almost
was, well, almost impossible due to the twisty, turny nature of the
implementation that made the twists in colossal cave  look sane and
predictable.

Without extreme tweaking, it wouldn't handle foo!bar!bas%bitnet@grubkle.edu
correctly...  Mostly because it was ambiguous and the definition of correct
changed as we went from being a UUCP leaf node to being a full denizen of
the internet on NSFNET.

Warner

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

Re: [TUHS] man-page style

[Chet Ramey]

On 11/29/18 11:36 AM, Warner Losh wrote:

> Without extreme tweaking, it wouldn't handle foo!bar!bas%bitnet@grubkle.edu
> <mailto:bas%25bitnet@grubkle.edu> correctly...  Mostly because it was
> ambiguous and the definition of correct changed as we went from being a
> UUCP leaf node to being a full denizen of the internet on NSFNET.

Exactly. That is inherently ambiguous and subject to local policy. There is
almost no way to handle it "correctly" in all situations.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[WIlliam Cheswick]

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

I sat down to my first TCP/IP connected host around 1985, and the first thing I wanted to do was to configure my first non-UUCP email machine.

After an hour of wading through sendmail’s state machines, I gave up wondering why it had to be so hard.  

In the amazing 184 BSTJ, Dave Presotto had described upas, the replacement he built for sendmail.  I loved its ease of use, and it was one of the reasons I wanted to join 1127, which I did in late 1987.

I supported email and upas for a number of years, including the {bitnet | csnet | uucp | acsnet(?)} -> domain migration.  Like the proverbial (and non-existent) boiling frog, this crept up on me: it was a mild surprise to realize we were using the other stuff much any more.

Aside from configuration issues, the main complaint with sendmail was that it was a huge program running as root, with intentional and unintentional holes in.  For many years it was a steady source of security problems, including its use in the Morris worm.

That said, sendmail is still running, and handling a fair amount of mail, I believe.  A few years ago I checked for recent security problems and found none reported.  I think this is a case of “software annealing”: if you don’t change the specs much, and keep working on it, you will eventually get most of the bugs.

As for the configuration: when Norman Wilson moved to Toronto, he implemented some form of little language for configuring sendmail, treating it somewhat as an assembly language.  I don’t know the details, but they might be of interest.

> On Nov 29, 2018, at 1:48 PM, Larry McVoy <lm@mcvoy.com> wrote:
> 
> Indeed.  Sendmail got a lot of hate but mostly from people in pure
> user@host.domain <mailto:user@host.domain> worlds.  I lived in the UUCP / BitNet / Arpanet
> world and while sendmail was definitely not the easiest thing to
> configure, once you got it right it just kept working (unlike UUCP
> that seemed to need constant babysitting).


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

[TUHS] Upas rewrite little language

[William Cheswick]

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

Whoa! I hadn’t realized that I have in my archives mail configuration files from no later that 1993.  Here is one rewrite file from “research”, as in “research!dmr":

more rewrite 
# local mail
[^!@%.=]+               translate       "exec /v/lib/upas/translate '&'"
local!([^!@]+)          >>              /usr/spool/mail/\1
\l!(.+)                 alias           \1
research\.att\.com!(.+) alias           \1
research\.research\.att\.com!(.+)       alias           \1
plan9\.research\.att\.com!(.+)  alias   \1

league\.att\.com!(.+)   alias           league!\1
league\.research\.att\.com!(.+) alias   league!\1
league!(.+)             alias   \1


# convert @ format to ! format
([^!]+)@([^!@]+)        alias   \2!\1

# convert % addresses for us only.
([^!]+)%([^!%]+)        alias   \2!\1

# network gateways

uucp!(.+)               alias   \1
bitnet!(.+)             alias   inet!bitnet!\1
uunet!(.+)              alias   inet!uunet.uu.net!\1
.*tempo\.att\.com!.*    | "exec /v/lib/upas/route '\s' allegra.att.com" "'&'"
vax135!(.*)             | "exec /v/lib/upas/route '\s' big.l1135.att.com" "\1"
\[([^!]+)\]!(.+)        |       "exec /v/lib/upas/route.ip '\s' '\1'" "'\2'"
([^!]+\.att\.com)!(.+)  |       "exec /v/lib/upas/route '\s' '\1'" "'\2'"
[^!]+\..*               |       "exec /v/lib/upas/route '\s' inet" "'&'"
([^!]+)!(.+)            |       "exec /v/lib/upas/route '\s' '\1'" "'\2’"


====

and here is the rewrite file for the mail application gateway no later than 1998:

#  get rid of the .att.com domain part of the name.
#  It's not used internally.
([^%!@.]+)\.att\.com!(.+)		alias	\1!\2

# the following must change: we don't really want these used.
att\.com!(.+)				alias	\1
att\.arpa!(.+)				alias	\1
(arpa|att-gw|gate)(\.arpa)?!(.+)	alias	\3

# rerouting:
uunet!(.+)		alias	uunet.uu.net!\1
mcvax!(.+)		alias	uunet.uu.net!mcvax!\1
local!(.+)		>>	/usr/spool/mail/\1
#tempo!(.+)		alias	research!tempo!\1
sola!(.+)		alias	jones!\1

# a very common mistake
.*!			|	"echo Bad address: '&'; exit 1"
# a problem at cunyvm.
cunyvm\.cuny\.edu!(cunyvm\.cuny\.edu)!(.+)	alias	\1!\2

# gateways
uucp!(.+)		alias	\1
csnet!(.+)		alias	relay.cs.net!\1
bitnet!([^!]+)!(.+)	alias	CUNYVM.CUNY.EDU!\1.BITNET!\2
bitnet!([^!]+)@([^!]+)	alias	CUNYVM.CUNY.EDU!\2.BITNET!\1
mailnet!([^!]+)!(.+)	alias	mit-multics.arpa!\1.MAILNET!\2
acsnet!(.+)		alias	research!&
attmail!(.+)		auth	false
# attmail!(.+)		alias	attbl!attmail!\1

# convert @ format to ! format always (so locals can use @ format)
(.+)@([^!@]+)			alias	\2!_pct_!\1

# convert % format only if the first hop isn't on the internet.
([^!]+)%([^!%]+)			alias	\2!\1
([^!.]+)!(.+!)?_pct_!(.+)%([^!%]+)	alias	\1!\2\4!_pct_!\3
([^!.]+)!(.+)%([^!%]+)			alias	\1!\3!_pct_!\2

# get rid of our _pct_ tag
((.+)!)?_pct_!(.+)			alias	\1\3

# don't route through research just to get to another machine
# this MUST follow the %@ conversion
research!([^!]+)!(.+)			alias   \1!\2
research!([^!]+)			alias	inet!\1

# at this point, anything without a "."  in the first component
inet!(.+)               	|       "exec /usr/lib/upas/route.inet '\s' inet" "'\1'"
(att|coma|alice|allegra)!(.+)	|       "exec /usr/lib/upas/route.toatt '\s' \1" "'\2'"
([^.!]+)!(.+)           	|       "exec /usr/lib/upas/route.toatt '\s' att" "'&'"

#	Only local or Internet Domain addresses below this line.

# various semi-official domain addresses
([^!]+)\.(csnet|bitnet|acsnet|mailnet|uucp)!(.*) alias	\2!\1!\3

# Domain routings - arranged with the other AT&T postmasters
sf\.att\.com!(.+)				alias	attunix!\1
([^!.]+)\.sf\.att\.com!(.+)			alias	attunix!\1!\2
([^!.]+)\.(astro|mercury|phone|div111)\.nj\.att\.com!(.+)	alias   \1!\2
([^!]*\.)?mis\.oh\.att\.com!.+			alias	att!&
([^!]*\.)?dptg\.att\.com!.+			alias	dptg!&
([^!]*\.)?garage(\.nj)?\.att\.com!.+		alias	garage!&
([^!]*)\.tempo(\.nj)?\.att\.com!(.+)		alias	\1!\3
([^!]*\.)?homer\.nj\.att\.com!.+		alias	ulysses!&
([^!]+)\.aloft\.att\.com!(.+)			alias	aloft!&
(([^!]*\.)?uso\.att\.com)!(.+)  |  "smtpqer -n -d .att.com -H att.att.com '\s' '\1'" "'\3'"
([^!]+)\.att\.com(\.)?!(.+)	| "echo 'Unknown AT\&T domain:' '&' >\&2; exit 1"

# Ready to send Internet mail.
([^!]+)!(.+)            |  "smtpqer -n -d .att.com -H att.att.com '\s' '\1'" "'\2'"

#	carefully selected local translates

postmaster		alias		coma!postmaster
[^!@%]*[._]+[^!@%]*	translate	\
	"exec /usr/lib/post/post -o '%^25name  %20ema  %^city, %+state ' -x -- '&'"
[^!@%]+			translate	"exec translate '&'"
[^!@%]+			>>		/usr/spool/mail/&


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

Re: [TUHS] man-page style

[Dave Horsfall]

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

On Fri, 30 Nov 2018, WIlliam Cheswick wrote:

> I supported email and upas for a number of years, including the {bitnet 
> | csnet | uucp | acsnet(?)} -> domain migration.  Like the proverbial 
> (and non-existent) boiling frog, this crept up on me: it was a mild 
> surprise to realize we were using the other stuff much any more.

Err, why the query after ACSnet?  We in Oz preferred it over UUCP, because 
it was far superior, with self-routing etc.

-- Dave

Re: [TUHS] man-page style

[WIlliam Cheswick]

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

We supported many nets, including ACSnet:

uucp!research!ches
bitnet!templevm!rdk
csnet!<host>!<user>
acsnet!<host>!<user>

I didn’t remember the exact name of the net, but we delivered to it.

> On Nov 30, 2018, at 5:58 PM, Dave Horsfall <dave@horsfall.org> wrote:
> 
> Err, why the query after ACSnet?


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

Re: [TUHS] man-page style

[arnold]

WIlliam Cheswick <ches@cheswick.com> wrote:

> As for the configuration: when Norman Wilson moved to Toronto, he
> implemented some form of little language for configuring sendmail,
> treating it somewhat as an assembly language.

Not from Norman (I'm pretty sure), there was a program called 'ease'
that did just that. Using it, I wrote a sendmail config file *from scratch*
for the computing center and math/cs system at Emory U, where I worked
at the time.

Because of that, the Morris worm totally passed us by. :-)

I think that I have literally forgotten more about sendmail than most
people ever know, and I'm totally OK with that. :-)

Arnold

Re: [TUHS] man-page style

[Grant Taylor via TUHS]

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

On 12/1/18 12:53 PM, arnold@skeeve.com wrote:
>> As for the configuration: when Norman Wilson moved to Toronto, he 
>> implemented some form of little language for configuring sendmail, 
>> treating it somewhat as an assembly language.
> 
> Not from Norman (I'm pretty sure), there was a program called 'ease' 
> that did just that. Using it, I wrote a sendmail config file *from scratch* 
> for the computing center and math/cs system at Emory U, where I worked 
> at the time.

Where can I find out more about 'ease' and what Normal wrote & used?

I'm quite fond of m4, which I picked up from Sendmail < 20 years ago.

> Because of that, the Morris worm totally passed us by. :-)

:-)

> I think that I have literally forgotten more about sendmail than most 
> people ever know, and I'm totally OK with that. :-)

I do think that I've gotten a better understanding of email, and SMTP in 
general, than some of my coworkers thanks to Sendmail and my pursuit of 
making it work.



-- 
Grant. . . .
unix || die


[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4008 bytes --]

[TUHS] Ease (was Re: man-page style)

[arnold]

Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:

> > Not from Norman (I'm pretty sure), there was a program called 'ease' 
> > that did just that. Using it, I wrote a sendmail config file *from scratch* 
> > for the computing center and math/cs system at Emory U, where I worked 
> > at the time.
>
> Where can I find out more about 'ease' and what Norman wrote & used?

Ease was posted in comp.sources.<something> and I think there was
;login: article about it. We're talking mid-1980s here. I subsequently
added a few features to it, mainly to support features in Sun's sendmail.

It's mentioned in Eric's (I think) book about Sendmail from the late 80s
or early 90s (and I have a footnote in there, I think).

I will see if I can dig up the sources.  It would undoubtedly take some
work to bring them into the 21st century.

Arnold

Re: [TUHS] Ease (was Re: man-page style)

[Grant Taylor via TUHS]

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

On 12/2/18 12:22 AM, arnold@skeeve.com wrote:
> Ease was posted in comp.sources.<something> and I think there was ;login: 
> article about it. We're talking mid-1980s here. I subsequently added a 
> few features to it, mainly to support features in Sun's sendmail.
> 
> It's mentioned in Eric's (I think) book about Sendmail from the late 
> 80s or early 90s (and I have a footnote in there, I think).
> 
> I will see if I can dig up the sources.  It would undoubtedly take some 
> work to bring them into the 21st century.

Thank you for the information.

I'll see if I can't find at something in the Usenet archives.



-- 
Grant. . . .
unix || die


[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4008 bytes --]

Re: [TUHS] Ease (was Re: man-page style)

[arnold]

Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:

> On 12/2/18 12:22 AM, arnold@skeeve.com wrote:
> > Ease was posted in comp.sources.<something> and I think there was ;login: 
> > article about it. We're talking mid-1980s here. I subsequently added a 
> > few features to it, mainly to support features in Sun's sendmail.
> > 
> > It's mentioned in Eric's (I think) book about Sendmail from the late 
> > 80s or early 90s (and I have a footnote in there, I think).
> > 
> > I will see if I can dig up the sources.  It would undoubtedly take some 
> > work to bring them into the 21st century.
>
> Thank you for the information.
>
> I'll see if I can't find at something in the Usenet archives.

I just now sent the code in direct email.

Arnold

Re: [TUHS] man-page style

[Michael Parson]

On 2018-11-16 14:56, Chet Ramey wrote:
> On 11/16/18 3:52 PM, Dave Horsfall wrote:
>> On Fri, 16 Nov 2018, Toby Thain wrote:
>> 
>>> GNU understood the difference, and wrote separate manuals (e.g. `info
>>> bash`, `info bison`, etc).
>> 
>> GNU "info" is one of the most non-intuitive interfaces that I've ever 
>> had
>> the displeasure to use.  Or maybe that's just me...
> 
> If you don't use emacs, you won't like it.

I don't like gnu info, but when I do need to read those docs, I use 
pinfo instead, which is more like using lynx to read basic hypertext 
docs.

-- 
Michael Parson
Pflugerville, TX
KF5LGQ

Re: [TUHS] man-page style

[Dave Horsfall]

On Sat, 17 Nov 2018, Michael Parson wrote:

> I don't like gnu info, but when I do need to read those docs, I use 
> pinfo instead, which is more like using lynx to read basic hypertext 
> docs.

Wow - just what I need!  Thanks.

BTW, I tried "[p]info info" on a Penguin box, and got basically the 
manpage...

-- Dave (VK2KFU)

Re: [TUHS] man-page style

[Jim Capp]

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

> GNU "info" is one of the most non-intuitive interfaces that I've ever had 
> the displeasure to use. Or maybe that's just me... 

I would cringe anytime I had to use "info" ... I always wondered where it came 
from and why they didn't just stick to traditional man pages. 


Jim 


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

Re: [TUHS] man-page style

[Toby Thain]

On 2018-11-16 3:59 PM, Jim Capp wrote:
>> GNU "info" is one of the most non-intuitive interfaces that I've ever had
>> the displeasure to use.  Or maybe that's just me...
> 
> I would cringe anytime I had to use "info" ... I always wondered where
> it came
> from and why they didn't just stick to traditional man pages.

Hypertext navigation, ToC, indexes. Features we expect from whole books
(the manuals) and not from reference cards.

`info` and `man` solve two different problems, regardless of one's
opinion of the interface to the former (which can be learned, it's no
more arcane than `vi`).

--T

> 
> Jim
> 

Re: [TUHS] man-page style

[Grant Taylor via TUHS]

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

On 11/16/2018 02:24 PM, Toby Thain wrote:
> `info` and `man` solve two different problems, regardless of one's 
> opinion of the interface to the former (which can be learned, it's no 
> more arcane than `vi`).

I feel like the man vs info war (IMHO it's a war) on Linux has gone too 
far.  Far enough that there are some tools that have between woefully 
inadequate man pages to missing man pages in favor of info documentation.

It's worse than solving different problems.



-- 
Grant. . . .
unix || die


[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 3982 bytes --]

Re: [TUHS] man-page style

[Toby Thain]

On 2018-11-16 4:29 PM, Grant Taylor via TUHS wrote:
> On 11/16/2018 02:24 PM, Toby Thain wrote:
>> `info` and `man` solve two different problems, regardless of one's
>> opinion of the interface to the former (which can be learned, it's no
>> more arcane than `vi`).
> 
> I feel like the man vs info war (IMHO it's a war) on Linux has gone too
> far.  Far enough that there are some tools that have between woefully
> inadequate man pages to missing man pages in favor of info documentation.

So you might be glad that Apple seems to have stopped shipping `info`
manuals for the tools that have them :-)

Progress, eh?

> 
> It's worse than solving different problems.
> 
> 
> 

Re: [TUHS] man-page style

[Chet Ramey]

On 11/16/18 4:29 PM, Grant Taylor via TUHS wrote:
> On 11/16/2018 02:24 PM, Toby Thain wrote:
>> `info` and `man` solve two different problems, regardless of one's
>> opinion of the interface to the former (which can be learned, it's no
>> more arcane than `vi`).
> 
> I feel like the man vs info war (IMHO it's a war) on Linux has gone too
> far.  Far enough that there are some tools that have between woefully
> inadequate man pages to missing man pages in favor of info documentation.

Agreed. That's why I supply both, with much the same content.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Lars Brinkhoff]

Jim Capp wrote:
> I would cringe anytime I had to use "info" ... I always wondered where
> it came from

It came from ITS.  That may explain some things.

Re: [TUHS] man-page style

[Dave Horsfall]

On Fri, 16 Nov 2018, Jim Capp wrote:

> I would cringe anytime I had to use "info" ... I always wondered where 
> it camefrom and why they didn't just stick to traditional man pages.

I understand it's because John Gilmore has some sort of an aversion to 
nroff; he is quoted somewhere as "The GNU project does not use nroff" (not 
"free" enough for his delicate sensibilities, maybe?).

-- Dave

Re: [TUHS] man-page style

[Ralph Corderoy]

Hi Jim,

> > GNU "info" is one of the most non-intuitive interfaces that I've
> > ever had the displeasure to use. Or maybe that's just me... 
>
> I would cringe anytime I had to use "info" ... I always wondered where
> it came from

From somewhere that didn't fit in well with Unix.
Its saving grace is piping info(1) made it just dump all the text,
skipping its UI, e.g.  `info gcc | less'.  Because it used to print
formatting progress to stderr!?, it used to need less's `G' then `g' to
skip to the end, getting all the formatting work out of the way, and
then back to the start to redraw the screen, dumping the stderr.

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy

Re: [TUHS] man-page style

[Donald ODona]

At 17 Nov 2018 23:39:45 +0000 (+00:00) from Ralph Corderoy <ralph@inputplus.co.uk>:
> 
> From somewhere that didn't fit in well with Unix.
its based on TekInfo, whereas 'Tek' allegedly refers to the anachronistic Tape Editor and Corrector, developed by a student (Dan Murphy) in 1964 on a PDP-1 without a operation system. According to the myth TekInfo was build on top of the Tape Editor, and finally made it on *NIX.

'Info' really doesn't fit in well with Unix. Its alien and another failed approach. Almost all 'GNU' man pages state, that the 'full' documentation is only available via 'info'. In real 99% of all 'info' requests  result in 'info' processing a man page. Thus its redundant and should be removed from all *NIX systems. Even in emacs some progressive developers recommend to replace 'info' by html or something else modern.

Re: [TUHS] man-page style

[Toby Thain]

On 2018-11-17 7:31 PM, Donald ODona wrote:
> 
> 
> At 17 Nov 2018 23:39:45 +0000 (+00:00) from Ralph Corderoy <ralph@inputplus.co.uk>:
>>
>> From somewhere that didn't fit in well with Unix.
> its based on TekInfo, whereas 'Tek' allegedly refers to the anachronistic Tape Editor and Corrector, developed by a student (Dan Murphy) in 1964 on a PDP-1 without a operation system. According to the myth TekInfo was build on top of the Tape Editor, and finally made it on *NIX.
> 
> 'Info' really doesn't fit in well with Unix. Its alien and another failed approach. Almost all 'GNU' man pages state, that the 'full' documentation is only available via 'info'. In real 99% of all 'info' requests  result in 'info' processing a man page.


In many notable examples, that is not true: e.g. GNU make, bash or bison
come quickly to mind. You can't fully learn how to use tools like these
from the abbreviated man page; for one thing, the man page only mentions
a fraction of the features.

`info` provides a comprehensive, well written manual and tutorial for
these tools. If you haven't seen them, have a good look. Removing `info`
would leave them only partially documented and without tutorials.

--Toby


 Thus its redundant and should be removed from all *NIX systems. Even in
emacs some progressive developers recommend to replace 'info' by html or
something else modern.
> 

Re: [TUHS] man-page style

[Chet Ramey]

On 11/17/18 10:00 PM, Toby Thain wrote:
> On 2018-11-17 7:31 PM, Donald ODona wrote:
>>
>>
>> At 17 Nov 2018 23:39:45 +0000 (+00:00) from Ralph Corderoy <ralph@inputplus.co.uk>:
>>>
>>> From somewhere that didn't fit in well with Unix.
>> its based on TekInfo, whereas 'Tek' allegedly refers to the anachronistic Tape Editor and Corrector, developed by a student (Dan Murphy) in 1964 on a PDP-1 without a operation system. According to the myth TekInfo was build on top of the Tape Editor, and finally made it on *NIX.
>>
>> 'Info' really doesn't fit in well with Unix. Its alien and another failed approach. Almost all 'GNU' man pages state, that the 'full' documentation is only available via 'info'. In real 99% of all 'info' requests  result in 'info' processing a man page.
> 
> 
> In many notable examples, that is not true: e.g. GNU make, bash or bison
> come quickly to mind. You can't fully learn how to use tools like these
> from the abbreviated man page; for one thing, the man page only mentions
> a fraction of the features.

The man page for bash includes everything. The info manual includes more
examples. I think other authors should follow that model, but I'm not going
to tell a volunteer what he has to do, and I understand how difficult it is
to maintain parallel content.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Lars Brinkhoff]

Donald ODona wrote:
> its based on TekInfo, whereas 'Tek' allegedly refers to the
> anachronistic Tape Editor and Corrector, developed by a student (Dan
> Murphy) in 1964 on a PDP-1 without a operation system. According to
> the myth TekInfo was build on top of the Tape Editor, and finally made
> it on *NIX.

Murphy's editor is called TECO:
http://tenex.opost.com/anhc-31-4-anec.pdf

I never heard of TekInfo, or a connection between TECO and INFO.  Where
does this myth come from?

I'm not sure exactly how INFO in ITS evolved.  Maybe it was a separate
program at first, but the latest version is an application written on
top of EMACS.

Re: [TUHS] man-page style

[Lars Brinkhoff]

> I'm not sure exactly how INFO in ITS evolved.  Maybe it was a separate
> program at first, but the latest version is an application written on
> top of EMACS.

Sorry, I didn't check thoroughly enough.  Before EMACS, INFO was written
in PDP-10 assembly language.

Re: [TUHS] man-page style

[Theodore Y. Ts'o]

On Sat, Nov 17, 2018 at 11:38:32PM +0000, Ralph Corderoy wrote:
> 
> From somewhere that didn't fit in well with Unix.
> Its saving grace is piping info(1) made it just dump all the text,
> skipping its UI, e.g.  `info gcc | less'.  Because it used to print
> formatting progress to stderr!?, it used to need less's `G' then `g' to
> skip to the end, getting all the formatting work out of the way, and
> then back to the start to redraw the screen, dumping the stderr.

There is a place for quick reference guides, and a place for a
full-fledged manual, and very often both are available.  So people who
are comparing, unfavorably, man pages and info files, are really
comparing apples and oranges.  (Or perhaps, just enjoy trying to tell
info files to get off their lawn.  :-)

If you think the *contents* of the info file are terrible, then
presumably you would also object to BSD's Programmer's Supplementary
Documents (PSD), User Supplmenetary Documents (USD), or System
Manager's Manual (SMM).

And if it's just that you hate hypertext, that's just the formatting,
and it's quite possible to convert the formatting into your choice of
text, PDF, HTML, ePub, etc.  You can take the source file for the info
file, called the texinfo file, and process it using TeX to generate a
dead-tree version of the file.  Or you can convert the texinfo file to
HTML, for thsoe who like browsers.  Or further convert the HTML to
ePub and then you can read it in your favorite eBook reader.

Cheers,

					- Ted

Re: [TUHS] man-page style

[emanuel stiebler]

On 2018-11-16 15:52, Dave Horsfall wrote:
> On Fri, 16 Nov 2018, Toby Thain wrote:

> GNU "info" is one of the most non-intuitive interfaces that I've ever
> had the displeasure to use.  Or maybe that's just me...

It isn't only you. If I don't find a "man" page for it, then I just
google ...

Re: [TUHS] man-page style

[Warner Losh]

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

On Fri, Nov 16, 2018 at 9:56 AM Paul Winalski <paul.winalski@gmail.com>
wrote:

>  agree with Grant.  If you want to know what a particular command
> does and what its options are, man pages are fantastic.  If you are a
> new or casual user trying to find out what command(s) to use to
> accomplish a particular task, the man pages are an exercise in
> frustration and futility.  Other OSes have done a better job in that
> area (the VMS and DTSS HELP commands come to mind).  IMO ideally one
> should have both--a generalized "help" command for those trying to
> find out what command to use, and "man" as reference material.  UNIX
> and Linux have never had a proper help facility.  Or at least I never
> was able to find it.
>

I've often wanted a 'man -v' which printed a more-verbose version of the
man page, if it were available, otherwise the standard one for
less-often-used commands that are a pita learn at the start, but once you
learn you just want a quick refresher.

Pike could then do a paper 'make -v considered harmful' :)

Warner

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

Re: [TUHS] man-page style

[Grant Taylor via TUHS]

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

On 11/16/2018 09:55 AM, Paul Winalski wrote:
> I agree with Grant.

;-)

> If you want to know what a particular command does and what its options 
> are, man pages are fantastic.

Agreed.

Though, some man pages can still feel overwhelming.  Bash and Zsh (full) 
man pages come to mind.

> If you are a new or casual user trying to find out what command(s) to 
> use to accomplish a particular task, the man pages are an exercise in 
> frustration and futility.

I tend to equate it to trying to learn to program (read: logic behind 
programming) and a given languages (read: syntax, structure, idioms, 
etc) at the same time, you're functionally dealing with two 
interconnected variables in an equation that are almost inseparable.

You almost need to learn other languages to start isolating the the 
logic from the syntax by replacing the syntax with different syntax.

IMHO it's a LOT easier to have an idea what you want to do and then find 
out how to do it than trying to do both at the same time.

> Other OSes have done a better job in that area (the VMS and DTSS HELP 
> commands come to mind).  IMO ideally one should have both--a generalized 
> "help" command for those trying to find out what command to use, and 
> "man" as reference material.  UNIX and Linux have never had a proper 
> help facility.  Or at least I never was able to find it.

I like the sound of that as I start dabbling with OpenVMS.  :-)

I've always liked to find some how-to / tutorials as a starting place to 
give broad overviews and then quickly migrate to and supplement with man 
pages to learn command specifics and behavior.  The how-to provides the 
logic and the man pages provide the syntax.



-- 
Grant. . . .
unix || die


[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 3982 bytes --]

Re: [TUHS] man-page style

[Chet Ramey]

On 11/16/18 1:16 PM, Grant Taylor via TUHS wrote:

> 
> Though, some man pages can still feel overwhelming.  Bash and Zsh (full)
> man pages come to mind.

You should try the POSIX standard. :-)

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Grant Taylor via TUHS]

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

On 11/16/2018 12:35 PM, Chet Ramey wrote:
> You should try the POSIX standard. :-)

/me touches his nose and says "Not me!"

That being said, I'm slowly embarking on OpenVMS.  I'll see what I feel 
like after that.  Though it may have more of an overlap with POSIX than 
I realize.  Particularly if I look at DECnet phase V.  (Granted, that's 
just networking, which is a subset of POSIX.)



-- 
Grant. . . .
unix || die


[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 3982 bytes --]

Re: [TUHS] man-page style

[Bakul Shah]

On Fri, 16 Nov 2018 11:55:28 -0500 Paul Winalski <paul.winalski@gmail.com> wrote:
> On 11/16/18, Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:
> >
> > I think man pages make a great reference.  But I don't think they are a
> > good teaching source for someone that doesn't know the material or what
> > the components are for.
> >
> I agree with Grant.  If you want to know what a particular command
> does and what its options are, man pages are fantastic.  If you are a
> new or casual user trying to find out what command(s) to use to
> accomplish a particular task, the man pages are an exercise in
> frustration and futility.  

When I first came to Unix, I read man pages for every one of
the commands in /bin and experimented with them and tried out
various options. Being a fan of recursion the first thing I
tried was "man man"!  Then I went through all the man pages in
other section to learn about libc functions, special devices
and so on.  I knew about "apropos" (though don't recall if it
was in v7) but I didn't really use it all that much.  Or the
inverted index.

I tend to think software has more in common with carpentry
than science or engineering and like all good craftsman,
knowing how to use all the tools in your workshop is
essential. If you get lucky you get to be an apprentice to a
good mentor but I didn't have that luxury in a startup.

>                            Other OSes have done a better job in that
> area (the VMS and DTSS HELP commands come to mind).  IMO ideally one
> should have both--a generalized "help" command for those trying to
> find out what command to use, and "man" as reference material.  UNIX
> and Linux have never had a proper help facility.  Or at least I never
> was able to find it.

I had usd VMS befoe Unix. Not for long but I don't recall its
help facility being particularly superior.

Each of us learns differently so there is no one true style.

Re: [TUHS] man-page style

[Earl Baugh]

I started on Unix in the ‘80’s and it was to help out a friend with adding waves to a ray tracing system he was building. I knew C at the time... my friend gave me like 5 vi commands and sat me down in front of the terminal with a visual bell. (Luckily I don’t have epilepsy or all that flashing would have had me in seizures :-) )

After answering about 30 questions about library calls available, he taught me the most useful thing I ever learned for Unix. “man -k | grep <word>”.  From there on out, I was on my own and completely equipped to learn all I needed. 

As a side note, when I saw Google fir the first time, I said “oh, man -k | grep for the web....”

Earl 


> On Nov 16, 2018, at 5:25 PM, Bakul Shah <bakul@bitblocks.com> wrote:
> 
>> On Fri, 16 Nov 2018 11:55:28 -0500 Paul Winalski <paul.winalski@gmail.com> wrote:
>>> On 11/16/18, Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:
>>> 
>>> I think man pages make a great reference.  But I don't think they are a
>>> good teaching source for someone that doesn't know the material or what
>>> the components are for.
>>> 
>> I agree with Grant.  If you want to know what a particular command
>> does and what its options are, man pages are fantastic.  If you are a
>> new or casual user trying to find out what command(s) to use to
>> accomplish a particular task, the man pages are an exercise in
>> frustration and futility.  
> 
> When I first came to Unix, I read man pages for every one of
> the commands in /bin and experimented with them and tried out
> various options. Being a fan of recursion the first thing I
> tried was "man man"!  Then I went through all the man pages in
> other section to learn about libc functions, special devices
> and so on.  I knew about "apropos" (though don't recall if it
> was in v7) but I didn't really use it all that much.  Or the
> inverted index.
> 
> I tend to think software has more in common with carpentry
> than science or engineering and like all good craftsman,
> knowing how to use all the tools in your workshop is
> essential. If you get lucky you get to be an apprentice to a
> good mentor but I didn't have that luxury in a startup.
> 
>>                           Other OSes have done a better job in that
>> area (the VMS and DTSS HELP commands come to mind).  IMO ideally one
>> should have both--a generalized "help" command for those trying to
>> find out what command to use, and "man" as reference material.  UNIX
>> and Linux have never had a proper help facility.  Or at least I never
>> was able to find it.
> 
> I had usd VMS befoe Unix. Not for long but I don't recall its
> help facility being particularly superior.
> 
> Each of us learns differently so there is no one true style.

Re: [TUHS] man-page style

[Dave Horsfall]

On Thu, 15 Nov 2018, Grant Taylor via TUHS wrote:

> I think man pages make a great reference.  But I don't think they are a 
> good teaching source for someone that doesn't know the material or what 
> the components are for.

True, but as I mentioned elsewhere we at UNSW has the advantage of a 
docset that Dr John Lions had published; I read them cover to cover and 
taught myself Unix that way.

-- Dave

Re: [TUHS] man-page style

[arnold]

Grant Taylor via TUHS <tuhs@minnie.tuhs.org> wrote:

> On 11/15/2018 10:32 PM, Dave Horsfall wrote:
> > The Unix manpage format is the epitome of perfection; they tell you 
> > everything you need to know, and in the right order.?? Frequently I 
> > cannot recall a particular flag (but I know what it does), and it's 
> > right there at the start.
>
> I think man pages make a great reference.  But I don't think they are a 
> good teaching source for someone that doesn't know the material or what 
> the components are for.

Indeed, the latter was the point of the famed 2nd volume of the Unix
programmer's manual.  The shame is that it was not propogated into
most of the Unix descendants as the man pages were.

Arnold

Re: [TUHS] man-page style

[arnold]

Larry McVoy <lm@mcvoy.com> wrote:

> From my quotes page:
>
> How good is good enough: documentation
>
>     Looking at Sun man pages versus Linux man pages is like looking at a Van
>     Gogh or Monet after studying the work of the high school football player
>     taking art as an "easy" elective. 
>
> Amy Graf, BitMover 

The man page authors / tech writers at Sun were paid to write man
pages, and learned / were taught how to do it well. The Linux stuff is
done by volunteers.  You're comparing apples and oranges.

Arnold

Re: [TUHS] man-page style

[Kurt H Maier]

On Sat, Nov 17, 2018 at 11:14:53AM -0700, arnold@skeeve.com wrote:
>
> The man page authors / tech writers at Sun were paid to write man
> pages, and learned / were taught how to do it well. The Linux stuff is
> done by volunteers.  You're comparing apples and oranges.
        
How do we kill this meme?  Linux is open to contribution by volunteers
but the overwhelming majority of the work done on the OS for *at least*
the last ten years has been by professionals who are paid to work on
Linux.  Pretending otherwise is disingenuous, and anyway I'm not sure
why the OS that powers pacemakers and self-driving car research gets to
be held to a lower standard.
       
khm

Re: [TUHS] man-page style

[arnold]

Kurt H Maier <khm@sciops.net> wrote:

> On Sat, Nov 17, 2018 at 11:14:53AM -0700, arnold@skeeve.com wrote:
> >
> > The man page authors / tech writers at Sun were paid to write man
> > pages, and learned / were taught how to do it well. The Linux stuff is
> > done by volunteers.  You're comparing apples and oranges.
>         
> How do we kill this meme?  Linux is open to contribution by volunteers
> but the overwhelming majority of the work done on the OS for *at least*
> the last ten years has been by professionals who are paid to work on
> Linux.

Is this true of the user land as well?  Maybe gcc, gdb and glibc, but most
of the day-to-day standard Unix commands are volunteer-maintained.

> I'm not sure why the OS that powers pacemakers and self-driving car
> research gets to be held to a lower standard.

A valid point.

Re: [TUHS] man-page style

[Noel Hunt]

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

Surely then, your remarks are a more damning
assessment of the Linux manuals, in that the
terrible state of the documentation is now a
result of 'professionals'.


On Sun, Nov 18, 2018 at 5:21 AM Kurt H Maier <khm@sciops.net> wrote:

> On Sat, Nov 17, 2018 at 11:14:53AM -0700, arnold@skeeve.com wrote:
> >
> > The man page authors / tech writers at Sun were paid to write man
> > pages, and learned / were taught how to do it well. The Linux stuff is
> > done by volunteers.  You're comparing apples and oranges.
>
> How do we kill this meme?  Linux is open to contribution by volunteers
> but the overwhelming majority of the work done on the OS for *at least*
> the last ten years has been by professionals who are paid to work on
> Linux.  Pretending otherwise is disingenuous, and anyway I'm not sure
> why the OS that powers pacemakers and self-driving car research gets to
> be held to a lower standard.
>
> khm
>

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

Re: [TUHS] man-page style

[Theodore Y. Ts'o]

On Sat, Nov 17, 2018 at 10:21:08AM -0800, Kurt H Maier wrote:
> On Sat, Nov 17, 2018 at 11:14:53AM -0700, arnold@skeeve.com wrote:
> >
> > The man page authors / tech writers at Sun were paid to write man
> > pages, and learned / were taught how to do it well. The Linux stuff is
> > done by volunteers.  You're comparing apples and oranges.
>         
> How do we kill this meme?  Linux is open to contribution by volunteers
> but the overwhelming majority of the work done on the OS for *at least*
> the last ten years has been by professionals who are paid to work on
> Linux.

This is true.  Alas, very few of these professionals are technical
writers.  The business model and incentives are different, furthermore
resources such as StackExchange don't exist tend to disincentivize
companies from investing in tech writers --- with notable exceptions
being documentation specific to Red Hat, SuSE, etc.

With commercial products that have competition, prospective customers
can say, "SunOS documentation isn't sufficiently thorough!  I'm
switching to VMS so I can have that wall of three ring binders" :-)

Without that competition, companies are less incentivized to divert
resources to luxuries like documentation --- and the commoditization
of Unix-like systems has reduced the available resources that
companies have available when they are trying to make budgeting
decisions.

(Although I will say, speaking of budgeting decisions, the amount of
human resources I've sent consumed in IBM Fall Plan and Spring Re-Plan
would, if converted from managers and senior engineers to tech
writers, be enough for a truly awesome amount of documentation.  My
condolences to my friends at Red Hat who will soon be getting to
enjoy the wonders of IBM corporate processes.  :-)

	      	     	       	       - Ted

Re: [TUHS] man-page style

[Chet Ramey]

On 11/17/18 1:21 PM, Kurt H Maier wrote:
> On Sat, Nov 17, 2018 at 11:14:53AM -0700, arnold@skeeve.com wrote:
>>
>> The man page authors / tech writers at Sun were paid to write man
>> pages, and learned / were taught how to do it well. The Linux stuff is
>> done by volunteers.  You're comparing apples and oranges.
>         
> How do we kill this meme?  

As soon as volunteers like Arnold, who maintains a widely-used piece
of the Linux infrastructure, get paid.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

Re: [TUHS] man-page style

[Anthony Martin]

Doug McIlroy <doug@cs.dartmouth.edu> once said:
> For nagging reasons of verbal continuity, the options displays
> were prefaced by *needless words* like, "The following options
> are recognized". A simple OPTIONS heading would be better.

There's a good one in ls(1) from v8: "There are an unbelievable
number of options".

  Anthony