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
