[PATCH 08/18] doc/bash.1: stop attempting literal ASCII " use

[G. Branden Robinson]

Migrate uses of the double quote (U+0022) as a literal to \(dq special
character escape sequence.  Generally these weren't _wrong_, but the man
page author then has to remember that they change their meaning when
they are placed inside macro arguments.

groff_man_style(7):
     ... Some escape sequences are however required for correct
     typesetting even in man pages and usually do not cause portability
     problems.

     \(dq   Basic Latin quotation mark (double quote).  Use in macro
            calls to prevent ‘"’ from being interpreted as beginning a
            quoted argument, or simply for readability.

                   .TP
                   .BI "split \(dq" text \(dq
---
 doc/bash.1 | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index f21aeb52..b666f63c 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -379,7 +379,7 @@ .SH INVOCATION
 .PP
 .RS
 .EX
-if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
+if [ \-n \(dq$BASH_ENV\(dq ]; then . \(dq$BASH_ENV\(dq; fi
 .EE
 .RE
 .PP
@@ -1159,7 +1159,7 @@ .SH QUOTING
 characters:
 .BR $ ,
 .BR \` ,
-\^\fB"\fP\^,
+\^\fB\(dq\fP\^,
 .BR \e ,
 or
 .BR <newline> .
@@ -1455,8 +1455,8 @@ .SS Special Parameters
 with each positional parameter separated by a space.
 When the
 expansion occurs within double quotes, each parameter expands to a
-separate word.  That is, "\fB$@\fP" is equivalent to
-"\fB$1\fP"\ "\fB$2\fP"\ .\|.\|.
+separate word.  That is, \(dq\fB$@\fP\(dq is equivalent to
+\(dq\fB$1\fP\(dq\ \(dq\fB$2\fP\(dq\ .\|.\|.
 If the double-quoted expansion occurs within a word, the expansion of
 the first parameter is joined with the beginning part of the original
 word, and the expansion of the last parameter is joined with the last
@@ -2567,7 +2567,7 @@ .SS Shell Variables
 Example:
 .RS
 .PP
-\fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":\(ti/shell\-mail?"$_ has 
mail!"\(aq
+\fBMAILPATH\fP=\(aq/var/mail/bfox?\(dqYou have 
mail\(dq:\(ti/shell\-mail?\(dq$_ has mail!\(dq\(aq
 .PP
 .B Bash
 can be configured to supply
@@ -3016,7 +3016,7 @@ .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
-"\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP",
+\(dq\fB$@\fP\(dq and \(dq\fB${\fP\fIname\fP\fB[@]}\fP\(dq,
 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
 as explained above (see
 .SM
@@ -3857,7 +3857,7 @@ .SS Word Splitting
 of
 .BR <space><tab><newline> .
 .PP
-Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained
+Explicit null arguments (\^\f3\(dq\^\(dq\fP or \^\f3\(aq\^\(aq\fP\^) are 
retained
 and passed to commands as empty strings.
 Unquoted implicit null arguments, resulting from the expansion of
 parameters that have no values, are removed.
@@ -4182,7 +4182,7 @@ .SS Quote Removal
 characters
 .BR \e ,
 .BR \(aq ,
-and \^\f3"\fP\^ that did not result from one of the above
+and \^\f3\(dq\fP\^ that did not result from one of the above
 expansions are removed.
 .SH REDIRECTION
 Before a command is executed, its input and output
@@ -6002,7 +6002,7 @@ .SS "Readline Key Bindings"
 .br
 Meta-Rubout: backward-kill-word
 .br
-Control-o: "> output"
+Control-o: \(dq> output\(dq
 .RE
 .LP
 In the above example,
@@ -6019,7 +6019,7 @@ .SS "Readline Key Bindings"
 .Q "> output"
 into the line).
 .PP
-In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
+In the second form, \fB\(dqkeyseq\(dq\fP:\^\fIfunction\-name\fP or \fImacro\fP,
 .B keyseq
 differs from
 .B keyname
@@ -6030,11 +6030,11 @@ .SS "Readline Key Bindings"
 are not recognized.
 .PP
 .RS
-"\eC\-u": universal\-argument
+\(dq\eC\-u\(dq: universal\-argument
 .br
-"\eC\-x\eC\-r": re\-read\-init\-file
+\(dq\eC\-x\eC\-r\(dq: re\-read\-init\-file
 .br
-"\ee[11\(ti": "Function Key 1"
+\(dq\ee[11\(ti\(dq: \(dqFunction Key 1\(dq
 .RE
 .PP
 In this example,
@@ -6065,8 +6065,8 @@ .SS "Readline Key Bindings"
 .B \e\e
 backslash
 .TP
-.B \e"
-literal "
+.B \e\(dq
+literal \(dq
 .TP
 .B \e\(aq
 literal \(aq
@@ -6117,7 +6117,7 @@ .SS "Readline Key Bindings"
 Unquoted text is assumed to be a function name.
 In the macro body, the backslash escapes described above are expanded.
 Backslash will quote any other character in the macro text,
-including " and \(aq.
+including \(dq and \(aq.
 .PP
 .B Bash
 allows the current readline key bindings to be displayed or modified
@@ -6583,7 +6583,7 @@ .SS "Readline Conditional Constructs"
 .nf
 \fB$if\fP Bash
 # Quote the current or previous word
-"\eC\-xq": "\eeb\e"\eef\e""
+\(dq\eC\-xq\(dq: \(dq\eeb\e\(dq\eef\e\(dq\(dq
 \fB$endif\fP
 .fi
 .RE
@@ -7469,7 +7469,7 @@ .SS Programmable Completion
 .nf
 _completion_loader()
 {
-  . "/etc/bash_completion.d/$1.sh" \c
+  . \(dq/etc/bash_completion.d/$1.sh\(dq \c
 .if \n(LL<80n \{\
 \e
 .br
@@ -8054,7 +8054,7 @@ .SH "SHELL BUILTIN COMMANDS"
 initialization file such as
 .IR .inputrc ,
 but each binding or command must be passed as a separate argument;
-e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'.
+e.g., '\(dq\eC\-x\eC\-r\(dq: re\-read\-init\-file'.
 In the following descriptions, output available to be re-read is formatted
 as commands that would appear in a
 .B readline
@@ -9151,7 +9151,7 @@ .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
-.Q "r=""fc \-s""" ,
+.Q "r=\(dqfc \-s\(dq" ,
 so that typing
 .Q "r cc"
 runs the last command beginning with
@@ -10835,7 +10835,7 @@ .SH "SHELL BUILTIN COMMANDS"
 \fBPathname Expansion\fP are enabled.
 .TP 8
 .B extquote
-If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is
+If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP\(dq\fIstring\fP\(dq quoting is
 performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
 enclosed in double quotes.  This option is enabled by default.
 .TP 8
-- 
2.30.2

signature.asc
Description: PGP signature