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: Chet Ramey <chet.ramey@case.edu>
Newsgroups: gnu.bash.bug
Subject: Re: man bash does not list 'in' as a builtin command
Date: Tue, 26 Nov 2019 11:28:28 -0500
Lines: 64
Approved: bug-bash@gnu.org
Message-ID: <mailman.2726.1574785714.13325.bug-bash@gnu.org>
References: <4dc457e0135603025cd500acdc95db53f9d30482.camel@peterbenjamin.com> <6F7CBE03-C2F4-45CC-91D6-8A72A0C7B3B6@gmail.com> <8b8e4751-4a3c-825a-3dd4-96a788fedf06@case.edu>
Reply-To: chet.ramey@case.edu
NNTP-Posting-Host: lists.gnu.org
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Cc: chet.ramey@case.edu, "bash.bug list" <bug-bash@gnu.org>, bash@packages.debian.org
To: Clint Hepner <clint.hepner@gmail.com>, Peter Benjamin <pete@peterbenjamin.com>
Envelope-to: bug-bash@gnu.org
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:68.0) Gecko/20100101 Thunderbird/68.2.2
In-Reply-To: <6F7CBE03-C2F4-45CC-91D6-8A72A0C7B3B6@gmail.com>
Content-Language: en-US
Precedence: list
Xref: csiph.com gnu.bash.bug:15658

On 11/25/19 8:15 PM, Clint Hepner wrote:

> Alternatively, maybe a short list of sections at the top of the man page would provide
> a hint.

The man page format is pretty entrenched. This is an opportunity for other
tools to fill the gap.

> 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

If you want something like this, the info format is a good start. It has
tables of contents, menus with links, and internal cross-references.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/