Subject: Re: bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals)

From: Sebastian Urban <[email-masked]>
Date: Thu, 13 May 2021 13:48:12 +0200

>>> I understand item 1, but not item 2. Why would we want to change
 >>> @samp to @kbd? Likewise in other parts, where you suggest to
 >>> change @t to @kbd. @kbd is for something the user types; using it
 >>> for quotes in context other than typing input is wrong.
 >>
 >> Before I answer, I have to ask: do we want extra (curved) quotes
 >> around examples showing quotes, both ASCII and curved? Because I
 >> have doubts which way is correct...
 >
 > I think we should use what's logical, even if it looks awkward on
 > some platforms. So if it's something the user types, then it should
 > be @kbd, and if not, it shouldn't be.
 >
 > Can you respin the patch without those changes?

Diff file attached.

NOTE! I was using:
- TEXINFO.TEX version 2020-06-25.17;
- TEXI (source) files from emacs-27.2(.tar.xz) release.

--
S. U.
diff -u old/doc/emacs/basic.texi new/doc/emacs/basic.texi
--- old/doc/emacs/basic.texi	2021-01-28 18:52:37.000000000 +0100
+++ new/doc/emacs/basic.texi	2021-05-13 11:51:52.437286100 +0200
@@ -112,10 +112,10 @@
 @cindex curly quotes, inserting
 @cindex curved quotes, inserting
   A few common Unicode characters can be inserted via a command
-starting with @kbd{C-x 8}.  For example, @kbd{C-x 8 [} inserts @t{‘}
+starting with @w{@kbd{C-x 8}}.  For example, @kbd{C-x 8 [} inserts @t{‘}
 which is Unicode code-point U+2018 @sc{left single quotation mark},
 sometimes called a left single ``curved quote'' or ``curly quote''.
-Similarly, @kbd{C-x 8 ]}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
+Similarly, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
 curved quotes @t{’}, @t{“} and @t{”}, respectively.  Also, a working
 @key{Alt} key acts like @kbd{C-x 8} (unless followed by @key{RET});
 e.g., @kbd{A-[} acts like @kbd{C-x 8 [} and inserts @t{‘}.  To see
diff -u old/doc/emacs/display.texi new/doc/emacs/display.texi
--- old/doc/emacs/display.texi	2021-01-28 18:52:37.000000000 +0100
+++ new/doc/emacs/display.texi	2021-05-13 12:21:38.215626100 +0200
@@ -1635,10 +1635,10 @@
 @cindex curved quotes, and terminal capabilities
 @cindex @code{homoglyph} face
 
-Emacs tries to determine if the curved quotes @samp{‘} and @samp{’}
+Emacs tries to determine if the curved quotes @t{‘} and @t{’}
 can be displayed on the current display.  By default, if this seems to
-be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`}
-and @samp{'}), when they appear in messages and help texts, to these
+be so, then Emacs will translate the @acronym{ASCII} quotes @w{(@samp{`}
+and @samp{'})}, when they appear in messages and help texts, to these
 curved quotes.  You can influence or inhibit this translation by
 customizing the user option @code{text-quoting-style} (@pxref{Keys in
 Documentation,,, elisp, The Emacs Lisp Reference Manual}).
@@ -1647,7 +1647,7 @@
 known to look just like @acronym{ASCII} characters, they are shown
 with the @code{homoglyph} face.  Curved quotes that are known not to
 be displayable are shown as their @acronym{ASCII} approximations
-@t{`}, @t{'}, and @t{"} with the @code{homoglyph} face.
+@samp{`}, @samp{'}, and @samp{"} with the @code{homoglyph} face.
 
 @node Cursor Display
 @section Displaying the Cursor
diff -u old/doc/emacs/emacs.texi new/doc/emacs/emacs.texi
--- old/doc/emacs/emacs.texi	2021-01-28 18:52:37.000000000 +0100
+++ new/doc/emacs/emacs.texi	2021-05-13 12:59:52.857256000 +0200
@@ -99,6 +99,7 @@
 
 @end titlepage
 
+@headings double
 
 @summarycontents
 @contents
diff -u old/doc/emacs/text.texi new/doc/emacs/text.texi
--- old/doc/emacs/text.texi	2021-01-28 18:52:37.000000000 +0100
+++ new/doc/emacs/text.texi	2021-05-13 12:55:51.725232900 +0200
@@ -421,13 +421,12 @@
 @cindex curved quotes
 @cindex guillemets
 @findex electric-quote-mode
-@c The funny quoting below is to make the printed version look
-@c correct.  FIXME.
+
   One common way to quote is the typewriter convention, which quotes
-using straight apostrophes @t{'like this'} or double-quotes @t{"like
+using straight apostrophes @samp{'like this'} or double-quotes @samp{"like
 this"}.  Another common way is the curved quote convention, which uses
-left and right single or double quotation marks `@t{like this}' or
-``@t{like this}''@footnote{
+left and right single or double quotation marks @t{‘like this’} or
+@t{“like this”}@footnote{
 The curved single quote characters are U+2018 @sc{left single quotation
 mark} and U+2019 @sc{right single quotation mark}; the curved double quotes
 are U+201C @sc{left double quotation mark} and U+201D @sc{right double
@@ -445,7 +444,7 @@
 @code{electric-quote-chars}, a list of four characters, where the
 items correspond to the left single quote, the right single quote, the
 left double quote and the right double quote, respectively, whose
-default value is @code{'(?@r{`} ?@r{'} ?@r{``} ?@r{''})}.
+default value is @w{@code{'(@w{?}‘ ?’ ?“ ?”)}}.
 
 @vindex electric-quote-paragraph
 @vindex electric-quote-comment
@@ -461,7 +460,7 @@
 
 @vindex electric-quote-replace-double
   You can also set the option @code{electric-quote-replace-double} to
-a non-@code{nil} value.  Then, typing @t{"} insert an appropriate
+a non-@code{nil} value.  Then, typing @kbd{"} insert an appropriate
 curved double quote depending on context: @t{“} at the beginning of
 the buffer or after a line break, whitespace, opening parenthesis, or
 quote character, and @t{”} otherwise.
@@ -473,7 +472,7 @@
 type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}.  To
 insert a curved quote even when Electric Quote is disabled or
 inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for
-@t{’}, @kbd{C-x 8 @{} for ``, and @kbd{C-x 8 @}} for ''.
+@t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}.
 @xref{Inserting Text}.  Note that the value of
 @code{electric-quote-chars} does not affect these keybindings, they
 are not keybindings of @code{electric-quote-mode} but bound in