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

[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 --]

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

[Paul Winalski]

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

On Sun, May 19, 2024 at 10:03 AM Douglas McIlroy <
douglas.mcilroy@dartmouth.edu> wrote:

>
> 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.  It depends on how far
the parse has gone off the rails before a grammatical error is found.
Pascal and BASIC (at least the original Dartmouth BASIC) have simple,
well-behaved grammars and the suggested syntactic correction is likely to
be correct.  It doesn't work as well for more syntactically complicated
languages such as C (consider an error resulting from use of == instead of
=) or PL/I.  And it's nigh on impossible for languages with ill-behaved
grammars such as Fortran and COBOL (among other grammatical evils, Fortran
has context-sensitive lexiing).

Commercial compiler writers avoid this techniq

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

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

[Paul Winalski]

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

Ack!  I finger-fumbled and accidentally sent this message incomplete.
Here's the complete version.  Sorry about that, Chief!

On Sun, May 19, 2024 at 12:18 PM Paul Winalski <paul.winalski@gmail.com>
wrote:

> On Sun, May 19, 2024 at 10:03 AM Douglas McIlroy <
> douglas.mcilroy@dartmouth.edu> wrote:
>
>>
>> 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.  It depends on how far
> the parse has gone off the rails before a grammatical error is found.
> Pascal and BASIC (at least the original Dartmouth BASIC) have simple,
> well-behaved grammars and the suggested syntactic correction is likely to
> be correct.  It doesn't work as well for more syntactically complicated
> languages such as C (consider an error resulting from use of == instead of
> =) or PL/I.  And it's nigh on impossible for languages with ill-behaved
> grammars such as Fortran and COBOL (among other grammatical evils, Fortran
> has context-sensitive lexiing).
>
> Commercial compiler writers avoid this techniq
>

Commercial compiler writers avoid this technique because it turns into an
error report generator.  The potential user benefit is outweighed by all of
the "your compiler suggested X as a correction when the problem was Y"
that need to be answered.

-Paul W.

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

[TUHS] Re: The 'usage: ...' message.

[Ralph Corderoy]

Hi Doug,

> Perhaps because it radically departs from Ken's "?" in qed/ed

That spread elsewhere.  When PDP-7 Unix's cp.s is given an odd number of
arguments, leaving the last unpaired, it prints the argument followed by
‘ ?’.  https://www.tuhs.org/cgi-bin/utree.pl?file=PDP7-Unix/cmd/cp.s

    mes:
       040000;077012		

    unbal:				
       lac name2			
       tad d4			
       dac 1f
       lac d1
       sys write; 1: 0; 4
       lac d1
       sys write; mes; 2
       sys exit

-- 
Cheers, Ralph.

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

[Dave Horsfall]

On Sun, 19 May 2024, Douglas McIlroy wrote:

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

I did something like that for our compiler-writing assignment.  An 
ALGOL-like language (I think I used ALGOLW) it would detect when a 
semicolon was missing, and insert it (with a warning).  As a test case, it 
successfully compiled a program with no semicolons at all...

-- Dave

[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] 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

[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] 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.