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

[Sebastian Urban <mrsebastianurban@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 8432 bytes --]

Alright, updated version of changes, without @verb.

NOTE: Based on TEXI files from emacs-27 branch, downloaded 19.08.2020.

* BASIC.TEXI
============

1.  Apparently, pushing "C-x 8 ]" to the next page made "C-x 8" (the
      same paragraph, above) split after "C-x", so another @w is needed.

2.  (OPTIONAL) I removed @verb, but kept reorder of the words.  As I
      wrote in the original message:
         I also moved examples to the end of part of the sentence, this
         way we have: description followed by an example, instead of
         example being in the middle of description.
      Also, last example is split between lines, so I had to use @w.

--8<---------------cut here---------------start------------->8---
--- old/basic.texi	2020-08-20 17:59:31.446496400 +0200
+++ new/basic.texi	2020-08-20 18:17:59.289249300 +0200
@@ -112,7 +112,7 @@
   @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, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
@@ -147,10 +147,10 @@

     In addition, in some contexts, if you type a quotation using grave
   accent and apostrophe @kbd{`like this'}, it is converted to a form
-@t{‘like this’} using single quotation marks, even without @kbd{C-x 8}
-commands.  Similarly, typing a quotation @kbd{``like this''} using
-double grave accent and apostrophe converts it to a form @t{“like
-this”} using double quotation marks.  @xref{Quotation Marks}.
+using single quotation marks @t{‘like this’}, even without @kbd{C-x 8}
+commands.  Similarly, typing a quotation using double grave accent and
+apostrophe @kbd{``like this''}, converts it to a form using double
+quotation marks @w{@t{“like this”}}.  @xref{Quotation Marks}.

   @node Moving Point
   @section Changing the Location of Point
--8<---------------cut here---------------end--------------->8---


* DISPLAY.TEXI
==============

1.  Changed @samp to @t, as far as I remember it's preferred for quotes.

2.  Similarly, in (...), I changed @samp to @kbd.  Although, this time
      there is a page break after "(`", so @w around parens is needed.
      But it moves "(` and ')" to the next page.  If we want to keep it
      on the same page, we have to include (inside @w) word "quotes",
      i.e. "@w{quotes (@kbd{`} and @kbd{'})}".

3.  If I didn't make mistake there should be ASCII quotes not curved
      quotes, so I changed @t to @kbd.

--8<---------------cut here---------------start------------->8---
--- old/display.texi	2020-08-19 15:44:43.000000000 +0200
+++ new/display.texi	2020-08-20 18:53:25.061187600 +0200
@@ -1632,10 +1632,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{(@kbd{`}
+and @kbd{'})}, 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}).
@@ -1644,7 +1644,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.
+@kbd{`}, @kbd{'}, and @kbd{"} with the @code{homoglyph} face.

   @node Cursor Display
   @section Displaying the Cursor
--8<---------------cut here---------------end--------------->8---


* MODES.TEXI
============

Since, we are sticking to @kbd, and not using @verb, no changes in
this file.


* TEXT.TEXI
===========

1.  Quotes are fixed, so we don't need FIXME note.

2.  Changed @t to @kbd, because straight quotes are needed.

3.  Changed `...' and ``...'' to ‘...’ and “...”, and put them inside
      of @t, because it works now.

4.  Quoting myself again:
         Value of "electric-quote-chars" has so many @w, because:
            A.  To prevent splitting between lines, which happens;
            B.  ?‘ expands to ¿, so I had to prevent it (@w near ?’ ?“
            ?”, are unnecessary, but I put them anyway for consistency
            and just in case something in the future change, i.e. for
            safety).
      As for splitting, with @w it is put in the next line alone,
      perhaps it would look better with "is" in front of it, if yes -
      "is" must be put inside @w.

5.  Changed @t{"} to @kbd{"}, because we want "quotation mark".

6.  Changed `` and '' to @t{“} and @t{”}, reason the same as in (3.).

--8<---------------cut here---------------start------------->8---
--- old/text.texi	2020-08-19 15:45:20.000000000 +0200
+++ new/text.texi	2020-08-20 19:40:15.062523900 +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 @kbd{'like this'} or double-quotes @kbd{"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{?}‘ @w{?}’ @w{?}“ @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
--8<---------------cut here---------------end--------------->8---


* EMACS.TEXI
============

This will change header style (PDF), to this:
+-------------------------+ +------------------------+
| PAGE_NUM      DOC_TITLE | |CHAPTER        PAGE_NUM |

--8<---------------cut here---------------start------------->8---
--- old/emacs.texi	2020-08-19 15:44:47.000000000 +0200
+++ new/emacs.texi	2020-08-20 20:06:46.751323200 +0200
@@ -99,6 +99,7 @@

   @end titlepage

+@headings double

   @summarycontents
   @contents
--8<---------------cut here---------------end--------------->8---


That's all,
S. U.


[-- Attachment #2: basic.diff --]
[-- Type: text/plain, Size: 1410 bytes --]

--- old/basic.texi	2020-08-20 17:59:31.446496400 +0200
+++ new/basic.texi	2020-08-20 18:17:59.289249300 +0200
@@ -112,7 +112,7 @@
 @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, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
@@ -147,10 +147,10 @@
 
   In addition, in some contexts, if you type a quotation using grave
 accent and apostrophe @kbd{`like this'}, it is converted to a form
-@t{‘like this’} using single quotation marks, even without @kbd{C-x 8}
-commands.  Similarly, typing a quotation @kbd{``like this''} using
-double grave accent and apostrophe converts it to a form @t{“like
-this”} using double quotation marks.  @xref{Quotation Marks}.
+using single quotation marks @t{‘like this’}, even without @kbd{C-x 8}
+commands.  Similarly, typing a quotation using double grave accent and
+apostrophe @kbd{``like this''}, converts it to a form using double
+quotation marks @w{@t{“like this”}}.  @xref{Quotation Marks}.
 
 @node Moving Point
 @section Changing the Location of Point

[-- Attachment #3: display.diff --]
[-- Type: text/plain, Size: 1316 bytes --]

--- old/display.texi	2020-08-19 15:44:43.000000000 +0200
+++ new/display.texi	2020-08-20 18:53:25.061187600 +0200
@@ -1632,10 +1632,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{(@kbd{`}
+and @kbd{'})}, 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}).
@@ -1644,7 +1644,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.
+@kbd{`}, @kbd{'}, and @kbd{"} with the @code{homoglyph} face.
 
 @node Cursor Display
 @section Displaying the Cursor

[-- Attachment #4: emacs.diff --]
[-- Type: text/plain, Size: 197 bytes --]

--- old/emacs.texi	2020-08-19 15:44:47.000000000 +0200
+++ new/emacs.texi	2020-08-20 20:06:46.751323200 +0200
@@ -99,6 +99,7 @@
 
 @end titlepage
 
+@headings double
 
 @summarycontents
 @contents

[-- Attachment #5: text.diff --]
[-- Type: text/plain, Size: 2401 bytes --]

--- old/text.texi	2020-08-19 15:45:20.000000000 +0200
+++ new/text.texi	2020-08-20 19:40:15.062523900 +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 @kbd{'like this'} or double-quotes @kbd{"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{?}‘ @w{?}’ @w{?}“ @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