bug-bash
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: man bash does not list 'in' as a builtin command


From: Clint Hepner
Subject: Re: man bash does not list 'in' as a builtin command
Date: Mon, 25 Nov 2019 20:15:12 -0500


> On 2019 Nov 25 , at 4:43 p, Peter Benjamin <pete@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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]