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=-1.0 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, 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 f2c902f4 for ; Fri, 20 Sep 2019 13:42:17 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 47A569BA0E; Fri, 20 Sep 2019 23:42:16 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 15DA1947C7; Fri, 20 Sep 2019 23:41:45 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 0AEE0947C7; Fri, 20 Sep 2019 23:41:44 +1000 (AEST) Received: from sdaoden.eu (sdaoden.eu [217.144.132.164]) by minnie.tuhs.org (Postfix) with ESMTPS id B61CE94792 for ; Fri, 20 Sep 2019 23:41:42 +1000 (AEST) Received: by sdaoden.eu (Postfix, from userid 1000) id D634716054; Fri, 20 Sep 2019 15:41:40 +0200 (CEST) Date: Fri, 20 Sep 2019 15:41:37 +0200 From: Steffen Nurpmeso To: "John P. Linderman" Message-ID: <20190920134137.DXBTo%steffen@sdaoden.eu> In-Reply-To: References: <1568916649.17313.for-standards-violators@oclsc.org> <20190919194415.Tp6NO%steffen@sdaoden.eu> Mail-Followup-To: "John P. Linderman" , Norman Wilson , The Eunuchs Hysterical Society User-Agent: s-nail v14.9.15-68-ge75b4fd9 OpenPGP: id=EE19E1C1F2F7054F8D3954D8308964B51883A0DD; url=https://ftp.sdaoden.eu/steffen.asc; preference=signencrypt BlahBlahBlah: Any stupid boy can crush a beetle. But all the professors in the world can make no bugs. MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=3S4pvIiEJqipSkgTUXOayizTJL-8oSznGda5=-=" Subject: Re: [TUHS] earliest Unix roff X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: The Unix Heritage Society mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: The Eunuchs Hysterical Society Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" This is a multi-part message in MIME format. --=-=3S4pvIiEJqipSkgTUXOayizTJL-8oSznGda5=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Content-Disposition: inline Content-ID: <20190920134137.3sqTU%steffen@sdaoden.eu> John P. Linderman wrote in : |In the early 70's, Marc Rochkind recommended re-reading the entire \ |UNIX manual yearly. Back then, it was doable. Now it is probably growing \ |faster than I can read. It is however astonishing by how much even the POSIX standard changes, as a lowest common denominator. The IETF produces an overwhelming amount of drafts and RFCs, which need to or should be adhered to, affecting functionality and documentation. So much more time would be needed, for so many things. |There is a place for a concise=C2=A0description=C2=A0of each command, and= a separate \ |place for tutorials and conference papers. Unfortunately not except in FreeBSD and NetBSD, which carry some in /usr/share/doc, like the BSD mail manual. You need to find it here, and i wonder how many of those who have grown up in the Linux world would find them at all. (Or even do a search.) They are not really updated in addition. Though FreeBSD added a clang entry, the time when developers invented ideas and implementations, and documented those under /usr/share/doc are over even there. This is really sad. Infrequently and getting rarer i reread those, for example "Rethinking /dev and devices in the UNIX kernel" about the introduction of devfs, which i still find great. It is great to hear you who is responsible that the "load of options reached 17 in v9", whereas i maintain a fork of the program which causes "old UNIX hands [to] groan at the monstrous headers that come from latter-day mailers and at the fatness of their manuals" (citing A Research UNIX Reader). To offer a solution i could add another layer in between -h output and full reference manual, and create a heavily minimized version of the manual, renaming that one to -reference.1 maybe, and prominently mention the reference. Also, easy it is to concisely document that -n chooses a numeric sort, and -r reverses the result order, but=20 -b addr, --bcc=3D.. Send a blind carbon copy to recipient addr. can result in dead-end or otherwise misunderstood situations unless you really know that particular manual is stripped down, and the reference manual makes this -b addr, --bcc=3D.. Send a blind carbon copy to recipient addr, if the set[268]ting of expandaddr[408], one of the INTERNAL VARIABLES[29], allows; the =E2=80=98shquote=E2=80=99 expandaddr[408] flag is supported. The= option may be used multiple times. Also see the section On sending mail, and non-interactive mode[7]. (Here, expandaddr has not been invented by me.) But if you have the reference a bit present in your head, then #?0|kent:nail$ .obj/s-nail -h|grep -- -b [:-a attachment:] [:-b bcc-addr:] [:-c cc-addr:] . -b, -c, -r, -T, to-addr: ex@am.ple or '(Lovely) Ex ' should also be sufficient. Blasting the concise complexity of a mathematical formula, -a file[=3Dinput-charset[#output-charset]], --attach=3D.. Attach file to the message (for compose mode opportunities refer to ~@[317] and ~^[319]). needs to backed as -a file[=3Dinput-charset[#output-charset]], --attach=3D.. Attach file to the message (for compose mode opportunities refer to ~@[317] and ~^[319]). Filename transformations[26] (also see file[193]) will be performed, except that shell variables are not expanded. Shall file not be accessible but contain a =E2=80=98= =3D=E2=80=99 charac=E2=80=90 ter, then anything before the last =E2=80=98=3D=E2=80=99 will be = used as the file=E2=80=90 name, anything thereafter as a character set specification. If an input character set is specified, but no output character set, then the given input character set is fixed as-is, and no conversion will be applied; giving the empty string or the special string hyphen-minus =E2=80=98-=E2=80=99 will be treated as if tty= charset[590] has been specified (the default). If an output character set has also been given then the conversion will be performed exactly as specified and on-the-fly, not consid= =E2=80=90 ering the file type and content. As an exception the empty string or hyphen-minus =E2=80=98-=E2=80=99, select the default conversio= n algorithm (see Character sets[14]): no conversion is performed on-the-fly, file and its contents will be MIME-classified (HTML mail and MIME attachments[9], The mime.types files[35]); Only this mode is sup= =E2=80=90 ported without support for character set conversions (features[411] does not mention =E2=80=98+iconv=E2=80=99). for people to get at least enough of the picture to use the option. (Note the actual algorithm is documented somewhere else.) #?0|kent:nail$ .obj/s-nail -h|grep -- '-a ' [:-a attachment:] [:-b bcc-addr:] [:-c cc-addr:] . -a attachment[=3Dinput-charset[#output-charset]] But normally, all you say is "-a file" and the thing is fine by default without just doing anything at all. That is how it should be. Dear John P. Linderman, be warned that the above output of -b is new, it was "-[bcrT]:" before, for which to understand regular expressions or file patterns are implied. I have given you credit for the change. --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) --=-=3S4pvIiEJqipSkgTUXOayizTJL-8oSznGda5=-= Content-Type: message/rfc822 Content-Disposition: inline Content-ID: <20190920134137.wGJIN%steffen@sdaoden.eu> Content-Description: Original message content Return-Path: X-Original-To: steffen@sdaoden.eu Delivered-To: steffen@sdaoden.eu Received: from mail-vk1-f176.google.com (mail-vk1-f176.google.com [209.85.221.176]) by sdaoden.eu (Postfix) with ESMTPS id 06B131604A for ; Thu, 19 Sep 2019 22:39:04 +0200 (CEST) Received: by mail-vk1-f176.google.com with SMTP id d126so1135913vkb.1 for ; Thu, 19 Sep 2019 13:39:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=ch1gdtyI1bgL13VufFDt0n+qMZMD0T7K2oFruSAwWto=; b=gUgxZGjfhNb0U7OOZ7UmUkfWwF6kZT3eRcpDFi/jI9x+SJ8CezhIE8I3GOxmxgkYvC qWmSGjni5wLYdLKDvoOyl4wdoWCelGB6ucUSIfgGaYQj0Zstxo/SI6dyUTl1IN42DLuY WUHlgl6VFLMW40rwzDbZSYRdb2jMuRAaxiRNI1xwnDfThnzlfUv425olBgWEQeRVJwPX egl7kq9rmS+nUF3p+/HISF/oV+x5z6gr9PjFqYTPSYPBv6xndSrbds7hdq3R6X/RPSmx 9gPAFWAUZkwR/t/BIyJelqvxd/WmQZhcAW9hFMOfFNIgcYAKpkCU4ktjf448IUtXug+j qGtA== 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=ch1gdtyI1bgL13VufFDt0n+qMZMD0T7K2oFruSAwWto=; b=PTN9MkyZG2LlAg3WKlNBubT/lu3tAF5YMO/fKGM0G2X3e3EPr5AXHdUku0/vkcmxyP 99Cq0CYu39qEnluV90stXM62T6XFQ2yPMpyvXZMieUeyedu0F6YDSsmQL861BLsTDRBo Ys3A6ndsj7pGX8g+VxWN2mGgLDYZewQhwWXln0uxtOnqCDEUMdQb/i1IQ6nBVZ3OMuwb x1H/lNZThFxn2kk0o+jWfzrf7moqPGyZpZJSB9hc4tlfzl7VizE2cl2L1dm609IXaNBN fKkmRfgvXstWEPEKbSk6ZGkV/HEP4pn6JyYZ4UThkUhrJlyRBOLM8cGNmPl9jV4LoOcp 3iMQ== X-Gm-Message-State: APjAAAX8J239XgFCBxeko48tBmqDYeBudsIKDS8EuNdjkWmL3HNwFIdM w0o9hNqYBNjm7hZIP19r4Qw8UvcNZPUpUO8l1Coxvg== X-Google-Smtp-Source: APXvYqw8cKOiwrUZhFhbe+iloNVFxLXQInWEgGr/DSdmPegsbc0IWX8Lo+tbbsngKCiOFcm2FOWm9ptDaNVVUnkU70s= X-Received: by 2002:a1f:d8c4:: with SMTP id p187mr5816429vkg.47.1568925543216; Thu, 19 Sep 2019 13:39:03 -0700 (PDT) MIME-Version: 1.0 References: <1568916649.17313.for-standards-violators@oclsc.org> <20190919194415.Tp6NO%steffen@sdaoden.eu> In-Reply-To: <20190919194415.Tp6NO%steffen@sdaoden.eu> From: "John P. Linderman" Date: Thu, 19 Sep 2019 16:38:51 -0400 Message-ID: Subject: Re: [TUHS] earliest Unix roff To: Steffen Nurpmeso Cc: Norman Wilson , The Eunuchs Hysterical Society Content-Type: multipart/alternative; boundary="000000000000aeb82e0592edf1b9" Status: RO --000000000000aeb82e0592edf1b9 Content-Type: text/plain; charset="UTF-8" In the early 70's, Marc Rochkind recommended re-reading the entire UNIX manual yearly. Back then, it was doable. Now it is probably growing faster than I can read. There is a place for a *concise* description of each command, and a separate place for tutorials and conference papers. On Thu, Sep 19, 2019 at 3:44 PM Steffen Nurpmeso wrote: > Norman Wilson wrote in <1568916649.17313.for-standards-violators@oclsc.org > >: > |Larry McVoy: > | > | If you have something like perl that needs a zillion sub pages, info > | makes sense. For just a man page, info is horrible. > | > |===== > | > |This pokes me in one of my longest-standing complaints: > | > |Manual entries, as printed by man and once upon a time in > |the Programmers' Manual Volume 1, should be concise references. > |They are not a place for tutorials or long-winded descriptions > |or even long lists of hundreds of options (let alone descriptions > |of why the developer thinks this is the neatest thing since > |sliced bread and what bread he had in his sandwiches that day). > | > |For many programs, one or two pages of concise reference is > |all the documentation that's needed; no one needs a ten-page > |tutorial on how to use cat or rm or ls, for example. But some > |programs really do deserve a longer treatment, either a tutorial > |or an extended reference with more detail or both. Those belong > |in separate documents, and are why the Programmers' Manual had > |a second volume. > | > |Nowadays people think nothing of writing 68-page-long manual > |entries (real example from something I'm working with right now) > |that are long, chatty lists of options or configuration-file > |directives with tutorial information interspersed. The result > |makes the developer feel good--look at all the documentation > |I've written!!--but it's useless for someone trying to figure > |out how to write a configuration file for the first time, and > |not so great even for someone trying to edit an existing one. > | > |Even the Research system didn't always get this right; some > > I totally disagree with you. Whereas i even admire McIlroy's > "concise", and really love reading Plan9 manual pages, and that > not only because one can imagine _who_ put their fingers on those, > i think manual pages should enable people to work with a program. > And not only intellectual elite, the absolute top of the pops > gathered together in this cave and grooving with a pict, but > "everybody" to the extend possible. > > If i would have a lot of money in spare i could hire teams of > three people each which rotate through the develop / test > / documentation cycle, and around each others work. But that is > not how it goes here, you add a feature and write down the docs, > you extend one and patch in doc where you think it belongs, yet > get infos from someone and patch in doc to clarify something. You > do all that short on time, and finally you have a rag rug. > > So what you would need then is time to step back, let time pass, > come back with fresh eyes, reread the entire documentation once, > reflect, and work it all over. > > Add the complications of not being a native speaker. > For some projects, add many translations done by volunteers, which > you leave behind if you adhere to this work cycle. (But do not if > you just patch up.) > > You could of course split the manual into several subsections, but > which one to split, which not. Duplicate several, for example > command line options, which can initiate complicate tasks, which > need a lengthy text to become understandable? > > Who is going to do all that work? Who is the one who will spend > the time and strength necessary to keep all the individual parts > in sync? For example, this week (at least the latter commit) on > FreeBSD the ZFS filesystem, thus a crucial part of the > infrastructure of FreeBSD (no Hammer or BTRFS support), the > i guess second largest free software environment, with quite some > people getting paid for working on the code base, was extended (i > do not use ZFS), but even the help string of the managing tool was > not updated until a follow up commit several days later fixed > that! > > So for me this is not feasible. I have the manual, and i have the > help string output for -h / --help, and a longer (long option) one > with --long-help. If you want a quick shot, use -h. If you need > documentation, use the manual. > > #?0|kent:mk$ man -l ../nail.1|wc -l > troff: :14382: name expected (got '\c'): treated as > missing > 8172 > > Without TOC and anchors. > bug in groff mdoc macros in 1.22.3, by the way (.Lk i guessed). > > #?0|kent:mk$ mdoc ../nail.1|wc -l > 8307 > > With TOC and hundreds of internal and external anchors. > > #?0|kent:mk$ /tmp/y/s-nail -h|wc -l > 24 > #?0|kent:mk$ /tmp/y/s-nail --long-help|wc -l > 57 > > |manual entries ran on and on and on when what was really > |needed was a concise list of something and a longer accompanying > |document. (The Tenth Edition manual was much better about > |that, mostly because of all the work Doug put in. I doubt > |there has ever been a better editor for technical text than > |Doug.) But it's far worse now in most systems, because > |there's rarely any editor at all; the manuals are just an > |accreted clump. > | > |And that's a shame, though I have no suggestions on how > |to fix it. > > I do not know either. The car industry has the many pictures but > no content (for people who spend money), a repair manual for > underpaid mechanics, and detailed spare part foils for those > people working in the dusty spare parts depot. That at least > thirty years ago when i snuffled into that industry. > > |Norman Wilson > |Toronto ON > --End of <1568916649.17313.for-standards-violators@oclsc.org> > > --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) > --000000000000aeb82e0592edf1b9 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
In = the early 70's, Marc Rochkind recommended re-reading the entire UNIX ma= nual yearly. Back then, it was doable. Now it is probably growing faster th= an I can read.
=
There is a= place for a concise=C2=A0description=C2=A0of each command, and a se= parate place for tutorials and conference papers.

