[groff] 11/24: [docs]: Add advice about " usage in string defs.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit dcbe3c996cfa8d6e91849580149a79bad147b1fd
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Dec 25 16:32:40 2022 -0600

    [docs]: Add advice about " usage in string defs.
    
    Also update and condense examples of this point.
---
 doc/groff.texi  | 8 +++++---
 man/groff.7.man | 8 ++++++++
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 336531ae5..4ed946cb6 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -12173,7 +12173,10 @@ document maintenance.
 @cindex spaces with @code{ds}
 @cindex @code{ds} request, and leading spaces
 An initial neutral double quote @code{"} in @var{contents} is stripped
-to allow embedding of leading spaces.
+to allow embedding of leading spaces.  Any other @code{"} is interpreted
+literally, but it is wise to use the special character escape sequence
+@code{\[dq]} instead if the string might be interpolated as part of a
+macro argument; see @ref{Calling Macros}.
 
 @c Examples should be more accessible than Unix nerd stuff like this,
 @c but in general document authors shouldn't want to use "straight"
@@ -12181,8 +12184,7 @@ to allow embedding of leading spaces.
 @c as these examples can get and not overrun the right margin in PDF.
 @Example
 .ds salutation "         Yours in a white wine sauce,\"
-.ds c-var-defn "    char build_date[]="2020-07-29";\"
-.ds sucmd sudo sh -c "fdisk -l /dev/sda > partitions"\"
+.ds c-var-defn "  char mydate[]=\[dq]2020-07-29\[dq];\"
 @endExample
 
 @cindex multi-line strings
diff --git a/man/groff.7.man b/man/groff.7.man
index 731aa4de7..d22702444 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5165,6 +5165,14 @@ An initial neutral double quote
 .B \[dq]
 in the string contents is stripped to allow embedding of leading spaces.
 .
+Any other
+.B \[dq]
+is interpreted literally,
+but it is wise to use the special character escape sequence
+.B \[rs][dq]
+instead if the string might be interpolated as part of a macro argument;
+see section \[lq]Calling macros\[rq] above.
+.
 Strings are not limited to a single input line of text.
 .BI \[rs] newline
 works just as it does elsewhere.