> On 2019 Nov 25 , at 4:43 p, Peter Benjamin <p...@peterbenjamin.com> wrote:
>
>
> Description:
> 'in' is a builtin command and is not listed in the man page as such.
>
> Repeat-By:
>
> type at the bash command line:
>
> $ in
> bash: syntax error near unexpected token `in'
This should be a big hint that it is *not* a built-in command. If it
were, you would have run the command, not gotten a syntax error.
>
> Why is this bug report important? Why change the man page? I wasted
> 20 minutes of my time, to prove to my satisfaction that 'in' was not
> invoking my script at all. Search engines did not find a match to the
> error message. I can not imagine this report is the first time this
> bug was found.
Given that ``in'' *is* documented as a reserved word
RESERVED WORDS
Reserved words are words that have a special meaning to the shell.
The
following words are recognized as reserved when unquoted and either
the
first word of a simple command (see SHELL GRAMMAR below) or the
third
word of a case or for command:
! case coproc do done elif else esac fi for function if in
select
then until while { } time [[ ]]
the question becomes, what change to the man page do you think would have
helped you
find this more quickly?
One thing that comes to mind would be a short (though off-topic) entry in
the SHELL BUILTIN COMMANDS section, like
in
See the Compound Commands section under SHELL GRAMMMAR. Used
to form the ``case'', ``select'', and ``for'' commands.
I don't really like that idea, as it starts down a slippery slope for adding
all sorts of non-command entries, turning the section into a general glossary
rather than
a listing of built-in commands.
Alternatively, maybe a short list of sections at the top of the man page would
provide
a hint.
For example, imagine the man page started out like this:
NAME
bash - GNU Bourne-Again Shell
SYNOPSIS
bash [options] [command_string | file]
DESCRIPTION
Bash is [...]
TABLE OF CONTENTS
OPTIONS
ARGUMENTS
INVOCATION
DEFINITIONS
RESERVED WORDS
SHELL GRAMMAR
COMMENTS
QUOTING
PARAMETERS
EXPANSION
REDIRECTION
ALIASES
FUNCTIONS
ARITHMETIC EVALUATION
CONDITIONAL EXPRESSIONS
SIMPLE COMMAND EXPANSION
COMMAND EXECUTION
COMMAND EXECUTION ENVIRONMENT
ENVIRONMENT
EXIT STATUS
SIGNALS
JOB CONTROL
PROMPTING
READLINE
HISTORY
HISTORY EXPANSION
SHELL BUILTIN COMMANDS
RESTRICTED SHELL
SEE ALSO
FILES
AUTHORS
BUG REPORTS
BUGS
OPTIONS
All of the single-character shell options ...
[etc]
The table of contents inserted between the existing DESCRIPTION and OPTIONS
sections is relatively brief,
and both RESERVED WORDS and SHELL GRAMMAR seem like they would be good starting
places to look for
information about the ``in'' token mentioned in the syntax error.
Given how short most of the section names are, it could easily be formatted as
two columns, making it
easier to scan.
--
Clint