Path: csiph.com!3.us.feeder.erje.net!feeder.erje.net!news.linkpendium.com!news.linkpendium.com!panix!usenet.stanford.edu!not-for-mail
From: Clint Hepner <clint.hepner@gmail.com>
Newsgroups: gnu.bash.bug
Subject: Re: man bash does not list 'in' as a builtin command
Date: Mon, 25 Nov 2019 20:15:12 -0500
Lines: 131
Approved: bug-bash@gnu.org
Message-ID: <mailman.2657.1574730908.13325.bug-bash@gnu.org>
References: <4dc457e0135603025cd500acdc95db53f9d30482.camel@peterbenjamin.com> <6F7CBE03-C2F4-45CC-91D6-8A72A0C7B3B6@gmail.com>
NNTP-Posting-Host: lists.gnu.org
Mime-Version: 1.0 (Mac OS X Mail 13.0 \(3601.0.10\))
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Cc: "bash.bug list" <bug-bash@gnu.org>, bash@packages.debian.org
To: Peter Benjamin <pete@peterbenjamin.com>
Envelope-to: bug-bash@gnu.org
In-Reply-To: <4dc457e0135603025cd500acdc95db53f9d30482.camel@peterbenjamin.com>
Precedence: list
Xref: csiph.com gnu.bash.bug:15647



> On 2019 Nov 25 , at 4:43 p, Peter Benjamin <pete@peterbenjamin.com> =
wrote:
>=20
>=20
> Description:
> 'in' is a builtin command and is not listed in the man page as such.
>=20
> Repeat-By:
>=20
> type at the bash command line:
>=20
> $ 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.

>=20
> 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=20
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=