On Thu, Sep 19, 2019= at 3:44 PM Steffen Nurpmeso <stef= fen@sdaoden.eu> wrote:
Norman Wilson wrote in <1568916649.17313.for-= standards-violators@oclsc.org>:
=C2=A0|Larry McVoy:
=C2=A0|
=C2=A0|=C2=A0 If you have something like perl that needs a zillion sub page= s, info
=C2=A0|=C2=A0 makes sense.=C2=A0 For just a man page, info is horrible.
=C2=A0|
=C2=A0|=3D=3D=3D=3D=3D
=C2=A0|
=C2=A0|This pokes me in one of my longest-standing complaints:
=C2=A0|
=C2=A0|Manual entries, as printed by man and once upon a time in
=C2=A0|the Programmers' Manual Volume 1, should be concise references.<= br> =C2=A0|They are not a place for tutorials or long-winded descriptions
=C2=A0|or even long lists of hundreds of options (let alone descriptions =C2=A0|of why the developer thinks this is the neatest thing since
=C2=A0|sliced bread and what bread he had in his sandwiches that day).
=C2=A0|
=C2=A0|For many programs, one or two pages of concise reference is
=C2=A0|all the documentation that's needed; no one needs a ten-page
=C2=A0|tutorial on how to use cat or rm or ls, for example.=C2=A0 But some<= br> =C2=A0|programs really do deserve a longer treatment, either a tutorial
=C2=A0|or an extended reference with more detail or both.=C2=A0 Those belon= g
=C2=A0|in separate documents, and are why the Programmers' Manual had =C2=A0|a second volume.
=C2=A0|
=C2=A0|Nowadays people think nothing of writing 68-page-long manual
=C2=A0|entries (real example from something I'm working with right now)=
=C2=A0|that are long, chatty lists of options or configuration-file
=C2=A0|directives with tutorial information interspersed.=C2=A0 The result<= br> =C2=A0|makes the developer feel good--look at all the documentation
=C2=A0|I've written!!--but it's useless for someone trying to figur= e
=C2=A0|out how to write a configuration file for the first time, and
=C2=A0|not so great even for someone trying to edit an existing one.
=C2=A0|
=C2=A0|Even the Research system didn't always get this right; some

I totally disagree with you.=C2=A0 Whereas i even admire McIlroy's
"concise", and really love reading Plan9 manual pages, and that not only because one can imagine _who_ put their fingers on those,
i think manual pages should enable people to work with a program.
And not only intellectual elite, the absolute top of the pops
gathered together in this cave and grooving with a pict, but
"everybody" to the extend possible.

If i would have a lot of money in spare i could hire teams of
three people each which rotate through the develop / test
/ documentation cycle, and around each others work.=C2=A0 But that is
not how it goes here, you add a feature and write down the docs,
you extend one and patch in doc where you think it belongs, yet
get infos from someone and patch in doc to clarify something.=C2=A0 You
do all that short on time, and finally you have a rag rug.

So what you would need then is time to step back, let time pass,
come back with fresh eyes, reread the entire documentation once,
reflect, and work it all over.

Add the complications of not being a native speaker.
For some projects, add many translations done by volunteers, which
you leave behind if you adhere to this work cycle.=C2=A0 (But do not if
you just patch up.)

You could of course split the manual into several subsections, but
which one to split, which not.=C2=A0 Duplicate several, for example
command line options, which can initiate complicate tasks, which
need a lengthy text to become understandable?

Who is going to do all that work?=C2=A0 Who is the one who will spend
the time and strength necessary to keep all the individual parts
in sync?=C2=A0 For example, this week (at least the latter commit) on
FreeBSD the ZFS filesystem, thus a crucial part of the
infrastructure of FreeBSD (no Hammer or BTRFS support), the
i guess second largest free software environment, with quite some
people getting paid for working on the code base, was extended (i
do not use ZFS), but even the help string of the managing tool was
not updated until a follow up commit several days later fixed
that!

So for me this is not feasible.=C2=A0 I have the manual, and i have the
help string output for -h / --help, and a longer (long option) one
with --long-help.=C2=A0 If you want a quick shot, use -h.=C2=A0 If you need=
documentation, use the manual.

=C2=A0 #?0|kent:mk$ man -l ../nail.1|wc -l
=C2=A0 troff: <standard input>:14382: name expected (got '\c'= ): treated as missing
=C2=A0 8172

Without TOC and anchors.
bug in groff mdoc macros in 1.22.3, by the way (.Lk i guessed).

=C2=A0 #?0|kent:mk$ mdoc ../nail.1|wc -l
=C2=A0 8307

With TOC and hundreds of internal and external anchors.

=C2=A0 #?0|kent:mk$ /tmp/y/s-nail -h|wc -l
=C2=A0 24
=C2=A0 #?0|kent:mk$ /tmp/y/s-nail --long-help|wc -l
=C2=A0 57

=C2=A0|manual entries ran on and on and on when what was really
=C2=A0|needed was a concise list of something and a longer accompanying
=C2=A0|document.=C2=A0 (The Tenth Edition manual was much better about
=C2=A0|that, mostly because of all the work Doug put in.=C2=A0 I doubt
=C2=A0|there has ever been a better editor for technical text than
=C2=A0|Doug.)=C2=A0 But it's far worse now in most systems, because
=C2=A0|there's rarely any editor at all; the manuals are just an
=C2=A0|accreted clump.
=C2=A0|
=C2=A0|And that's a shame, though I have no suggestions on how
=C2=A0|to fix it.

I do not know either.=C2=A0 The car industry has the many pictures but
no content (for people who spend money), a repair manual for
underpaid mechanics, and detailed spare part foils for those
people working in the dusty spare parts depot.=C2=A0 That at least
thirty years ago when i snuffled into that industry.

=C2=A0|Norman Wilson
=C2=A0|Toronto ON
=C2=A0--End of <1568916649.17313.for-standards-violators@oc= lsc.org>

--steffen
|
|Der Kragenbaer,=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 The= moon bear,
|der holt sich munter=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0he cheerfully= and one by one
|einen nach dem anderen runter=C2=A0 wa.ks himself off
|(By Robert Gernhardt)
--000000000000aeb82e0592edf1b9-- --=-=3S4pvIiEJqipSkgTUXOayizTJL-8oSznGda5=-=--