bash: bash.1: Some remarks and editorial fixes for the man page

[Bjarni Ingi Gislason]

Package: bash
Version: 5.2.15-2+b5
Severity: minor
Tags: patch

Dear Maintainer,

here are some notes and an editorial changes for the manual.

The patch is in the attachment.

-.-

The difference between the formatted outputs can be seen with:

  nroff -man <file1> > <out1>
  nroff -man <file2> > <out2>
  diff -u <out1> <out2>

and for groff, using

"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "

instead of "nroff -man"

  Add the option "-t", if the file contains a table.

  Read the output of "diff -u" with "less -R" or similar.

-.-.

  If "man" (man-db) is used to check the manual for warnings,
the following must be set:

  The option "-warnings=w"

  The environmental variable:

export MAN_KEEP_STDERR=yes (or any non-empty value)

  or

  (produce only warnings):

export MANROFFOPT="-ww -z"

export MAN_KEEP_STDERR=yes (or any non-empty value)

-.-.

Output from "mandoc -T lint bash.1":

mandoc: bash.1:533:105: STYLE: input text line longer than 80 bytes: ! case  
coproc  do d...
mandoc: bash.1:534:166: STYLE: input text line longer than 80 bytes: !    case  
  coproc ...
mandoc: bash.1:556:90: STYLE: input text line longer than 80 bytes: [\fBtime\fP 
[\fB\-p\...
mandoc: bash.1:2568:42: STYLE: whitespace at end of input line
mandoc: bash.1:3409:70: STYLE: whitespace at end of input line
mandoc: bash.1:3952:2: WARNING: skipping paragraph macro: br before sp
mandoc: bash.1:3965:89: STYLE: input text line longer than 80 bytes: alnum 
alpha ascii bl...
mandoc: bash.1:3966:115: STYLE: input text line longer than 80 bytes: alnum   
alpha   asci...
mandoc: bash.1:3970:2: WARNING: skipping paragraph macro: br before sp
mandoc: bash.1:3981:2: WARNING: skipping paragraph macro: br before sp
mandoc: bash.1:5333:68: STYLE: whitespace at end of input line
mandoc: bash.1:5998:35: STYLE: whitespace at end of input line
mandoc: bash.1:6010:35: STYLE: whitespace at end of input line
mandoc: bash.1:6011:82: STYLE: input text line longer than 80 bytes: A string 
variable th...
mandoc: bash.1:6011:82: STYLE: whitespace at end of input line
mandoc: bash.1:6104:70: STYLE: whitespace at end of input line
mandoc: bash.1:6137:71: STYLE: whitespace at end of input line
mandoc: bash.1:6138:30: STYLE: whitespace at end of input line
mandoc: bash.1:6139:73: STYLE: whitespace at end of input line
mandoc: bash.1:6141:42: STYLE: whitespace at end of input line
mandoc: bash.1:6200:70: STYLE: whitespace at end of input line
mandoc: bash.1:6265:70: STYLE: whitespace at end of input line
mandoc: bash.1:7284:1: WARNING: tab in filled text
mandoc: bash.1:7708:2: WARNING: skipping paragraph macro: PP after SH
mandoc: bash.1:7908:68: STYLE: whitespace at end of input line
mandoc: bash.1:8110:158: STYLE: input text line longer than 80 bytes: 
[\fB\-F\fP \fIfuncti...
mandoc: bash.1:8417:37: STYLE: whitespace at end of input line
mandoc: bash.1:10788:52: STYLE: whitespace at end of input line
mandoc: bash.1:11389:55: STYLE: whitespace at end of input line
mandoc: bash.1:11584:2: WARNING: skipping paragraph macro: PP after SH

-.-.

chk_man: Next line: execute doclifter -w -v bash.1
bash.1 uses man macros...
bash.1:11720: warning - variable-list header just before section break
bash.1:11803: warning - variable-list header just before section break
"bash.1": warning - portability warning: nonportable requests 'end' seen.

-.-.

Input file is bash.1.

Remove space characters at the end of lines.

Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".

2568:If this is set but not an array variable, 
3409:If there are two slashes separating \fIparameter\fP and \fIpattern\fP 
5333:When \fBbash\fP is running without job control enabled and receives 
5998:.B active\-region\-start\-color   
6010:.B active\-region\-end\-color     
6011:A string variable that "undoes" the effects of 
\fBactive\-region\-start\-color\fP 
6104:This variable is dependent on the \fBLC_CTYPE\fP locale category, and 
6137:The \fIpoint\fP is the current cursor position, and \fImark\fP refers  
6138:to a saved cursor position.   
6139:The text between the point and mark is referred to as the \fIregion\fP.  
6141:to designate the region as \fIactive\fP.  
6200:This variable is dependent on the \fBLC_CTYPE\fP locale category, and 
6265:This variable is dependent on the \fBLC_CTYPE\fP locale category, and 
7908:The shell assigns any numeric argument the user supplied to the     
8417:(except the \fInameref\fP attribute) 
10788:Expressions are composed of the primaries described 
11389:default behavior in bash-3.2 and subsequent versions). 

-.-.

Change two HYPHEN-MINUSES (code 0x055, 2D) to an em-dash (\(em),
if one is intended.  An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters) transforms an en-dash (\(en ) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".

bash.1:11380:compatibility level -- each option is mutually exclusive.
bash.1:11691:http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix 
mode

-.-.

Use the correct macro for the font change of a single argument or
split the argument into two.

1994:.BR RANDOM

-.-.

Change - to \- if it shall be printed as a minus sign.

bash.1:9448:.if n ``popd -0''
bash.1:9449:.if t \f(CWpopd -0\fP
bash.1:9451:.if n ``popd -1''
bash.1:9452:.if t \f(CWpopd -1\fP

-.-.

Use the word (in)valid instead of (il)legal,
if not related to legal matters.
See "www.gnu.org/prep/standards".
Think about translations into other languages!

bash.1:2856:Any reference to a variable using a valid subscript is legal, and

-.-.

Remove space in the first column, if not indented.

bash.1:6350: extends to the end of the line;

-.-.

Change a HYPHEN-MINUS (code 0x55, 2D) to a minus (\-), if in front of a
name for an option, or is a symbol for standard input.

66:is an \fBsh\fR-compatible command language interpreter that
540:followed by \fBblank\fP-separated words and redirections, and
1377:.if t \f(CWdeclare -n ref=$1\fP
1378:.if n declare -n ref=$1
2004:.if t \f(CWbind -x\fP
2005:.if n "bind -x"
2016:.if t \f(CWbind -x\fP
2017:.if n "bind -x"
2027:.if t \f(CWbind -x\fP
2028:.if n "bind -x"
2040:.if t \f(CWbind -x\fP
2041:.if n "bind -x"
2160:.if t \f(CWset -x\fP
2161:.if n \fIset -x\fP
2558:.if t \f(CWset -o posix\fP
2559:.if n \fIset -o posix\fP
7288:complete -D -F _completion_loader -o bashdefault -o default
8675:.if t \f(CWenable -n test\fP.
8676:.if n ``enable -n test''.
8705:.if n ``enable -f \fIname name\fP .
8875:.if n ``r="fc -s"'',
9134:\fBhistory -d\fP command.
9457:the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
11055:.if t \f(CWtype -t name\fP
11056:.if n ``type -t name''
11065:.if t \f(CWtype -t name\fP
11066:.if n ``type -t name''
11509:(e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage 
is
11663:\fBset +r\fP or \fBshopt -u restricted_shell\fP.

-.-.

Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.

755:BUILTIN COMMANDS below) for the handling of parameters (i.e.

-.-.

Wrong distance between sentences.

  Separate the sentences and subordinate clauses; each begins on a new
line.  See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").

  The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.

Remember coding: Only one command ("sentence") on each (logical) line.

E-mail: Easier to quote exactly the relevant lines.

Generally: Easier to edit the sentence.

Patches: Less unaffected text.

Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.

  The amount of space between sentences in the output can then be
controlled with the ".ss" request.

N.B

  The number of lines affected is too large to be in the patch.

556:[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] 
\fIcommand2\fP ... ]
814:indices. The element of
956:[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
1015:If \fIcommand\fP is a compound command, \fINAME\fP is optional. The
1325:is evaluated as an arithmetic expression even if the $((...)) expansion is
1483:Expands to the process ID of the shell. In a subshell, it
2097:referenced. The random number generator is not linear on systems that
2781:\fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
5552:job changes state. The \fB\-f\fP option causes \fBwait\fP to wait
6138:to a saved cursor position.   
6389:minor version (e.g., \fB7.1\fP). If the minor version is omitted, it
6417:Both string and boolean variables may be tested. Boolean variables must be
6519:physical screen line. This will not have the desired effect if the current
6525:physical screen line. This will not have the desired effect if the current
7284:   . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
8564:\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ]
8990:places ? into
9191:\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ]
9194:\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
9306:\fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ]
10207:The positional parameters from \fIn\fP+1 ... are renamed to
10631:returns. This is identical to the behavior of unsetting local variables
10712:alias expansion. If it has an alias, \fBbash\fP attempts programmable
11384:behavior. It's intended to be a temporary solution.
11419:option for the previous version. Users should use
11509:(e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage 
is
11519:or continue loops in the calling context. Bash-4.4 and later reset
11556:more randomness. If the shell compatibility level is set to 50 or
11565:output that can be reused as input. Bash-5.1 suppresses that message

-.-.

Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.

bash.1: line 533 length 105
.if n ! case  coproc  do done elif else esac fi for function if in select then 
until while { } time [[ ]]

bash.1: line 534 length 166
.if t !    case    coproc    do    done    elif    else    esac    fi    for    
function    if    in    select    then    until    while    {    }    time    
[[    ]]

bash.1: line 556 length 90
[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] 
\fIcommand2\fP ... ]

bash.1: line 863 length 91
\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP 
; \fBdone\fP

bash.1: line 877 length 90
\fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; 
\fBdone\fP

bash.1: line 890 length 82
\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; 
\fBdone\fP

bash.1: line 3965 length 89
.if n alnum alpha ascii blank cntrl digit graph lower print punct space upper 
word xdigit

bash.1: line 3966 length 115
.if t alnum   alpha   ascii   blank   cntrl   digit   graph   lower   print   
punct   space   upper   word   xdigit

bash.1: line 6011 length 82
A string variable that "undoes" the effects of 
\fBactive\-region\-start\-color\fP 

bash.1: line 7814 length 114
\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP 
\fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]

bash.1: line 8108 length 159
\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] 
[\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP 
\fIwordlist\fP]

bash.1: line 8110 length 158
[\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP 
\fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP 
[\fIname ...\fP]

bash.1: line 8335 length 89
\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] 
[\fIname\fP]

bash.1: line 8662 length 83
\fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP 
...]

bash.1: line 9245 length 117
\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | 
\fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...

bash.1: line 9338 length 210
\fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP 
\fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] 
[\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]

bash.1: line 9341 length 212
\fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP 
\fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] 
[\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]

bash.1: line 9607 length 234
\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] 
[\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] 
[\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] 
[\fIname\fP ...]

bash.1: line 9813 length 110
\fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] 
[\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]

bash.1: line 9816 length 108
\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] 
[\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]

bash.1: line 11688 length 86
\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, 
IEEE --

-.-.

Split a punctuation from a single argument, if a two-font macro is meant

3790:.B LC_COLLATE.
11740:.B bash,

-.-.

End of a block is marked with a "\}" without a period in front of it.
That creates a space character, which forces "groff" to waste processing
time to remove.

11673:\}

-.-.

[ "test-groff" is a developmental version of "groff" ]

Input file is ./bash.1

Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z 
-rCHECKSTYLE=0":
troff: backtrace: file '<stdin>':377
troff:<stdin>:377: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':1377
troff:<stdin>:1377: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':1863
troff:<stdin>:1863: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2004
troff:<stdin>:2004: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2016
troff:<stdin>:2016: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2027
troff:<stdin>:2027: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2040
troff:<stdin>:2040: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2098
troff:<stdin>:2098: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2160
troff:<stdin>:2160: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2188
troff:<stdin>:2188: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2216
troff:<stdin>:2216: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2259
troff:<stdin>:2259: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2548
troff:<stdin>:2548: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2558
troff:<stdin>:2558: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':2568
troff:<stdin>:2568: warning: trailing space in the line
troff: backtrace: file '<stdin>':3409
troff:<stdin>:3409: warning: trailing space in the line
troff: backtrace: file '<stdin>':3746
troff:<stdin>:3746: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':3746
troff:<stdin>:3746: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':5333
troff:<stdin>:5333: warning: trailing space in the line
troff: backtrace: file '<stdin>':5421
troff:<stdin>:5421: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':5424
troff:<stdin>:5424: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':5853
troff:<stdin>:5853: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':5885
troff:<stdin>:5885: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':6008
troff:<stdin>:6008: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':6011
troff:<stdin>:6011: warning: trailing space in the line
troff: backtrace: file '<stdin>':6020
troff:<stdin>:6020: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':6104
troff:<stdin>:6104: warning: trailing space in the line
troff: backtrace: file '<stdin>':6137
troff:<stdin>:6137: warning: trailing space in the line
troff: backtrace: file '<stdin>':6138
troff:<stdin>:6138: warning: trailing space in the line
troff: backtrace: file '<stdin>':6139
troff:<stdin>:6139: warning: trailing space in the line
troff: backtrace: file '<stdin>':6141
troff:<stdin>:6141: warning: trailing space in the line
troff: backtrace: file '<stdin>':6200
troff:<stdin>:6200: warning: trailing space in the line
troff: backtrace: file '<stdin>':6265
troff:<stdin>:6265: warning: trailing space in the line
troff: backtrace: file '<stdin>':6697
troff:<stdin>:6697: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':7280
troff:<stdin>:7280: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':7908
troff:<stdin>:7908: warning: trailing space in the line
troff: backtrace: file '<stdin>':8417
troff:<stdin>:8417: warning: trailing space in the line
troff: backtrace: file '<stdin>':8506
troff:<stdin>:8506: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':8675
troff:<stdin>:8675: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':8704
troff:<stdin>:8704: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':8831
troff:<stdin>:8831: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':8876
troff:<stdin>:8876: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':8879
troff:<stdin>:8879: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':8882
troff:<stdin>:8882: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':8885
troff:<stdin>:8885: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':9437
troff:<stdin>:9437: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':9440
troff:<stdin>:9440: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':9449
troff:<stdin>:9449: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':9452
troff:<stdin>:9452: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':9979
troff:<stdin>:9979: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':10788
troff:<stdin>:10788: warning: trailing space in the line
troff: backtrace: file '<stdin>':11055
troff:<stdin>:11055: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':11065
troff:<stdin>:11065: warning: cannot select font 'CW'
troff: backtrace: file '<stdin>':11389
troff:<stdin>:11389: warning: trailing space in the line
troff: backtrace: file '<stdin>':11673
troff:<stdin>:11673: warning: trailing space in the line

-.-.

Additional:

  No ligature for the command word 'fi'

-- System Information:
Debian Release: trixie/sid
  APT prefers testing
  APT policy: (990, 'testing')
Architecture: amd64 (x86_64)

Kernel: Linux 6.4.13-1 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), 
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)

Versions of packages bash depends on:
ii  base-files   13
ii  debianutils  5.13
ii  libc6        2.37-10
ii  libtinfo6    6.4+20230625-2

Versions of packages bash recommends:
ii  bash-completion  1:2.11-8

Versions of packages bash suggests:
ii  bash-doc  5.2.15-2

-- no debconf information

chk_man.err.bash.1.60211.044903
Description: Text document