From: "John P. Linderman" <jpl.jpl@gmail.com>
To: Steffen Nurpmeso <steffen@sdaoden.eu>
Cc: The Eunuchs Hysterical Society <tuhs@tuhs.org>
Subject: Re: [TUHS] earliest Unix roff
Date: Thu, 19 Sep 2019 16:38:51 -0400 [thread overview]
Message-ID: <CAC0cEp-CVPb-OhcDHKfbj5nMoiYjkAOEZnEOf4Sv5ZrzTnDKTg@mail.gmail.com> (raw)
In-Reply-To: <20190919194415.Tp6NO%steffen@sdaoden.eu>
[-- Attachment #1: Type: text/plain, Size: 6093 bytes --]
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 <steffen@sdaoden.eu> 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: <standard input>: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)
>
[-- Attachment #2: Type: text/html, Size: 7304 bytes --]
next prev parent reply other threads:[~2019-09-19 20:39 UTC|newest]
Thread overview: 99+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-09-19 18:10 Norman Wilson
2019-09-19 18:37 ` Clem Cole
2019-09-19 18:44 ` Jon Steinhart
2019-09-19 19:44 ` Steffen Nurpmeso
2019-09-19 20:38 ` John P. Linderman [this message]
2019-09-20 13:41 ` Steffen Nurpmeso
2019-09-20 15:03 ` Steffen Nurpmeso
2019-09-19 20:53 ` Bakul Shah
-- strict thread matches above, loose matches on Subject: below --
2019-09-19 18:50 [TUHS] [OT] " Norman Wilson
2019-09-19 19:00 ` Nemo Nusquam
2019-09-19 20:18 ` Larry McVoy
2019-09-19 20:42 ` [TUHS] " Andy Kosela
2019-09-19 18:42 Norman Wilson
2019-09-19 22:42 ` Rob Pike
2019-09-19 22:55 ` Bakul Shah
2019-09-15 22:07 Doug McIlroy
2019-09-17 0:20 ` Steve Johnson
2019-09-17 1:11 ` Arthur Krewat
2019-09-17 1:17 ` Larry McVoy
2019-09-17 1:26 ` Clem cole
2019-09-17 1:33 ` Larry McVoy
2019-09-17 22:39 ` Dave Horsfall
2019-09-17 1:36 ` Richard Salz
2019-09-17 1:57 ` Bakul Shah
2019-09-17 1:19 ` Bakul Shah
2019-09-15 2:45 Doug McIlroy
2019-09-13 3:20 [TUHS] My EuroBSDcon talk (preview for commentary) Warner Losh
2019-09-13 19:47 ` Clem Cole
2019-09-13 20:02 ` Clem Cole
2019-09-13 20:06 ` Clem Cole
2019-09-13 20:24 ` Jon Steinhart
2019-09-13 20:43 ` Clem Cole
2019-09-13 20:53 ` Diomidis Spinellis
2019-09-13 21:45 ` Clem Cole
2019-09-13 22:13 ` [TUHS] earliest Unix roff Warren Toomey
2019-09-13 22:55 ` Clem Cole
2019-09-14 2:02 ` Larry McVoy
2019-09-14 2:44 ` Warren Toomey
2019-09-15 2:56 ` U'll Be King of the Stars
2019-09-15 6:54 ` arnold
2019-09-15 7:01 ` Dave Horsfall
2019-09-15 16:17 ` Jon Steinhart
2019-09-15 17:23 ` Ronald Natalie
2019-09-15 19:48 ` Clem Cole
2019-09-15 21:16 ` Dave Horsfall
2019-09-15 7:32 ` U'll Be King of the Stars
2019-09-15 7:46 ` arnold
2019-09-15 19:37 ` Clem Cole
2019-09-16 5:52 ` arnold
2019-09-16 12:10 ` Clem Cole
2019-09-16 12:26 ` Lars Brinkhoff
2019-09-16 13:42 ` Clem Cole
2019-09-16 14:54 ` Larry McVoy
2019-09-16 16:09 ` Paul Winalski
2019-09-16 22:05 ` Dave Horsfall
2019-09-16 22:33 ` reed
2019-09-17 0:11 ` Dave Horsfall
2019-09-17 0:02 ` Nemo Nusquam
2019-09-17 0:21 ` Arthur Krewat
2019-09-17 11:12 ` Thomas Paulsen
2019-09-17 0:46 ` Clem Cole
2019-09-16 13:13 ` Chet Ramey
2019-09-16 14:51 ` Larry McVoy
2019-09-16 14:57 ` Clem Cole
2019-09-16 15:14 ` Richard Salz
2019-09-16 15:48 ` Ronald Natalie
2019-09-16 16:10 ` Larry McVoy
2019-09-16 16:16 ` Jon Steinhart
2019-09-16 16:26 ` Larry McVoy
2019-09-16 16:31 ` Richard Salz
2019-09-16 16:45 ` Larry McVoy
2019-09-16 17:19 ` KatolaZ
2019-09-16 17:24 ` Larry McVoy
2019-09-16 17:32 ` Jon Steinhart
2019-09-16 17:35 ` Clem Cole
2019-09-16 17:37 ` Jon Steinhart
2019-09-16 18:04 ` Chet Ramey
2019-09-16 18:19 ` KatolaZ
2019-09-16 23:24 ` Dave Horsfall
2019-09-16 17:24 ` Clem Cole
2019-09-16 17:00 ` Clem Cole
2019-09-17 11:20 ` Thomas Paulsen
2019-09-16 19:13 ` Steffen Nurpmeso
2019-09-16 19:31 ` Bakul Shah
2019-09-16 22:35 ` Dave Horsfall
2019-09-17 7:53 ` arnold
2019-09-17 14:21 ` Clem Cole
2019-09-17 15:03 ` arnold
2019-09-17 15:58 ` Christopher Browne
2019-09-17 18:15 ` arnold
2019-09-17 18:32 ` Warner Losh
2019-09-18 0:42 ` Adam Thornton
2019-09-16 21:42 ` Dave Horsfall
2019-09-16 21:48 ` Larry McVoy
2019-09-16 21:54 ` Jon Steinhart
2019-09-16 21:59 ` Larry McVoy
2019-09-17 5:07 ` Lars Brinkhoff
2019-09-16 22:10 ` Bakul Shah
2019-09-17 0:16 ` Greg 'groggy' Lehey
2019-09-17 0:31 ` Jon Steinhart
2019-09-17 12:20 ` David
2019-10-05 19:44 ` Michael Parson
2019-09-15 19:35 ` Clem Cole
2019-09-15 20:49 ` U'll Be King of the Stars
2019-09-16 6:20 ` arnold
2019-09-16 12:13 ` Clem Cole
2019-09-16 12:34 ` arnold
2019-09-16 14:52 ` Larry McVoy
2019-09-15 19:27 ` Clem Cole
2019-09-15 19:31 ` Jon Steinhart
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAC0cEp-CVPb-OhcDHKfbj5nMoiYjkAOEZnEOf4Sv5ZrzTnDKTg@mail.gmail.com \
--to=jpl.jpl@gmail.com \
--cc=steffen@sdaoden.eu \
--cc=tuhs@tuhs.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).