...instead of assuming the availability of a font named `CW`, and using inconsistent quotation conventions when rendering to terminals with nroff(1).
This resolves 25 instances of the following warning from groff 1.23.0.
troff:./doc/bash.1:360: warning: cannot select font 'CW'
To extract the most salient points from a lengthy discussion on Perl's
GitHub site[1]:
1. "CW" is not a portable font name.
2. There is no portable way to ask troff whether a font is available.
Further, and this is more a matter of taste and opinion, some
typographical authorities deprecate changes of font family in running
text. (This is similar to typographers' and technical writers' advice
not to change the typeface often, for instance with frequent use of
italics and, especially, bold. But this latter horse is probably locked
_out_ of the barn for man pages.) Contrast with use of different font
families for "displays", that is, text that is set off by vertical
separation (and often indentation) from its surroundings.
With a macro, it is more straightforward to tackle another portability
problem: the availability of special character escape sequences for
doubled typographer's quotes. groff has supported these for 30+ years;
and mandoc and Heirloom Doctools do as well. But they are not portable
to System V or DWB troff, let alone the Seventh Edition Unix troff that
BSD employed until replacing it with groff in the early 1990s.
Therefore, define a quotation macro as follows:
A. Bracket the first argument with `lq` and `rq` special character
escape sequences if the formatter is groff;
B. ...with `` and '' on a non-groff troff typesetter;
C. ...with " and " on a non-groff nroff program.
D. Accept a second argument for abutting, trailing punctuation,
similarly to man(7)'s font alternation macros (and groff's `ME`,
`UE`, and `MR` extensions).
Furthermore:
E. Drop font style changes, no longer necessary to mark the text now
that quotation is reliable.
F. Use dummy character escape sequence \& after quoted, word-ending
dots to avoid erroneous insertion of inter-sentence space.[2] (See
particularly bash(1)'s subsection "Pathname Expansion".)
G. Fix outright missing closing quotation in description of "enable"
built-in.
mandoc maintainer Ingo Schwarze gravely warns man page authors against
defining macros, but (1) mandoc _does_ support them if they're not too
complex, like this [I tested]; (2) he'd rather that any given man page
be written in mdoc(7) instead, a heavy lift for a document of bash(1)'s
mass even if such were desired by its maintainer and/or user community;
(3) at some point, portability demands of legacy systems militate for
such things (and all legacy troffs are considerably more flexible than
mandoc(1)); and (4) an alternative approach, perhaps using autoconf(1)
to check the host's troff(1), nroff(1), and man(7) for features and
constructing a man page at build time using soelim(1), is conceivable,
and I'm willing to assist with that if it sounds promising.
Exhibits of visible change (UTF-8, which groff and mandoc produce,
follows):
- ement (the one with the highest index) is "main". This variable
ex‐
+ ement (the one with the highest index) is “main”. This variable
ex‐
- will write the trace output generated when set -x is enabled to
that
+ will write the trace output generated when “set -x” is enabled to
- mand. The default value is ‘‘<space><tab><newline>’’.
+ mand. The default value is “<space><tab><newline>”.
- ‘‘.’’ at the start of a name or immediately following a slash must be
+ “.” at the start of a name or immediately following a slash must be
matched
[The foregoing item was rendered with left adjustment; observe that the
quoted dot is no longer treated as ending a sentence.]
- name, as if the command were ‘‘enable -f name name . The return
+ name, as if the command were “enable -f name name”. The return
[1] https://github.com/Perl/perl5/issues/21239
[2] https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html
---
doc/bash.1 | 234 ++++++++++++++++++++++++++++++-----------------------
1 file changed, 131 insertions(+), 103 deletions(-)
diff --git a/doc/bash.1 b/doc/bash.1
index ed67e4b0..b1257639 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -43,7 +43,15 @@
.\" but Sun doesn't seem to like that very much.
.\"
.de FN
-\fI\|\\$1\|\fP
+\%\fI\|\\$1\|\fP
+..
+.\" quotation macro
+.de Q
+.ie \n(.g \(lq\\$1\(rq\\$2
+.el \{
+. if t ``\\$1''\\$2
+. if n "\\$1"\\$2
+.\}
..
.SH NAME
bash \- GNU Bourne-Again SHell
@@ -1868,8 +1876,7 @@ .SS Shell Variables
The element with index 0 is the name of any currently-executing
shell function.
The bottom-most element (the one with the highest index) is
-.if t \f(CW"main"\fP.
-.if n "main".
+.Q main .
This variable exists only when a shell function is executing.
Assignments to
.SM
@@ -2009,8 +2016,7 @@ .SS Shell Variables
.TP
.B READLINE_ARGUMENT
Any numeric argument given to a readline command that was defined using
-.if t \f(CWbind \-x\fP
-.if n "bind \-x"
+.Q "bind \-x"
(see
.SM
.B "SHELL BUILTIN COMMANDS"
@@ -2021,8 +2027,7 @@ .SS Shell Variables
The contents of the
.B readline
line buffer, for use with
-.if t \f(CWbind \-x\fP
-.if n "bind \-x"
+.Q "bind \-x"
(see
.SM
.B "SHELL BUILTIN COMMANDS"
@@ -2032,8 +2037,7 @@ .SS Shell Variables
The position of the mark (saved insertion point) in the
.B readline
line buffer, for use with
-.if t \f(CWbind \-x\fP
-.if n "bind \-x"
+.Q "bind \-x"
(see
.SM
.B "SHELL BUILTIN COMMANDS"
@@ -2045,8 +2049,7 @@ .SS Shell Variables
The position of the insertion point in the
.B readline
line buffer, for use with
-.if t \f(CWbind \-x\fP
-.if n "bind \-x"
+.Q "bind \-x"
(see
.SM
.B "SHELL BUILTIN COMMANDS"
@@ -2165,8 +2168,7 @@ .SS Shell Variables
.B BASH_XTRACEFD
If set to an integer corresponding to a valid file descriptor, \fBbash\fP
will write the trace output generated when
-.if t \f(CWset \-x\fP
-.if n \fIset \-x\fP
+.Q "set \-x"
is enabled to that file descriptor.
The file descriptor is closed when
.SM
@@ -2193,8 +2195,7 @@ .SS Shell Variables
.B cd
command.
A sample value is
-.if t \f(CW".:\(ti:/usr"\fP.
-.if n ".:\(ti:/usr".
+.Q .:\(ti:/usr .
.TP
.B CHILD_MAX
Set the number of exited child status values for the shell to remember.
@@ -2436,7 +2437,7 @@ .SS Shell Variables
split lines into words with the
.B read
builtin command. The default value is
-``<space><tab><newline>''.
+.Q <space><tab><newline> .
.TP
.B IGNOREEOF
Controls the
@@ -2581,8 +2582,7 @@ .SS Shell Variables
.BR bash .
A common value is
.na
-.if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP.
-.if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''.
+.Q /usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin .
.ad
.TP
.B POSIXLY_CORRECT
@@ -2624,14 +2624,14 @@ .SS Shell Variables
.SM
.B PROMPTING
below) and used as the primary prompt string. The default value is
-``\fB\es\-\ev\e$ \fP''.
+.Q "\es\-\ev\e$ " .
.TP
.B PS2
The value of this parameter is expanded as with
.SM
.B PS1
and used as the secondary prompt string. The default is
-``\fB> \fP''.
+.Q "> " .
.TP
.B PS3
The value of this parameter is used as the prompt for the
@@ -2652,7 +2652,8 @@ .SS Shell Variables
.SM
.B PS4
is replicated multiple times, as necessary, to indicate multiple
-levels of indirection. The default is ``\fB+ \fP''.
+levels of indirection. The default is
+.Q "+ " .
.TP
.B SHELL
This variable expands to the full pathname to the shell.
@@ -3375,8 +3376,11 @@ .SS Parameter Expansion
.IR parameter ,
then the result of the expansion is the expanded value of
.I parameter
-with the shortest matching pattern (the ``\fB#\fP'' case) or the
-longest matching pattern (the ``\fB##\fP'' case) deleted.
+with the shortest matching pattern (the
+.Q #
+case) or the longest matching pattern (the
+.Q ##
+case) deleted.
If
.I parameter
is
@@ -3410,8 +3414,11 @@ .SS Parameter Expansion
.IR parameter ,
then the result of the expansion is the expanded value of
.I parameter
-with the shortest matching pattern (the ``\fB%\fP'' case) or the
-longest matching pattern (the ``\fB%%\fP'' case) deleted.
+with the shortest matching pattern (the
+.Q %
+case) or the longest matching pattern (the
+.Q %%
+case) deleted.
If
.I parameter
is
@@ -3832,7 +3839,10 @@ .SS Word Splitting
When a quoted null argument appears as part of a word whose expansion is
non-null, the null argument is removed.
That is, the word
-\f(CW\-d\(aq\^\(aq\fP becomes \f(CW\-d\fP after word splitting and
+.Q "\-d\(aq\^\(aq"
+becomes
+.Q \-d
+after word splitting and
null argument removal.
.PP
Note that if no expansion occurs, no splitting
@@ -3875,29 +3885,32 @@ .SS Pathname Expansion
of alphabetic characters.
When a pattern is used for pathname expansion,
the character
-.B ``.''
+.Q .\&
at the start of a name or immediately following a slash
must be matched explicitly, unless the shell option
.B dotglob
is set.
In order to match the filenames
-.B ``.''
+.Q .\&
and
-.BR ``..'' ,
-the pattern must begin with ``.'' (for example, ``.?''),
+.Q ..\& ,
+the pattern must begin with
+.Q .\&
+(for example,
+.Q .?\& ),
even if
.B dotglob
is set.
If the
.B globskipdots
shell option is enabled, the filenames
-.B ``.''
+.Q .\&
and
-.BR ``..''
+.Q ..\&
are never matched, even if the pattern begins with a
-.BR ``.'' .
+.Q .\& .
When not matching pathnames, the
-.B ``.''
+.Q .\&
character is not treated specially.
When matching a pathname, the slash character must always be
matched explicitly by a slash in the pattern, but in other matching
@@ -3936,9 +3949,9 @@ .SS Pathname Expansion
.B GLOBIGNORE
is performed without regard to case.
The filenames
-.B ``.''
+.Q .\&
and
-.B ``..''
+.Q ..\&
are always ignored when
.SM
.B GLOBIGNORE
@@ -3948,12 +3961,12 @@ .SS Pathname Expansion
to a non-null value has the effect of enabling the
.B dotglob
shell option, so all other filenames beginning with a
-.B ``.''
+.Q .\&
will match.
To get the old behavior of ignoring filenames beginning with a
-.BR ``.'' ,
+.Q .\& ,
make
-.B ``.*''
+.Q .*
one of the patterns in
.SM
.BR GLOBIGNORE .
@@ -4117,12 +4130,21 @@ .SS Pathname Expansion
When matching filenames, the \fBdotglob\fP shell option determines
the set of filenames that are tested:
when \fBdotglob\fP is enabled, the set of filenames includes all files
-beginning with ``.'', but ``.'' and ``..'' must be matched by a
-pattern or sub-pattern that begins with a dot;
+beginning with
+.Q .\& ,
+but
+.Q .\&
+and
+.Q ..\&
+must be matched by a pattern or sub-pattern that begins with a dot;
when it is disabled, the set does not
-include any filenames beginning with ``.'' unless the pattern
-or sub-pattern begins with a ``.''.
-As above, ``.'' only has a special meaning when matching filenames.
+include any filenames beginning with
+.Q .\&
+unless the pattern or sub-pattern begins with a
+.Q .\&
+As above,
+.Q .\&
+only has a special meaning when matching filenames.
.PP
Complicated extended pattern matching against long strings is slow,
especially when the patterns contain alternations and the strings
@@ -4913,7 +4935,9 @@ .SH "CONDITIONAL EXPRESSIONS"
True if \fIfile\fP exists and is a symbolic link.
.TP
.B \-k \fIfile\fP
-True if \fIfile\fP exists and its ``sticky'' bit is set.
+True if \fIfile\fP exists and its
+.Q sticky
+bit is set.
.TP
.B \-p \fIfile\fP
True if \fIfile\fP exists and is a named pipe (FIFO).
@@ -5519,10 +5543,12 @@ .SH "JOB CONTROL"
processes are those whose process group ID differs from the terminal's;
such processes are immune to keyboard-generated signals.
Only foreground processes are allowed to read from or, if the
-user so specifies with \f(CWstty tostop\fP, write to the
-terminal.
+user so specifies with
+.Q "stty tostop" ,
+write to the terminal.
Background processes which attempt to read from (write to when
-\f(CWstty tostop\fP is in effect) the
+.Q "stty tostop"
+is in effect) the
terminal are sent a
.SM
.B SIGTTIN (SIGTTOU)
@@ -5610,12 +5636,12 @@ .SH "JOB CONTROL"
foreground:
.B %1
is a synonym for
-\fB``fg %1''\fP,
+.Q "fg %1" ,
bringing job 1 from the background into the foreground.
Similarly,
-.B ``%1 &''
+.Q "%1 &"
resumes job 1 in the background, equivalent to
-\fB``bg %1''\fP.
+.Q "bg %1" .
.PP
The shell learns immediately whenever a job changes state.
Normally,
@@ -5951,8 +5977,7 @@ .SS "Readline Key Bindings"
.I C\-o
is bound to run the macro
expressed on the right hand side (that is, to insert the text
-.if t \f(CW> output\fP
-.if n ``> output''
+.Q "> output"
into the line).
.PP
In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
@@ -5983,8 +6008,7 @@ .SS "Readline Key Bindings"
and
.I "ESC [ 1 1 \(ti"
is bound to insert the text
-.if t \f(CWFunction Key 1\fP.
-.if n ``Function Key 1''.
+.Q "Function Key 1" .
.PP
The full set of GNU Emacs style escape sequences is
.RS
@@ -6106,7 +6130,8 @@ .SS "Readline Variables"
This variable is reset to the default value whenever the terminal type changes.
The default value is the string that puts the terminal in standout mode,
as obtained from the terminal's terminfo description.
-A sample value might be \f(CW"\ee[01;33m"\fP.
+A sample value might be
+.Q "\ee[01;33m" .
.TP
.B active\-region\-end\-color
A string variable that "undoes" the effects of
\fBactive\-region\-start\-color\fP
@@ -6118,7 +6143,8 @@ .SS "Readline Variables"
This variable is reset to the default value whenever the terminal type changes.
The default value is the string that restores the terminal from standout mode,
as obtained from the terminal's terminfo description.
-A sample value might be \f(CW"\ee[0m"\fP.
+A sample value might be
+.Q "\ee[0m" .
.TP
.B bell\-style (audible)
Controls what happens when readline wants to ring the terminal bell.
@@ -6132,7 +6158,9 @@ .SS "Readline Variables"
treated specially by the kernel's terminal driver to their
readline equivalents.
These override the default readline bindings described here.
-Type \f(CWstty \-a\fP at a bash prompt to see your current terminal settings,
+Type
+.Q "stty \-a"
+at a bash prompt to see your current terminal settings,
including the special control characters (usually \fBcchars\fP).
.TP
.B blink\-matching\-paren (Off)
@@ -7687,7 +7715,7 @@ .SS Event Designators
with
.IR string2 .
Equivalent to
-``!!:s\d\s+2\(ha\s-2\u\fIstring1\fP\d\s+2\(ha\s-2\u\fIstring2\fP\d\s+2\(ha\s-2\u''
+.Q
!!:s\d\s+2\(ha\s-2\u\fIstring1\fP\d\s+2\(ha\s-2\u\fIstring2\fP\d\s+2\(ha\s-2\u
(see \fBModifiers\fP below).
.TP
.B !#
@@ -8138,7 +8166,9 @@ .SH "SHELL BUILTIN COMMANDS"
are separated by a colon (:). A null directory name in
.SM
.B CDPATH
-is the same as the current directory, i.e., ``\fB.\fP''. If
+is the same as the current directory, i.e.,
+.Q .\& .
+If
.I dir
begins with a slash (/),
then
@@ -8279,10 +8309,14 @@ .SH "SHELL BUILTIN COMMANDS"
each \fIname\fP, or, if no \fIname\fPs are supplied, all
completion specifications.
The \fB\-D\fP option indicates that other supplied options and actions should
-apply to the ``default'' command completion; that is, completion attempted
+apply to the
+.Q default
+command completion; that is, completion attempted
on a command for which no completion has previously been defined.
The \fB\-E\fP option indicates that other supplied options and actions should
-apply to ``empty'' command completion; that is, completion attempted on a
+apply to
+.Q empty
+command completion; that is, completion attempted on a
blank line.
The \fB\-I\fP option indicates that other supplied options and actions should
apply to completion on the initial non-assignment word on the line, or after
@@ -8512,10 +8546,14 @@ .SH "SHELL BUILTIN COMMANDS"
The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
builtin described above.
The \fB\-D\fP option indicates that other supplied options should
-apply to the ``default'' command completion; that is, completion attempted
+apply to the
+.Q default
+command completion; that is, completion attempted
on a command for which no completion has previously been defined.
The \fB\-E\fP option indicates that other supplied options should
-apply to ``empty'' command completion; that is, completion attempted on a
+apply to
+.Q empty
+command completion; that is, completion attempted on a
blank line.
The \fB\-I\fP option indicates that other supplied options should
apply to completion on the initial non-assignment word on the line,
@@ -8541,7 +8579,9 @@ .SH "SHELL BUILTIN COMMANDS"
must be \(>= 1. If
.I n
is greater than the number of enclosing loops, the last enclosing loop
-(the ``top-level'' loop) is resumed.
+(the
+.Q top-level
+loop) is resumed.
The return value is 0 unless \fIn\fP is not greater than or equal to 1.
.TP
\fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP]
...]
@@ -8673,8 +8713,7 @@ .SH "SHELL BUILTIN COMMANDS"
subsequent assignments.
The return value is 0 unless an invalid option is encountered,
an attempt is made to define a function using
-.if n ``\-f foo=bar'',
-.if t \f(CW\-f foo=bar\fP,
+.Q "\-f foo=bar" ,
an attempt is made to assign a value to a readonly variable,
an attempt is made to assign a value to an array variable without
using the compound assignment syntax (see
@@ -8844,8 +8883,7 @@ .SH "SHELL BUILTIN COMMANDS"
.SM
.B PATH
instead of the shell builtin version, run
-.if t \f(CWenable \-n test\fP.
-.if n ``enable \-n test''.
+.Q "enable \-n test" .
The
.B \-f
option means to load the new builtin command
@@ -8875,8 +8913,7 @@ .SH "SHELL BUILTIN COMMANDS"
If no options are supplied and a \fIname\fP is not a shell builtin,
\fBenable\fP will attempt to load \fIname\fP from a shared object named
\fIname\fP, as if the command were
-.if t \f(CWenable \-f\fP \fIname name\fP .
-.if n ``enable \-f \fIname name\fP .
+.Q "enable \-f \fI name name\fP" .
The return value is 0 unless a
.I name
is not a shell builtin or there is an error loading a new builtin
@@ -9004,8 +9041,7 @@ .SH "SHELL BUILTIN COMMANDS"
.I last
is not specified, it is set to
the current command for listing (so that
-.if n ``fc \-l \-10''
-.if t \f(CWfc \-l \-10\fP
+.Q "fc \-l \-10"
prints the last 10 commands) and to
.I first
otherwise.
@@ -9049,17 +9085,13 @@ .SH "SHELL BUILTIN COMMANDS"
of \fIpat\fP is replaced by \fIrep\fP.
\fICommand\fP is interpreted the same as \fIfirst\fP above.
A useful alias to use with this is
-.if n ``r="fc \-s"'',
-.if t \f(CWr='fc \-s'\fP,
+.Q "r=""fc \-s""" ,
so that typing
-.if n ``r cc''
-.if t \f(CWr cc\fP
+.Q "r cc"
runs the last command beginning with
-.if n ``cc''
-.if t \f(CWcc\fP
+.Q cc
and typing
-.if n ``r''
-.if t \f(CWr\fP
+.Q r
re-executes the last command.
.IP
If the first form is used, the return value is 0 unless an invalid
@@ -9329,7 +9361,9 @@ .SH "SHELL BUILTIN COMMANDS"
are interpreted as described above.
.TP
.B \-a
-Append the ``new'' history lines to the history file.
+Append the
+.Q new
+history lines to the history file.
These are history lines entered since the beginning of the current
\fBbash\fP session, but not already appended to the history file.
.TP
@@ -9624,11 +9658,9 @@ .SH "SHELL BUILTIN COMMANDS"
.BR dirs ,
starting with zero, from the stack.
For example:
-.if n ``popd +0''
-.if t \f(CWpopd +0\fP
+.Q "popd +0"
removes the first directory,
-.if n ``popd +1''
-.if t \f(CWpopd +1\fP
+.Q "popd +1"
the second.
.TP
\fB\-\fP\fIn\fP
@@ -9636,11 +9668,9 @@ .SH "SHELL BUILTIN COMMANDS"
shown by
.BR dirs ,
starting with zero. For example:
-.if n ``popd \-0''
-.if t \f(CWpopd \-0\fP
+.Q "popd \-0"
removes the last directory,
-.if n ``popd \-1''
-.if t \f(CWpopd \-1\fP
+.Q "popd \-1"
the next to last.
.PD
.PP
@@ -10205,8 +10235,7 @@ .SH "SHELL BUILTIN COMMANDS"
.TP 8
.B ignoreeof
The effect is as if the shell command
-.if t \f(CWIGNOREEOF=10\fP
-.if n ``IGNOREEOF=10''
+.Q IGNOREEOF=10
had been executed
(see
.B Shell Variables
@@ -10651,9 +10680,9 @@ .SH "SHELL BUILTIN COMMANDS"
includes filenames beginning with a `.' in the results of pathname
expansion.
The filenames
-.B ``.''
+.Q .\&
and
-.B ``..''
+.Q ..\&
must always be matched explicitly, even if
.B dotglob
is set.
@@ -10770,11 +10799,11 @@ .SH "SHELL BUILTIN COMMANDS"
.TP 8
.B globskipdots
If set, pathname expansion will never match the filenames
-.B ``.''
+.Q .\&
and
-.BR ``..'' ,
+.Q ..\& ,
even if the pattern begins with a
-.BR ``.'' .
+.Q .\& .
This option is enabled by default.
.TP 8
.B globstar
@@ -10873,8 +10902,9 @@ .SH "SHELL BUILTIN COMMANDS"
.TP 8
.B mailwarn
If set, and a file that \fBbash\fP is checking for mail has been
-accessed since the last time it was checked, the message ``The mail in
-\fImailfile\fP has been read'' is displayed.
+accessed since the last time it was checked, the message
+.Q "The mail in \fImailfile\fP has been read"
+is displayed.
.TP 8
.B no_empty_cmd_completion
If set, and
@@ -11309,8 +11339,7 @@ .SH "SHELL BUILTIN COMMANDS"
.I name
were specified as a command name,
or nothing if
-.if t \f(CWtype \-t name\fP
-.if n ``type \-t name''
+.Q "type \-t name"
would not return
.IR file .
The
@@ -11319,8 +11348,7 @@ .SH "SHELL BUILTIN COMMANDS"
.SM
.B PATH
search for each \fIname\fP, even if
-.if t \f(CWtype \-t name\fP
-.if n ``type \-t name''
+.Q "type \-t name"
would not return
.IR file .
If a command is hashed,
--
2.30.2
signature.asc
Description: PGP signature
