Re: [TUHS] earliest Unix roff

[Steffen Nurpmeso <steffen@sdaoden.eu>]

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)