[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Douglas McIlroy]

[-- Attachment #1: Type: text/plain, Size: 513 bytes --]

I just revisited this ironic echo of Mies van der Rohe's aphorism, "Less is
more".
       % less --help | wc
      298
Last time I looked, the line count was about 220. Bloat is self-catalyzing.

What prompted me to look was another disheartening discovery. The "small
special tool" Gnu diff has a 95-page manual!  And it doesn't cover the
option I was looking up (-h). To be fair, the manual includes related
programs like diff3(1), sdiff(1) and patch(1), but the original manual for
each fit on one page.

Doug

[-- Attachment #2: Type: text/html, Size: 697 bytes --]

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Brantley Coile]

I'm so grateful that we are able to work using Plan 9. 

aztec% wc -l /sys/src/cmd/p.c
     90 /sys/src/cmd/p.c
aztec% 

So the size of Plan 9's paginator's source code is 208 lines smaller than the help for that paginator. And it has no options.

Just say'n.

bwc

> On May 18, 2024, at 2:07 PM, Douglas McIlroy <douglas.mcilroy@dartmouth.edu> wrote:
> 
> I just revisited this ironic echo of Mies van der Rohe's aphorism, "Less is more".
>        % less --help | wc
>       298
> Last time I looked, the line count was about 220. Bloat is self-catalyzing. 
> 
> What prompted me to look was another disheartening discovery. The "small special tool" Gnu diff has a 95-page manual!  And it doesn't cover the option I was looking up (-h). To be fair, the manual includes related programs like diff3(1), sdiff(1) and patch(1), but the original manual for each fit on one page.
> 
> Doug

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Larry McVoy]

On Sat, May 18, 2024 at 02:07:38PM -0400, Douglas McIlroy wrote:
> I just revisited this ironic echo of Mies van der Rohe's aphorism, "Less is
> more".
>        % less --help | wc
>       298
> Last time I looked, the line count was about 220. Bloat is self-catalyzing.
> 
> What prompted me to look was another disheartening discovery. The "small
> special tool" Gnu diff has a 95-page manual!  And it doesn't cover the
> option I was looking up (-h). To be fair, the manual includes related
> programs like diff3(1), sdiff(1) and patch(1), but the original manual for
> each fit on one page.

Normally I agree with Doug but on documentation, the less is more leaves me
cold.  It's fine when it is V7 cat that had maybe an option or two.  GNU
diff is a complex beast and it needs lots of docs.

Personally, I like it when man pages have a few usage examples, the BitKeeper
docs are like that.  But I'm ok with a terse man page with a SEE ALSO that
points to a user guide.

Docs should be helpful.
-- 
---
Larry McVoy           Retired to fishing          http://www.mcvoy.com/lm/boat

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Ralph Corderoy]

Hi Doug,

>        % less --help | wc -l
>       298
> Last time I looked, the line count was about 220. Bloat is self-catalyzing.

Adding a --help option is a sign the man page lacks succintness.
It's the easier solution.

Another point against adding --help: there's a second attempt to
describe the source.

-- 
Cheers, Ralph.

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Peter Weinberger (温博格) via TUHS]

There is a common problem in our field. When something (a command, a
language, a library, etc) has a flaw, we say to ourselves, "This is
not good. If we remove this flaw things will be better."  as if it's
an obvious truth.

Sometimes it is true, but it's frequently questionable, and all too
often it's just wrong. We have no commonly accepted way of balancing
complexity and function; usually complexity wins. When AI takes my job
it will be because it's better at dealing with the mindless complexity
of enormous APIs (and command-line flags).


On Sat, May 18, 2024 at 2:08 PM Douglas McIlroy
<douglas.mcilroy@dartmouth.edu> wrote:
>
> I just revisited this ironic echo of Mies van der Rohe's aphorism, "Less is more".
>        % less --help | wc
>       298
> Last time I looked, the line count was about 220. Bloat is self-catalyzing.
>
> What prompted me to look was another disheartening discovery. The "small special tool" Gnu diff has a 95-page manual!  And it doesn't cover the option I was looking up (-h). To be fair, the manual includes related programs like diff3(1), sdiff(1) and patch(1), but the original manual for each fit on one page.
>
> Doug

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Clem Cole]

