[PATCH 14/18] doc/bash.1: apply new `Q` quotation macro

[G. Branden Robinson]

Instead of variously using `this' and ``that'' quotation styles (mostly
the former), and which which render ugly on systems that hack up groff's
character mappings to force ` and ' to the grave accent (U+0060) and
neutral apostrophe (U+0027), respectively,[1] employ the new Q macro for
all (knock wood) quotation applications.

[1] For futher background (with a generous helping of opinion), see
<https://gitlab.com/procps-ng/procps/-/merge_requests/213/diffs?\
commit_id=a3ac4b667929320d4c8012435d63a9d1dd538a8d>.

Diff of rendering (groff):

-     reserved word if the next token begins with a ‘-’.  The TIMEFORMAT 
variable
+     reserved word if the next token begins with a “-”.  The TIMEFORMAT 
variable

-            character of the IFS special variable.  That is, "$*" is equivalent
-            to "$1c$2c...", where c is the first character of the value of the
+            character of the IFS special variable.  That is, “$*” is equivalent
+            to “$1c$2c...”, where c is the first character of the value of the

-            implicit ‘*’ is appended).  Each pattern is tested against the line
+            implicit “*” is appended).  Each pattern is tested against the line

-     comment-begin (‘‘#’’)
+     comment-begin (“#”)

-     isearch-terminators (‘‘C-[C-J’’)
+     isearch-terminators (“C-[C-J”)

[many more occurrences like these]

Diff of rendering (mandoc):

-       recognize time as a reserved word if the next token begins with a `-'.
+       recognize time as a reserved word if the next token begins with a “-”.

-       comment-begin (``#'')
+       comment-begin (“#”)

[many more occurrences like these]

Diff of rendering (Heirloom Doctools, DWB):

-       recognize time as a reserved word if the next token begins with a `-'.
+       recognize time as a reserved word if the next token begins with a "-".

-       comment-begin (``#'')
-              The string that is inserted when the readline insert-comment
-              command is executed.  This command is bound to M-# in emacs mode
-              and to # in vi command mode.
+       comment-begin (
+              "#") The string that is inserted when the readline
+              insert-comment command is executed.  This command is bound to
+              M-# in emacs mode and to # in vi command mode.

[many more occurrences like these]

That break is unfortunate.  It's a long story.
https://lists.gnu.org/archive/html/groff/2022-06/msg00026.html
---
 doc/bash.1 | 222 +++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 156 insertions(+), 66 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 3854d561..93855546 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -598,7 +598,8 @@ .SS Pipelines
 terminates.
 The \fB\-p\fP option changes the output format to that specified by POSIX.
 When the shell is in \fIposix mode\fP, it does not recognize
-\fBtime\fP as a reserved word if the next token begins with a `\-'.
+\fBtime\fP as a reserved word if the next token begins with a
+.Q \- .
 The
 .SM
 .B TIMEFORMAT
@@ -1430,8 +1431,13 @@ .SS Special Parameters
 with the value of each parameter separated by the first character of the
 .SM
 .B IFS
-special variable.  That is, "\fB$*\fP" is equivalent
-to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP.\|.\|.", where
+special variable.
+That is,
+.Q \fB$*\fP
+is equivalent
+to
+.Q \fB$1\fP\fIc\fP\fB$2\fP\fIc\fP.\|.\|. ,
+where
 .I c
 is the first character of the value of the
 .SM
@@ -2396,14 +2402,18 @@ .SS Shell Variables
 A colon-separated list of patterns used to decide which command lines
 should be saved on the history list.  Each pattern is anchored at the
 beginning of the line and must match the complete line (no implicit
-`\fB*\fP' is appended).  Each pattern is tested against the line
-after the checks specified by
+.Q \fB*\fP
+is appended).
+Each pattern is tested against the line after the checks specified by
 .SM
 .B HISTCONTROL
 are applied.
-In addition to the normal shell pattern matching characters, `\fB&\fP'
-matches the previous history line.  `\fB&\fP' may be escaped using a
-backslash; the backslash is removed before attempting a match.
+In addition to the normal shell pattern matching characters,
+.Q \fB&\fP
+matches the previous history line.
+.Q \fB&\fP
+may be escaped using a backslash;
+the backslash is removed before attempting a match.
 The second and subsequent lines of a multi-line compound command are
 not tested, and are added to the history regardless of the value of
 .SM
@@ -2566,7 +2576,8 @@ .SS Shell Variables
 .B MAILPATH
 A colon-separated list of filenames to be checked for mail.
 The message to be printed when mail arrives in a particular file
-may be specified by separating the filename from the message with a `?'.
+may be specified by separating the filename from the message with a
+.Q ? .
 When used in the text of the message, \fB$_\fP expands to the name of
 the current mailfile.
 Example:
@@ -2798,18 +2809,23 @@ .SS Shell Variables
 .B HISTORY EXPANSION
 below).  The first character is the \fIhistory expansion\fP character,
 the character which signals the start of a history
-expansion, normally `\fB!\fP'.
+expansion, normally
+.Q \fB!\fP .
 The second character is the \fIquick substitution\fP
 character, which is used as shorthand for re-running the previous
 command entered, substituting one string for another in the command,
 when it appears as the first character on the line.
-The default is `\fB\(ha\fP'.
-The optional third character is the character
-which indicates that the remainder of the line is a comment when found
-as the first character of a word, normally `\fB#\fP'.  The history
-comment character causes history substitution to be skipped for the
-remaining words on the line.  It does not necessarily cause the shell
-parser to treat the rest of the line as a comment.
+The default is
+.Q \fB\(ha\fP .
+The optional third character is the character which indicates that the
+remainder of the line is a comment when found as the first character of
+a word,
+normally
+.Q \fB#\fP .
+The history comment character causes history substitution to be skipped
+for the remaining words on the line.
+It does not necessarily cause the shell parser to treat the rest of the
+line as a comment.
 .PD
 .SS Arrays
 .B Bash
@@ -3023,7 +3039,9 @@ .SH EXPANSION
 can increase the number of words of the expansion; other expansions
 expand a single word to a single word.
 The only exceptions to this are the expansions of
-\(dq\fB$@\fP\(dq and \(dq\fB${\fP\fIname\fP\fB[@]}\fP\(dq,
+.B \(dq$@\(dq
+and
+.BR \(dq${\fIname\fP[@]}\(dq ,
 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
 as explained above (see
 .SM
@@ -3046,7 +3064,9 @@ .SS Brace Expansion
 .PP
 Brace expansions may be nested.  The results of each expanded
 string are not sorted; left to right order is preserved.
-For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'.
+For example,
+a\fB{\fPd,c,b\fB}\fPe expands into
+.Q "ade ace abe" .
 .PP
 A sequence expression takes the form
 \fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP,
@@ -3127,8 +3147,10 @@ .SS Brace Expansion
 .B SHELL BUILTIN COMMANDS
 below).
 .SS Tilde Expansion
-If a word begins with an unquoted tilde character (`\fB\(ti\fP'), all of
-the characters preceding the first unquoted slash (or all characters,
+If a word begins with an unquoted tilde character (\c
+.Q \fB\(ti\fP ),
+all of the characters preceding the first unquoted slash
+(or all characters,
 if there is no unquoted slash) are considered a \fItilde-prefix\fP.
 If none of the characters in the tilde-prefix are quoted, the
 characters in the tilde-prefix following the tilde are treated as a
@@ -3145,22 +3167,36 @@ .SS Tilde Expansion
 Otherwise, the tilde-prefix is replaced with the home directory
 associated with the specified login name.
 .PP
-If the tilde-prefix is a `\(ti+', the value of the shell variable
+If the tilde-prefix is a
+.Q \(ti+ ,
+the value of the shell variable
 .SM
 .B PWD
 replaces the tilde-prefix.
-If the tilde-prefix is a `\(ti\-', the value of the shell variable
+If the tilde-prefix is a
+.Q \(ti\- ,
+the value of the shell variable
 .SM
 .BR OLDPWD ,
 if it is set, is substituted.
 If the characters following the tilde in the tilde-prefix consist
 of a number \fIN\fP, optionally prefixed
-by a `+' or a `\-', the tilde-prefix is replaced with the corresponding
-element from the directory stack, as it would be displayed by the
+by a
+.Q +
+or a
+.Q \- ,
+the tilde-prefix is replaced with the corresponding element from the
+directory stack,
+as it would be displayed by the
 .B dirs
 builtin invoked with the tilde-prefix as an argument.
 If the characters following the tilde in the tilde-prefix consist of a
-number without a leading `+' or `\-', `+' is assumed.
+number without a leading
+.Q +
+or
+.Q \- ,
+.Q +
+is assumed.
 .PP
 If the login name is invalid, or the tilde expansion fails, the word
 is unchanged.
@@ -3189,14 +3225,17 @@ .SS Tilde Expansion
 \fBBash\fP does not do this, except for the \fIdeclaration\fP commands listed
 above, when in \fIposix mode\fP.
 .SS Parameter Expansion
-The `\fB$\fP' character introduces parameter expansion,
+The
+.Q \fB$\fP
+character introduces parameter expansion,
 command substitution, or arithmetic expansion.  The parameter name
 or symbol to be expanded may be enclosed in braces, which
 are optional but serve to protect the variable to be expanded from
 characters immediately following it which could be
 interpreted as part of the name.
 .PP
-When braces are used, the matching ending brace is the first `\fB}\fP'
+When braces are used, the matching ending brace is the first
+.Q \fB}\fP
 not escaped by a backslash or within a quoted string, and not within an
 embedded arithmetic expansion, command substitution, or parameter
 expansion.
@@ -5765,7 +5804,8 @@ .SH PROMPTING
 an ASCII escape character (033)
 .TP
 .B \eh
-the hostname up to the first `.'
+the hostname up to the first
+.Q .
 .TP
 .B \eH
 the hostname
@@ -6161,8 +6201,14 @@ .SS "Readline Variables"
 .B Off
 (without regard to case).
 Unrecognized variable names are ignored.
-When a variable value is read, empty or null values, "on" (case-insensitive),
-and "1" are equivalent to \fBOn\fP.  All other values are equivalent to
+When a variable value is read,
+empty or null values,
+.Q on
+(case-insensitive),
+and
+.Q 1
+are equivalent to \fBOn\fP.
+All other values are equivalent to
 \fBOff\fP.
 The variables and their default values are:
 .PP
@@ -6233,8 +6279,12 @@ .SS "Readline Variables"
 colors to indicate their file type.
 The color definitions are taken from the value of the \fBLS_COLORS\fP
 environment variable.
+.\" Tucking multiple macro calls into a paragraph tag requires some
+.\" finesse.  We require `\c`, and while the single-font macros don't
+.\" honor input trap continuation, the font alternation macros do.
 .TP
-.B comment\-begin (``#'')
+.BR comment\-begin\ ( \c
+.Q \fB#\fP )
 The string that is inserted when the readline
 .B insert\-comment
 command is executed.
@@ -6385,7 +6435,8 @@ .SS "Readline Variables"
 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
 may change if the locale is changed.
 .TP
-.B isearch\-terminators (``C\-[C\-J'')
+.BR isearch\-terminators\ ( \c
+.Q \fBC\-[C\-J\fP )
 The string of characters that should terminate an incremental
 search without subsequently executing the character as a command.
 If this variable has not been given a value, the characters
@@ -6431,10 +6482,14 @@ .SS "Readline Variables"
 .TP
 .B match\-hidden\-files (On)
 This variable, when set to \fBOn\fP, causes readline to match files whose
-names begin with a `.' (hidden files) when performing filename
-completion.
-If set to \fBOff\fP, the leading `.' must be
-supplied by the user in the filename to be completed.
+names begin with a
+.Q .
+(hidden files)
+when performing filename completion.
+If set to \fBOff\fP,
+the leading
+.Q .
+must be supplied by the user in the filename to be completed.
 .TP
 .B menu\-complete\-display\-prefix (Off)
 If set to \fBOn\fP, menu completion displays the common prefix of the
@@ -6772,12 +6827,16 @@ .SS Commands for Manipulating the History
 Without an argument, move back to the first entry in the history list.
 .TP
 .B reverse\-search\-history (C\-r)
-Search backward starting at the current line and moving `up' through
-the history as necessary.  This is an incremental search.
+Search backward starting at the current line and moving
+.Q up
+through the history as necessary.
+This is an incremental search.
 .TP
 .B forward\-search\-history (C\-s)
-Search forward starting at the current line and moving `down' through
-the history as necessary.  This is an incremental search.
+Search forward starting at the current line and moving
+.Q down
+through the history as necessary.
+This is an incremental search.
 .TP
 .B non\-incremental\-reverse\-search\-history (M\-p)
 Search backward through the history starting at the current line
@@ -7762,7 +7821,9 @@ .SS Event Designators
 .IR n .
 .TP
 .B !!
-Refer to the previous command.  This is a synonym for `!\-1'.
+Refer to the previous command.
+This is a synonym for
+.Q !\-1 .
 .TP
 .B !\fIstring\fR
 Refer to the most recent command preceding the current position in the
@@ -7824,15 +7885,22 @@ .SS Word Designators
 zeroth word if there is only one word in the line.
 .TP
 .B %
-The first word matched by the most recent `?\fIstring\fR?' search,
+The first word matched by the most recent
+.Q ?\fIstring\fR?
+search,
 if the search string begins with a character that is part of a word.
 .TP
 .I x\fB\-\fPy
-A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
+A range of words;
+.Q \-\fIy\fR
+abbreviates
+.Q 0\-\fIy\fR .
 .TP
 .B *
-All of the words but the zeroth.  This is a synonym
-for `\fI1\-$\fP'.  It is not an error to use
+All of the words but the zeroth.
+This is a synonym for
+.Q \fI1\-$\fP .
+It is not an error to use
 .B *
 if there is just one
 word in the event; the empty string is returned in that case.
@@ -7849,7 +7917,8 @@ .SS Word Designators
 previous command is used as the event.
 .SS Modifiers
 After the optional word designator, there may appear a sequence of
-one or more of the following modifiers, each preceded by a `:'.
+one or more of the following modifiers, each preceded by a
+.Q : .
 These modify, or edit, the word or words selected from the history event.
 .PP
 .PD 0
@@ -7921,16 +7990,25 @@ .SS Modifiers
 .TP
 .B g
 Cause changes to be applied over the entire event line.  This is
-used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
-or `\fB:&\fP'.  If used with
-`\fB:s\fP', any delimiter can be used
-in place of /, and the final delimiter is optional
-if it is the last character of the event line.
+used in conjunction with
+.Q \fB:s\fP
+(e.g.,
+.Q \fB:gs/\fIold\fP/\fInew\fP/\fR )
+or
+.Q \fB:&\fP .
+If used with
+.Q \fB:s\fP ,
+any delimiter can be used in place of /,
+and the final delimiter is optional if it is the last character of the
+event line.
 An \fBa\fP may be used as a synonym for \fBg\fP.
 .TP
 .B G
-Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word
-in the event line.
+Apply the following
+.Q \fBs\fP
+or
+.Q \fB&\fP
+modifier once to each word in the event line.
 .PD
 .SH "SHELL BUILTIN COMMANDS"
 .\" start of bash_builtins
@@ -8766,7 +8844,10 @@ .SH "SHELL BUILTIN COMMANDS"
 Mark \fIname\fPs for export to subsequent commands via the environment.
 .PD
 .PP
-Using `+' instead of `\-'
+Using
+.Q +
+instead of
+.Q \-
 turns off the attribute instead,
 with the exceptions that \fB+a\fP and \fB+A\fP
 may not be used to destroy array variables and \fB+r\fP will not
@@ -10456,12 +10537,17 @@ .SH "SHELL BUILTIN COMMANDS"
 Exit after reading and executing one command.
 .TP 8
 .B \-u
-Treat unset variables and parameters other than the special
-parameters "@" and "*",
-or array variables subscripted with "@" or "*",
-as an error when performing
-parameter expansion.  If expansion is attempted on an
-unset variable or parameter, the shell prints an error message, and,
+Treat unset variables and parameters other than the special parameters
+.Q @
+and
+.Q * ,
+or array variables subscripted with
+.Q @
+or
+.Q * ,
+as an error when performing parameter expansion.
+If expansion is attempted on an unset variable or parameter,
+the shell prints an error message, and,
 if not interactive, exits with a non-zero status.
 .TP 8
 .B \-v
@@ -12164,9 +12250,10 @@ .SH BUG REPORTS
 .I bashbug
 command to submit a bug report.
 If you have a fix, you are encouraged to mail that as well!
-Suggestions and `philosophical' bug reports may be mailed
-to \fIbug-bash@gnu.org\fP or posted to the Usenet
-newsgroup
+Suggestions and
+.Q philosophical
+bug reports may be mailed to \fIbug-bash@gnu.org\fP or posted to the
+Usenet newsgroup
 .BR gnu.bash.bug .
 .PP
 ALL bug reports should include:
@@ -12181,7 +12268,9 @@ .SH BUG REPORTS
 .TP
 A description of the bug behaviour
 .TP
-A short script or `recipe' which exercises the bug
+A short script or \c
+.Q recipe " \c"
+which exercises the bug
 .PD
 .PP
 .I bashbug
@@ -12207,7 +12296,8 @@ .SH BUGS
 .PP
 Shell builtin commands and functions are not stoppable/restartable.
 .PP
-Compound commands and command sequences of the form `a ; b ; c'
+Compound commands and command sequences of the form
+.Q "a ; b ; c"
 are not handled gracefully when process suspension is attempted.
 When a process is stopped, the shell immediately executes the next
 command in the sequence.
-- 
2.30.2

signature.asc
Description: PGP signature