Re: Shell Grammar man page

[Mike Jonkmans]

On Wed, Feb 24, 2021 at 12:08:50PM -0500, Chet Ramey wrote:
> On 2/23/21 7:31 PM, Mike Jonkmans wrote:
> > On Tue, Feb 23, 2021 at 04:33:44PM -0500, Chet Ramey wrote:
> > > On 2/22/21 8:11 AM, Mike Jonkmans wrote:
> > > > 
> > > > Hi,
> > > > 
> > > > It seems some things are missing in the bash manual.
> > > > Notably definition of command and placements of coproc- and 
> > > > function-definition.
> > > > 
> > > > The section 'SHELL GRAMMAR' describes:
> > > > - simple-command
> > > > - pipeline
> > > > - list
> > > > - compound-command
> > > > - coproc
> > > > - function-definition
> > > 
> > > These are basically the `command' productions from the grammar. The
> > > exception is `list', and it's there because it would be strange for
> > > the reader if it were presented before simple commands and pipelines,
> > > which users are more likely to encounter, even though a complete
> > > command is technically a list.
> > 
> > It is mostly recursive, so you have to start somewhere.
> 
> Sure. We start with lists. That's just not something that will resonate
> with a reader.
> 
> > Your reasoning is understandable. Start with what the reader knows.
> > Though the readers are likely to be familiar with grammars/rules/start 
> > symbols.
> 
> Readers are likely to be familiar with simple commands and pipelines,
> especially the ones who primarily use interactive shells. I disagree that
> the average reader is likely to be familiar with grammars.

Aren't grammars taught already in primary school? It is in the Netherlands.
But i agree that it is a good thing to let the text not depend on that.

Starting with 'Statements' might be an option.
E.g.

Shell Grammar
     Statements
       Input to bash is a sequence of statements separated by ;, &, or newline. 
           A statement sequence is parsed first. Only after a newline does bash
           perform any effects, like command execution, defined by these 
statements.
           A statement consists of simple-command, pipeline, compound-command, 
...
           (as defined below).

     Simple Commmand
     ...


> > Because 'command' is not described, a reader might think that all these 
> > items
> > are commands.
> > 
> > > > Simplified, a pipeline is:
> > > >         [ ! ] command1 [ | command2 ]
> > > > 
> > > > A list is a sequence of pipelines separated by ;, &, &&, or ||
> > > > and optionally terminated by ;, & or NL.
> > > > 
> > > > Within the list description, the and-list and or-list are described as:
> > > >         and-list: command1 && command2
> > > >         or-list: command1 || command2
> > > > Though the text says that and/or-lists are sequences of pipelines
> > > > (separated by && or ||).
> > > 
> > > `command1' and `command2' are meta-notation, not a grammar production.
> > 
> > I know. It is just as the man page describes it.
> > The numbering is quite handy for referring in the text.
> > 
> > > > That is slightly inconsistent.
> > > Not really.
> > > 
> > > > A pipeline can be reduced to a command.
> > > In a sense, yes, depending on your definition of `command'.
> > 
> > That is the point. The documentation never describes what a 'command' is.
> > The inconsistency comes when you try to follow the documentation's
> > use of 'command'. It is only in the words, not in the real grammar of 
> > course.
> 
> So where would you suggest changes? I'd argue that the use of `command' in
> the simple commands section is quite clear. I'd also argue that everyone
> understands what `the last command in a pipeline' means, or `commands in a
> list', and that those are more descriptive than `pipeline elements' or
> `list elements'.

I agree that the usage of 'command' is clear in these cases.
But these commands are different things.
The command in pipelines might be better described as compound-command.

May I also suggest to make it more clear that coprocesses and
function-definitions are compound-commands also?
The indentation of these differ from the preceding while/if/etc.

The description of Coprocesses uses the words 'shell command'. 
That looks like it came from shell_command in parse.y and is actually 
a compound-command without coproc and funcdef (limited-compound-command?).
The 'command' in 'coproc [NAME] command [redirections]' is also
a limited-compound-command.
Better word? shell-command has drawbacks.
Maybe just mention in the text that the compound-command is limited
or leave coproc/funcdefs outside of compound-command (but i think that would
need more mentioning).

sidenote: parse.y has:
 - 'shell_command' which has for/while/if/etc. constructs;
 - 'command' (shell_command + coproc + funcdef)
        which is equivalent to compound-command.


> I do think I'll change the pipeline description to use `command1' instead
> of `command', though.

Yes, the numbering is consistent with other uses.

> > > > In that case, the and/or list should read:
> > > >         and-list: pipeline1 && pipeline2
> > > >         or-list: pipeline1 || pipeline2
> > > 
> > > No, it really shouldn't.
> > 
> > You're right. These pipelines should be lists.
> 
> No. An and-or list is
> 
>       and-or: and-or && pipeline
>             | and-or || pipeline
>             | pipeline

parse.y has lists (simple_list1 and list1) between && and ||.

Ah, I see, you are using the Posix grammar.
That would translate to 'pipeline1 [ &&⎪|| pipeline2 ]' in the manual page.


Regards, Mike Jonkmans