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