From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,HTML_FONT_LOW_CONTRAST,HTML_MESSAGE, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from minnie.tuhs.org (minnie.tuhs.org [45.79.103.53]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 9a5ca13a for ; Mon, 19 Nov 2018 18:41:58 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 1CAE3945F6; Tue, 20 Nov 2018 04:41:57 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 6571A94106; Tue, 20 Nov 2018 04:41:26 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 07752940FE; Tue, 20 Nov 2018 04:41:19 +1000 (AEST) Received: from mail-wm1-f53.google.com (mail-wm1-f53.google.com [209.85.128.53]) by minnie.tuhs.org (Postfix) with ESMTPS id 36DE7940FA for ; Tue, 20 Nov 2018 04:41:13 +1000 (AEST) Received: by mail-wm1-f53.google.com with SMTP id s11so6318715wmh.1 for ; Mon, 19 Nov 2018 10:41:13 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ccc.com; s=google; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=48ITP1gwuQ5zN3ibT9DPIpT4Ya2scGtvClhmB83QYDo=; b=bdLcDMcvJ6MKRC45NCjXJsZZucihiwUpAEbiV4NTczmzHD2lX9UMzezeAH+qcj20ii 2CGfBtWf7HH60IiE8xPldyw29U0wheT3lPRhwEhTK3PTmxWdfK/9tuNoyzLBrXR/sUbp +Gyj0XpnocxQOQBVBV4R3Mx3vrTqtOhuEuWW8= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=48ITP1gwuQ5zN3ibT9DPIpT4Ya2scGtvClhmB83QYDo=; b=FqU4yq2ucyYEW1sl7H6vRSgsmIh/z4JgmfeeUQOPbn/sMNkYBRyxc03TTtiwtmtmeW 4KxmcsEAE7pYh18ZY5S1Rz+ZwQ7JtHl7fuqJqgRAy+qHM/tLIUne3CEsnMNgijXl7TpL 6+ZTIPBA5BpJKRLzJVcM7rbw5g++T6e0J9oD2ti/plNcJs+FbCKaf10G1ChqzKxv7Ge5 dVfa4Pyw+Q/zMA/4KUwp4v9P4g1Rr9yW5hKqkcM2ShwQvKOfChLbshsKsPNohcTlCpIk i87oJ5qEd24rDg4P2AsKVXcD/93XxGI5K13ktqPdqpAJqZqQ/R/i7lKePz2+n5WNILQU RUGA== X-Gm-Message-State: AA+aEWa1JXaT7LJKHOssqHQQyXA2kkClZPUgzwrkMIY7JNfyBjHlPmAT COBXUjbfAQ+3XRKZunrzAIRYB2RIpRjqybnu+ZzfDA== X-Google-Smtp-Source: AFSGD/UKYgPlmxZRpl8VbPHvL7BNv3lbYW9O1AlQuks6zaVKeTuYwfFGo/Lqk/+YvIjSSLCmhTyzmBBlEIk45Z2RkMo= X-Received: by 2002:a1c:248b:: with SMTP id k133-v6mr7796389wmk.148.1542652871618; Mon, 19 Nov 2018 10:41:11 -0800 (PST) MIME-Version: 1.0 References: <7a632484-cdc7-7c59-7077-7a2c752045da@spamtrap.tnetconsulting.net> <4c36b2b2-76df-435f-27bc-e1feb0647f36@case.edu> <201811162113.wAGLDGiQ031455@darkstar.fourwinds.com> <201811190311.wAJ3BDHR028154@darkstar.fourwinds.com> <20181119173952.GA19377@thunk.org> In-Reply-To: <20181119173952.GA19377@thunk.org> From: Clem Cole Date: Mon, 19 Nov 2018 13:40:43 -0500 Message-ID: To: tytso@mit.edu Content-Type: multipart/alternative; boundary="0000000000006cbfd9057b08dc9f" Subject: Re: [TUHS] man-page style X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: The Unix Heritage Society mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: tuhs@tuhs.org Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" --0000000000006cbfd9057b08dc9f Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 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 !=3D 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 sourc= e > 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 =E1=90=A7 =E1=90=A7 --0000000000006cbfd9057b08dc9f Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
As is often in these disagreements, I suspect agree mor= e than disagree.=C2=A0 But some of the absolute edges/where you start or st= op is where we pick different=C2=A0things.

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.=C2=A0 All<= br> executables are supposed to have a man page.=C2=A0
Rig= ht, thank you and I applaud them for that...=C2=A0 =C2=A0As you and others = have pointed out, Debian !=3D Gnu

=C2=A0
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.=C2=A0
I thin= k that's somewhat backwards in he spirit of 'UNIX'...=C2=A0 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.=C2=A0 =C2= =A0 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 qu= ick reference.


=C2=A0

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 ma= ke in ~77/78 timeframe when make came to us (I think via UNIX/TS), modulo s= taring at makefiles and copying them.
Truth is I did not read Feldm= an's paper to start because it was not online and we don't have the= storage for it.=C2=A0 I mostly learned make by duplicating makefiles I fou= nd and if I did not understand something - reading the code.=C2=A0 =C2=A0I = did read the paper at some point and mostly understood it.=C2=A0 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&= #39;Rielly) that I really 'got it.'=C2=A0 =C2=A0Talbot would pester= me, Steve Glaser, Steinhart, Zuhl and the other UNIX jockeys at Tektronix = asking how things worked.=C2=A0 Then he wrote it down and wrote a wonderful= book.=C2=A0 It's simple, to the point -- make in a nutshell -- what yo= u need to know to use it.=C2=A0 To this day, when someone asks me about mak= e I loan then a copy of the Steve's book as the starting point.=C2=A0 = =C2=A0Once 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...=C2=A0 = =C2=A0the 'primary manual' as you call it is the document in /usr/d= oc/make in this case.=C2=A0 But [as others have pointed out, writing that &= gt;well<< can be hard]. FWIW: Feldman's description of make in /u= sr/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.=C2=A0

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

info should ju= st be a different interface to man.=C2=A0 No more, not less -- the referenc= e - not the manual.


=C2=A0

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

C= lem
3D""=E1=90=A7
3D""=E1=90=A7 --0000000000006cbfd9057b08dc9f--