[-- Attachment #1: Type: text/plain, Size: 3144 bytes --]

On Sat, May 18, 2024 at 2:18 PM Larry McVoy <lm@mcvoy.com> wrote:

> But I'm ok with a terse man page with a SEE ALSO that points to a user
> guide.
>
Only if the SEE ALSO has more complete and relevant information -
otherwise, it degrades to VMS's famous "see figure 1" SPR.

>
> Docs should be helpful.
>
And easy to extract information.

The issue to be comes back to the type of information each document is
designed to give. I believe there at least three types of docs:

   1. Full manuals explain how something is built and it it used.  It helps
   to have theory/principles of operations behind it and enough detail when
   done, you can understand why and how to use it.
   2. Tutorials are excellent for someone trying to learn a new tool.  Less
   theory - and more -- examples, showing off the features and how to do
   something.
   3. References pages - need to be quick look-ups to remind someone how to
   use something - particularly for tools you don't use every
   day/generally don't memorize.


There are at least two more: an academic paper which might be looked at as
a start of #1 and full books which take #1 to even more details.  Some
academic papers indeed are fine manuals, and I can also argue the "manual"
for some tools like awk/sed or, for that matter, yacc(1) are full
books. But the idea is the >>complete<< review here.

Tutorials and reference pages are supposed to easy helpful things -- but
often miss the mark for the audience.  To me, the problem is the wrong type
of information is put in each one and, more importantly, people's
expectations from the document.  I love properly built manual pages - I
detest things like the VMS/TOPS help command or gnu info pages. What I
really hate is when there is no manual, but they tell you see the HELP
command -- but which command or "subtopic" -- Yikes.  The traditional
man system is simple quick reminders, basic reference and I can move on.
For instance, I needed to remember which C library has the definition these
days for some set of functions and what are its error return codes -- man 3
functions, I'm done.

Tutorials are funny.  For some people, what they want to learn the ideas
behind a tool.  Typically, I don't need that as much as how this toll does
some function.   For instance, Apple is forcing me the learn lldb because
the traditional debuggers derived from UCB's DBX are not there.   It's
similar to different.  The man page is useful only for the command lines
switches.   It turns out the commands are all really long, but they have
abbreviations and can be aliases.  I found references to this in an lldb
tutorial - but the tutorial is written to teach people more how to use a
debugger to debug there code, and less how this debugger maps into the
traditional functions.  Hey I would like to find an cheat sheet or a set of
aliases that map DBX/GDB into it -- but so far I've found nothing.

So Larry -- I agree with you ... "*Docs should be helpful*," but I fear
saying like that is a bit like the Faber College Motto/Founder's
Quote: "*Knowledge
is good*."



ᐧ

[-- Attachment #2: Type: text/html, Size: 6731 bytes --]

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Luther Johnson]

[-- Attachment #1: Type: text/plain, Size: 4993 bytes --]

Complexity is entropy. It occurs naturally in all human endeavor. It
takes work to keep things small, orderly, and rational. But there is
also a point where although a tool may be perfect in its conception and
execution, from its own perspective, it is not as useful as a slightly
more disorderly version that does what people want it to do. "Well they
shouldn't want that !" is a common response. Then people write scripts
to do for themselves what the tool doesn't do. Which might be right, but
it might lead to a whole bunch of similar scripts to do the same thing,
just a little differently And that's when we discover that it would have
been better to have it in the one tool in the first place.

So it's a back and forth, trial and error process. Eventually new
balances get struck, and people of like minds and tastes find a new
center, like Plan 9, or other things.

Myself, I do tend to like tools that are smaller and more single-minded
in their function (and that makes it possible to have documentation that
is clearer and more concise), but as an example, sometimes I want the
"-u" switch on diff, to make a patch, sometimes I don't, the default
display is better for a quick review (but I think or expect that the
essential diff engine is being shared). It's all a matter of judgment,
but you can't apply good judgment until you have the experience gained
from trying several alternatives. So things will get bloated up, and
then they will need to be pruned and re-engineered, but hopefully we
don't throw out the most helpful exceptions to the rule just because
they don't fit with some sort of consistency aesthetic.

On 05/18/2024 11:52 AM, Clem Cole wrote:
>
>
> On Sat, May 18, 2024 at 2:18 PM Larry McVoy <lm@mcvoy.com
> <mailto:lm@mcvoy.com>> wrote:
>
>     But I'm ok with a terse man page with a SEE ALSO thatpoints to a
>     user guide.
>
> Only if the SEE ALSO has more complete and relevant information -
> otherwise, it degrades to VMS's famous "see figure 1" SPR.
>
>
>     Docs should be helpful.
>
> And easy to extract information.
>
> The issue to be comes back to the type of information each document is
> designed to give. I believe there at least three types of docs:
>
>  1. Full manuals explain how something is built and it it used.  It
>     helps to have theory/principles of operations behind it and enough
>     detail when done, you can understand why and howto use it.
>  2. Tutorials are excellent for someone trying to learn a new tool.
>     Less theory - and more -- examples, showing off the features and
>     how to do something.
>  3. References pages - need to be quick look-ups to remind someone how
>     to use something - particularly for tools you don't use every
>     day/generally don't memorize.
>
>
> There are at least two more: an academic paper which might be looked
> at as a start of #1 and full books which take #1 to even more
> details.  Some academic papers indeed are fine manuals, and I can also
> argue the "manual" for some tools like awk/sed or, for that matter,
> yacc(1) are full books. But the idea is the >>complete<< review here.
>
> Tutorials and reference pages are supposed to easy helpful things --
> but often miss the mark for the audience. To me, the problem is the
> wrong type of information is put in each one and, more importantly,
> people's expectations from the document.  I love properly builtmanual
> pages - I detest things like the VMS/TOPS help command or gnu info
> pages. What I really hate is when there is no manual, but they tell
> you see the HELP command -- but which command or "subtopic" -- Yikes.
> The traditional man system is simple quick reminders,
> basicreferenceand I can move on.  For instance, I needed to remember
> which C library has the definition these days for some set of
> functions and what are its error return codes -- man 3 functions, I'm
> done.
>
> Tutorials are funny.  For some people, what they want to learn the
> ideas behind a tool.  Typically, I don't need that as much as how this
> toll does some function.   For instance, Apple is forcing me the learn
> lldb because the traditional debuggers derived from UCB's DBX are not
> there.   It's similar to different. The man page is useful only for
> the command lines switches.   It turns out the commands are all really
> long, but they have abbreviations and can be aliases.  I found
> references to this in an lldb tutorial - but the tutorial is written
> to teach people more how to use a debugger to debug there code, and
> less how this debugger maps into the traditional functions.  Hey I
> would like to find an cheat sheet or a set of aliases that map DBX/GDB
> into it -- but so far I've found nothing.
>
> So Larry -- I agree with you ... "/Docs should be helpful/," but I
> fear saying like that is a bit like the Faber College
> Motto/Founder's Quote: "/Knowledge is good/."
>
>
>
> ᐧ


[-- Attachment #2: Type: text/html, Size: 11399 bytes --]

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Stuff Received]

On 2024-05-18 14:52, Clem Cole wrote (in part):
> Hey I would like to find 
> an cheat sheet or a set of aliases that map DBX/GDB into it -- but so 
> far I've found nothing.

Does this help? https://lldb.llvm.org/use/map.html

(I confess that learning lldb has been quite the chore.)

S.

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[segaloco via TUHS]

On Saturday, May 18th, 2024 at 12:19 PM, Luther Johnson <luther.johnson@makerlisp.com> wrote:

> Complexity is entropy. It occurs naturally in all human endeavor. It takes work to keep things small, orderly, and rational. But there is also a point where although a tool may be perfect in its conception and execution, from its own perspective, it is not as useful as a slightly more disorderly version that does what people want it to do. "Well they shouldn't want that !" is a common response. Then people write scripts to do for themselves what the tool doesn't do. Which might be right, but it might lead to a whole bunch of similar scripts to do the same thing, just a little differently And that's when we discover that it would have been better to have it in the one tool in the first place.
> 
> So it's a back and forth, trial and error process. Eventually new balances get struck, and people of like minds and tastes find a new center, like Plan 9, or other things.
> 
> Myself, I do tend to like tools that are smaller and more single-minded in their function (and that makes it possible to have documentation that is clearer and more concise), but as an example, sometimes I want the "-u" switch on diff, to make a patch, sometimes I don't, the default display is better for a quick review (but I think or expect that the essential diff engine is being shared). It's all a matter of judgment, but you can't apply good judgment until you have the experience gained from trying several alternatives. So things will get bloated up, and then they will need to be pruned and re-engineered, but hopefully we don't throw out the most helpful exceptions to the rule just because they don't fit with some sort of consistency aesthetic.
> 
> On 05/18/2024 11:52 AM, Clem Cole wrote:
> 
> > 
> > 
> > On Sat, May 18, 2024 at 2:18 PM Larry McVoy <lm@mcvoy.com> wrote:
> > 
> > > But I'm ok with a terse man page with a SEE ALSO that points to a user guide.
> > 
> > Only if the SEE ALSO has more complete and relevant information - otherwise, it degrades to VMS's famous "see figure 1" SPR.
> > 
> > > 
> > > Docs should be helpful.
> > 
> > And easy to extract information.
> > 
> > 
> > The issue to be comes back to the type of information each document is designed to give. I believe there at least three types of docs:
> > 
> > 1.  Full manuals explain how something is built and it it used. It helps to have theory/principles of operations behind it and enough detail when done, you can understand why and how to use it.
> > 2.  Tutorials are excellent for someone trying to learn a new tool. Less theory - and more -- examples, showing off the features and how to do something.
> > 3.  References pages - need to be quick look-ups to remind someone how to use something - particularly for tools you don't use every day/generally don't memorize.
> > 
> > 
> > 
> > There are at least two more: an academic paper which might be looked at as a start of #1 and full books which take #1 to even more details. Some academic papers indeed are fine manuals, and I can also argue the "manual" for some tools like awk/sed or, for that matter, yacc(1) are full books. But the idea is the >>complete<< review here.
> > 
> > 
> > Tutorials and reference pages are supposed to easy helpful things -- but often miss the mark for the audience. To me, the problem is the wrong type of information is put in each one and, more importantly, people's expectations from the document. I love properly built manual pages - I detest things like the VMS/TOPS help command or gnu info pages. What I really hate is when there is no manual, but they tell you see the HELP command -- but which command or "subtopic" -- Yikes. The traditional man system is simple quick reminders, basic reference and I can move on. For instance, I needed to remember which C library has the definition these days for some set of functions and what are its error return codes -- man 3 functions, I'm done.
> > 
> > 
> > Tutorials are funny. For some people, what they want to learn the ideas behind a tool. Typically, I don't need that as much as how this toll does some function. For instance, Apple is forcing me the learn lldb because the traditional debuggers derived from UCB's DBX are not there. It's similar to different. The man page is useful only for the command lines switches. It turns out the commands are all really long, but they have abbreviations and can be aliases. I found references to this in an lldb tutorial - but the tutorial is written to teach people more how to use a debugger to debug there code, and less how this debugger maps into the traditional functions. Hey I would like to find an cheat sheet or a set of aliases that map DBX/GDB into it -- but so far I've found nothing.
> > 
> > 
> > So Larry -- I agree with you ... "Docs should be helpful," but I fear saying like that is a bit like the Faber College Motto/Founder's Quote: "Knowledge is good."
> > 
> > 
> > 
> > 
> > ᐧ

Facing ever-growing complexity, I often find myself turning strictly to the POSIX/SUS manpages for anything that has one, not only due to an interest in keeping things as portable as possible, but also admittedly out of some trepidation that the cool shiny specific feature of the week for a specific implementation doesn't have quite the same stabilizing standard behind it, and as such has the unlikely but real potential to change right out from under you in a new major version.  Issuing 'man 1p' or 'man 3p' before most studying has become habit, turning to a vendors' docs only when necessary.

Granted, no standardization of debuggers, assemblers, linkers, etc. makes this much trickier when working with embedded stuff or intensive diagnostics, so in that regard I've thus far been aligned with the GNU family of these components.  For the sake of embedded devs, it would be nice if the as/ld/db set of utilities had some sort of guiding light driving disparate implementations.  A particular example of divergent behavior wearing a familiar mask is the cc65 suite.  The assembler and linker smell of predictable UNIX fare, but differ in a number of little, quite annoying ways, among them "export" instead of "globl", cheap labels based strictly on counts forward and backward rather than recyclable numeric labels, just little things.  While a standard isn't the end all be all solution to everything, it certainly decreases at least some of the cognitive load, giving you a subset of behaviors to learn once, only turning to specifics when you've exhausted your options (or patience) with the intersections of various implementations.

I see a domino effect in this sort of thing too, one basal tool diverges a bit from other versions, then folks who only ever use that implementation head down a new fork in the road, those in their "camp" follow, before long whatever that difference is happens to be entrenched in a number of folks' vocabularies.  Like linguistic divergence, eventually the dialectical bits of how they work are no longer mutually intelligible.  The Tower of Babel grows ever higher, only time will tell whether the varied, sometimes contradictory styles of architecture are a strength or weakness.  Like evolution, oft times the most successful, sensible approaches prevail, but nature has a funny way of lapsing on our narrow understanding of "fitness" too.  After all, most of what many of us use on the regular guarantees no "fitness for a particular purpose".  Does this make stability an organic consequence or a happy accident?  I know I couldn't say.

- Matt G.

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Steffen Nurpmeso]

Douglas McIlroy wrote in
 <CAKH6PiXaYGEUmVFRX99eM6s3+nTJrbVvkuBRa-Awhhd69xzJrg@mail.gmail.com>:
 |I just revisited this ironic echo of Mies van der Rohe's aphorism, "Less is
 |more".
 |       % less --help | wc
 |      298
 |Last time I looked, the line count was about 220. Bloat is self-catalyzing.

I do not buy that.
You are working on Windows and in the meantime have switched to
one of those graphical browser monsters (i think) where each
instance has more code active than the entire Unix history
altogether.

less(1) can now Unicode, and that is not as easy with ISO/POSIX as
it was on Plan9 for example which simply goes UTF-8 and has some
(smart) lookup tables (now in go, more or less, last i looked),
but that is not the whole picture of it.

It can those ANSI / ISO 6429 color sequences that everybody wants,
as you have them everywhere, even GNU's yacc, bison.

The OpenBSD people took a port done by an OpenSolaris (i think,
that scene, anyhow) guy, and together they stripped it down
massively.

But i do not use it, because after almost exactly a decade i got
upstreamed to Nudelman's less(1) the necessary patches to have
active hyperlinks on the terminal, in a normal Unix (roff mdoc)
manual.  (These work via OSC-8 escape sequences; it was a "15
files changed, 601 insertions(+), 9 deletions(-)" patch, which
included careful quoting of file paths etc. for man(1) openings
(ie, such code gets lengthy), but he did it differently a bit, and
left off some things i wanted, included others (good), but if you
use --mouse with his one then you have a real browser feeling.
I have problems with --mouse, unfortunately, because when used you
can no longer copy+paste -- he would need to add clipboard control
in addition i'd say.., adding even more code.)

You know, it may be viable for some tools, but for others, .. not.
You say it yourself in your "A Research UNIX Reader": "Electronic
mail was there from the start.  Never satisfied with its exact
behavior, everybody touched it at one time or another".
In the meantime the IETF went grazy and produced masses of
standards, and unfortunately each one adds a little bit that needs
to be addressed differently, and all that needs documentation.
Now mail is an extreme example.

And almost a quarter of a century ago i wrote a small pager that
even had a clock, and it required less CPU on a day with some
scrolling than less/ncurses for a one time scroll through the
document.  But that pager is history, and less is still there,
running everywhere, and being used by me dozens to hundreds time
a day.  Also with colours, with searching, and now also with

  ^O^N  ^On         *  Search forward for (N-th) OSC8 hyperlink.
  ^O^P  ^Op         *  Search backward for (N-th) OSC8 hyperlink.
  ^O^L  ^Ol            Jump to the currently selected OSC8 hyperlink.

And prepared mdoc manuals can now display on a normal Unix
terminal in a normal (actively OSC-8 supporting $PAGER) a TOC (at
will, with links), and have external (man:, but also http: etc;
man is built into less(1) -- yay!) links, too.
For example here ∞ is an external, and † are internal links:

   The OpenSSL program ciphers(1)∞ should be referred to when creating a
   custom cipher list.  Variables of interest for TLS in general are
   tls-ca-dir†, tls-ca-file†, tls-ca-flags†, tls-ca-no-defaults†,
   tls-config-file†, tls-config-module†, tls-config-pairs

So ^O^L on that ciphers(1) opens a new man(1)ual instance.
For all this functionality a program with 221K bytes is small:

  221360 May 18 22:13 ...less*

Also it starts up into interactive mode with --help.
So you could have "full interactivity" and colours and mouse, and
configurability to a large extend, which somehow has to be
documented, in just 221 K bytes.

I give in in that i try to have --help/-h and --long-help/-H, but
sometimes that -h is only minimal, because a screenful of data is
simply not enough to allow users to have a notion.

So less could split the manual into a less.1 and a less-book.7.
The same is true for bash, for sure.  (And for my little mailer.)
But things tend to divert, and it is hard enough to keep one
manual in sync with the codebase, especially if you develop
focused and expert-idiotized in a one man show.

 |What prompted me to look was another disheartening discovery. The "small
 |special tool" Gnu diff has a 95-page manual!  And it doesn't cover the
 |option I was looking up (-h). To be fair, the manual includes related
 |programs like diff3(1), sdiff(1) and patch(1), but the original manual for
 |each fit on one page.
 --End of <CAKH6PiXaYGEUmVFRX99eM6s3+nTJrbVvkuBRa-Awhhd69xzJrg@mail.gmail\
 .com>

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

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Marc Rochkind]

[-- Attachment #1: Type: text/plain, Size: 5455 bytes --]

UNIX man pages were almost universally accurate, complete, and succinct.

That third admirable attribute gave me the opportunity to write *Advanced
UNIX Programming*.

So I wasn't complaining.

Marc

On Sat, May 18, 2024, 11:33 PM Steffen Nurpmeso <steffen@sdaoden.eu> wrote:

> Douglas McIlroy wrote in
>  <CAKH6PiXaYGEUmVFRX99eM6s3+nTJrbVvkuBRa-Awhhd69xzJrg@mail.gmail.com>:
>  |I just revisited this ironic echo of Mies van der Rohe's aphorism, "Less
> is
>  |more".
>  |       % less --help | wc
>  |      298
>  |Last time I looked, the line count was about 220. Bloat is
> self-catalyzing.
>
> I do not buy that.
> You are working on Windows and in the meantime have switched to
> one of those graphical browser monsters (i think) where each
> instance has more code active than the entire Unix history
> altogether.
>
> less(1) can now Unicode, and that is not as easy with ISO/POSIX as
> it was on Plan9 for example which simply goes UTF-8 and has some
> (smart) lookup tables (now in go, more or less, last i looked),
> but that is not the whole picture of it.
>
> It can those ANSI / ISO 6429 color sequences that everybody wants,
> as you have them everywhere, even GNU's yacc, bison.
>
> The OpenBSD people took a port done by an OpenSolaris (i think,
> that scene, anyhow) guy, and together they stripped it down
> massively.
>
> But i do not use it, because after almost exactly a decade i got
> upstreamed to Nudelman's less(1) the necessary patches to have
> active hyperlinks on the terminal, in a normal Unix (roff mdoc)
> manual.  (These work via OSC-8 escape sequences; it was a "15
> files changed, 601 insertions(+), 9 deletions(-)" patch, which
> included careful quoting of file paths etc. for man(1) openings
> (ie, such code gets lengthy), but he did it differently a bit, and
> left off some things i wanted, included others (good), but if you
> use --mouse with his one then you have a real browser feeling.
> I have problems with --mouse, unfortunately, because when used you
> can no longer copy+paste -- he would need to add clipboard control
> in addition i'd say.., adding even more code.)
>
> You know, it may be viable for some tools, but for others, .. not.
> You say it yourself in your "A Research UNIX Reader": "Electronic
> mail was there from the start.  Never satisfied with its exact
> behavior, everybody touched it at one time or another".
> In the meantime the IETF went grazy and produced masses of
> standards, and unfortunately each one adds a little bit that needs
> to be addressed differently, and all that needs documentation.
> Now mail is an extreme example.
>
> And almost a quarter of a century ago i wrote a small pager that
> even had a clock, and it required less CPU on a day with some
> scrolling than less/ncurses for a one time scroll through the
> document.  But that pager is history, and less is still there,
> running everywhere, and being used by me dozens to hundreds time
> a day.  Also with colours, with searching, and now also with
>
>   ^O^N  ^On         *  Search forward for (N-th) OSC8 hyperlink.
>   ^O^P  ^Op         *  Search backward for (N-th) OSC8 hyperlink.
>   ^O^L  ^Ol            Jump to the currently selected OSC8 hyperlink.
>
> And prepared mdoc manuals can now display on a normal Unix
> terminal in a normal (actively OSC-8 supporting $PAGER) a TOC (at
> will, with links), and have external (man:, but also http: etc;
> man is built into less(1) -- yay!) links, too.
> For example here ∞ is an external, and † are internal links:
>
>    The OpenSSL program ciphers(1)∞ should be referred to when creating a
>    custom cipher list.  Variables of interest for TLS in general are
>    tls-ca-dir†, tls-ca-file†, tls-ca-flags†, tls-ca-no-defaults†,
>    tls-config-file†, tls-config-module†, tls-config-pairs
>
> So ^O^L on that ciphers(1) opens a new man(1)ual instance.
> For all this functionality a program with 221K bytes is small:
>
>   221360 May 18 22:13 ...less*
>
> Also it starts up into interactive mode with --help.
> So you could have "full interactivity" and colours and mouse, and
> configurability to a large extend, which somehow has to be
> documented, in just 221 K bytes.
>
> I give in in that i try to have --help/-h and --long-help/-H, but
> sometimes that -h is only minimal, because a screenful of data is
> simply not enough to allow users to have a notion.
>
> So less could split the manual into a less.1 and a less-book.7.
> The same is true for bash, for sure.  (And for my little mailer.)
> But things tend to divert, and it is hard enough to keep one
> manual in sync with the codebase, especially if you develop
> focused and expert-idiotized in a one man show.
>
>  |What prompted me to look was another disheartening discovery. The "small
>  |special tool" Gnu diff has a 95-page manual!  And it doesn't cover the
>  |option I was looking up (-h). To be fair, the manual includes related
>  |programs like diff3(1), sdiff(1) and patch(1), but the original manual
> for
>  |each fit on one page.
>  --End of <CAKH6PiXaYGEUmVFRX99eM6s3+nTJrbVvkuBRa-Awhhd69xzJrg@mail.gmail\
>  .com>
>
> --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: 6358 bytes --]

[TUHS] The 'usage: ...' message. (Was: On Bloat...)

[Ralph Corderoy]

Hi,

I wrote:
> Another point against adding --help: there's a second attempt to
> describe the source.

It occurred to me --help's the third attempt as there's already ‘usage:
argv[0] ...’.  Back when running man took time and paper, I can see
a one-line summary to aid memory was useful.  I wondered when it first
appeared.

I've found V2, https://www.tuhs.org/cgi-bin/utree.pl?file=V2/cmd, has
cmp.s with

    cmp     (sp)+,$3
    beq     1f
    jsr     r5,mesg; <Usage: cmp arg1 arg2\n\0>; .even
    sys     exit

And cp.c has

    if(argc != 3) {
	    write(1,"Usage: cp oldfile newfile\n",26);
	    exit();
    }

Given the lack of options, the need for a usage message surprises me.
But then ‘cp a-src a-dest b-src b-dest ...’ used to copy files in pairs.
Perhaps when this was dropped, one too many losses?, the usage was
needed to remind users of the change.

Any earlier Unix examples known by the list?
And was ‘usage: ...’ adopted from an earlier system?

-- 
Cheers, Ralph.

[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[Adam Thornton]

[-- Attachment #1: Type: text/plain, Size: 640 bytes --]

I can't tell you--although some of you will know--what a delight it is to
be working on a project with an actual documentation engineer.

That person (Jonathan Sick, if any of you want to hire him) has engineered
things such that it is easy to write good documentation for the projects we
write, and not very onerous.

He's put in an enormous amount of effort to ensure that if we write
reasonably clean code, we can also auto-generate accurate and complete API
documentation for it.  And to the degree we want to write explanatory docs,
that's catered for too.

It has been an amazing experience compared to my entire prior history.

Adam

[-- Attachment #2: Type: text/html, Size: 786 bytes --]

[TUHS] Documentation (was On Bloat and the Idea of Small Specialized Tools)

[Paul Winalski]

[-- Attachment #1: Type: text/plain, Size: 1344 bytes --]

On Mon, May 20, 2024 at 2:08 AM Adam Thornton <athornton@gmail.com> wrote:

> I can't tell you--although some of you will know--what a delight it is to
> be working on a project with an actual documentation engineer.
>
> That person (Jonathan Sick, if any of you want to hire him) has engineered
> things such that it is easy to write good documentation for the projects we
> write, and not very onerous.
>
> Design for documentability, testability, and ease of maintenance are what
distinguishes good software engineering from hackery.

Back when I worked in DEC's software development tools group, we had
professional technical writers who write the manuals and online help text.
There was an unexpected (at least by me) benefit during a project's design
phase, too.  Documentation was written in parallel with the code, so once
the user interface specification was arrived at, first order of business
was to sit down with the tech writer and explain it to them.  Sometimes in
the process of doing that youd stop and think, "wait a minute--we don't
really want it doing that".  Or you'd find that you bhad difficulty
articulating exactly how a particular feature behaves.  That's a red flag
that you've designed the feature to be too obscure and complex, or that
there's something flat-out wrong with it.

-Paul W.

[-- Attachment #2: Type: text/html, Size: 1732 bytes --]

[TUHS] Re: Documentation (was On Bloat and the Idea of Small Specialized Tools)

[Andrew Hume]

> On May 20, 2024, at 8:43 AM, Paul Winalski <paul.winalski@gmail.com> wrote:
>   Sometimes in the process of doing that youd stop and think, "wait a minute--we don't really want it doing that".  Or you'd find that you bhad difficulty articulating exactly how a particular feature behaves.  That's a red flag that you've designed the feature to be too obscure and complex, or that there's something flat-out wrong with it.

that’s what i used doug mcilroy for! i especially remember that for mk(1).

[TUHS] Re: Documentation (was On Bloat and the Idea of Small Specialized Tools)

[Yeechang Lee]

Paul Winalski says:
> Sometimes in the process of doing that youd stop and think, "wait a
> minute--we don't really want it doing that".  Or you'd find that you
> bhad difficulty articulating exactly how a particular feature
> behaves.  That's a red flag that you've designed the feature to be
> too obscure and complex, or that there's something flat-out wrong
> with it.

My understanding is that an unexpected result of the requirement to draft all federal laws in Canada in both English and French is something similar: The discussion process ensuring that a bill's meaning is identical in both languages helps rid the text of ambiguities and errors regardless of language.

[TUHS] Re: Documentation (was On Bloat and the Idea of Small Specialized Tools)

[Phil Budne]

Yeechang Lee:
> My understanding is that an unexpected result of the requirement to
> draft all federal laws in Canada in both English and French is
> something similar: The discussion process ensuring that a bill's
> meaning is identical in both languages helps rid the text of
> ambiguities and errors regardless of language.

It always seemed to me that ISO standards were written to be equally
incomprehensible in all languages, substituting terms like Protocol
Data Unit (PDU) for familiar ones like Packet.

In the early Internet, where there wasn't ANY money to be made in
antisocial conduct, it was easier to justify sentiments like "Rough
consensus and working code" and "be liberal in what you accept".

Lest ye forget, "industry standards" were once limited to things like
magnetic patterns on half-inch tape and the serial transmission of
bits, and at the LOWEST of levels.  Reading a tape written on another
vendor's system wasn't easy when I got started in the early 80's; In
addition to ASCII and EBCDIC, there were still systems with
vendor-specific 6-bit character sets, never mind punched cards.  I
remember going on a campus tour in the late 70's where there was an
ASCII terminal hooked up to some system that had BASIC (the standard
at the time was ANSI "Minimal BASIC"; a full(er) standard took long
enough that it was dead on arrival), but instead of "RETURN" required
typing CTRL/C (defined in ASCII as End Of Text) to enter a line!

In that context, getting ANYTHING working across vendors was a
victory, and having one system refuse to speak to another because of
some small detail in what one of them considered reasonable (or not)
was asking for trouble.

The times and stakes today are distinctly different.

[TUHS] The 'usage: ...' message. (Was: On Bloat...)

[Douglas McIlroy]

[-- Attachment #1: Type: text/plain, Size: 2004 bytes --]

>> Another non-descriptive style of error message that I admired was that
>> of Berkeley Pascal's syntax diagnostics. When the LR parser could not
>> proceed, it reported where, and automatically provided a sample token
>> that would allow the parsing to progress. I found this uniform
>> convention to be at least as informative as distinct hand-crafted
>> messages, which almost by definition can't foresee every contingency.
>> Alas, this elegant scheme seems not to have inspired imitators.

> The hazard with this approach is that the suggested syntactic correction
> might simply lead the user farther into the weeds

I don't think there's enough experience to justify this claim. Before I
experienced the Berkeley compiler, I would have thought such bad outcomes
were inevitable in any language. Although the compilers' suggestions often
bore little or no relationship to the real correction,  I always found them
informative. In particular, the utterly consistent style assured there was
never an issue of ambiguity or of technical jargon.

The compiler taught me Pascal in an evening. I had scanned the Pascal
Report a couple of years before but had never written a Pascal program.
With no manual at hand, I looked at one program to find out what
mumbo-jumbo had to come first and how to print integers, then wrote the
rest by trial and error. Within a couple of hours  I had a working program
good enough to pass muster in an ACM journal.

An example arose that one might think would lead "into the weeds". The
parser balked before 'or' in a compound Boolean expression like  'a=b and
c=d or x=y'. It couldn't suggest a right paren because no left paren had
been seen. Whatever suggestion it did make (perhaps 'then') was enough to
lead me to insert a remote left paren and teach me that parens are required
around Boolean-valued subexpressions. (I will agree that this lesson might
be less clear to a programming novice, but so might be many conventional
diagnostics, e.g. "no effect".)

Doug

[-- Attachment #2: Type: text/html, Size: 3392 bytes --]

[TUHS] The 'usage: ...' message. (Was: On Bloat...)

[Douglas McIlroy]

[-- Attachment #1: Type: text/plain, Size: 1099 bytes --]

> was ‘usage: ...’ adopted from an earlier system?

"Usage" was one of those lovely ideas, one exposure to which flips its
status from unknown to eternal truth. I am sure my first exposure was on
Unix, but I don't remember when. Perhaps because it radically departs from
Ken's "?" in qed/ed, I have subconsciously attributed it to Dennis.

The genius of "usage" and "?" is that they don't attempt to tell one what's
wrong. Most diagnostics cite a rule or hidden limit that's been violated or
describe the mistake (e.g. "missing semicolon") , sometimes raising more
questions than they answer.

Another non-descriptive style of error message that I admired was that of
Berkeley Pascal's syntax diagnostics. When the LR parser could not proceed,
it reported where, and automatically provided a sample token that would
allow the parsing to progress. I found this uniform convention to be at
least as informative as distinct hand-crafted messages, which almost by
definition can't foresee every contingency. Alas, this elegant scheme seems
not to have inspired imitators.

Doug

[-- Attachment #2: Type: text/html, Size: 1310 bytes --]