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

[Sebastian Urban <mrsebastianurban@gmail.com>]

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

I'm revisiting this bug report, because, thanks to patches to
TEXINFO.TEX by Gavin Smith, I believe we can finally fix the issues
for good.  TEXINFO.TEX version >= 2020-05-10.15 is required.

Additionally bug about heading not appearing sometimes on last page of
the chapter (present in official PDF version updated for 26.3), was
fixed as well.


I decided to went through places pointed out in this report, to see if
any changes are needed, here are diffs based on master branch from
03.05.2020 (I also attached them):

------------------------- BASIC.TEXI START -------------------------
--- old/basic.texi	2020-05-03 01:28:18.576838200 +0200
+++ new/basic.texi	2020-05-05 23:07:21.487684600 +0200
@@ -115,7 +115,7 @@
  starting with @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
@@ -146,11 +146,11 @@
  how many copies of the character to insert (@pxref{Arguments}).

    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}.
+accent and apostrophe @verb{|`like this'|}, it is converted to a form
+using single quotation marks @t{‘like this’}, even without @kbd{C-x 8}
+commands.  Similarly, typing a quotation using double grave accent and
+apostrophe @verb{|``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
------------------------- BASIC.TEXI END -------------------------

1st change @w - in PDF this key is split on two pages, which looks
     	   	bad.
2nd change:
    - changed @kbd to @verb, because @kbd surrounds text with pair of
      curved quotes in plain text - result it ‘``like this''’, @verb
      doesn't do it;
    - @w, because last example is split between 2 lines;
    - 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.

------------------------- DSIPLAY.TEXI START -------------------------
--- old/display.texi	2020-05-03 01:29:34.852965900 +0200
+++ new/display.texi	2020-05-05 23:00:10.014126600 +0200
@@ -1629,10 +1629,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}).
@@ -1641,7 +1641,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
------------------------- DSIPLAY.TEXI END -------------------------

Basically, I got rid of @samp in favour of @t and @kbd; the @w
prevents line break after "`".

------------------------- MODES.TEXI START -------------------------
--- old/modes.texi	2020-05-03 01:32:48.773267500 +0200
+++ new/modes.texi	2020-05-05 20:23:41.217738900 +0200
@@ -207,7 +207,7 @@

  @item
  Electric Quote mode automatically converts quotation marks.  For
-example, it requotes text typed @kbd{`like this'} to text @t{‘like
+example, it requotes text typed @verb{|`like this'|} to text @t{‘like
  this’}.  You can control what kind of text it operates in, and you can
  disable it entirely in individual buffers.  @xref{Quotation Marks}.
------------------------- MODES.TEXI END -------------------------

Another example surrounded by unnecessary curved quotes in plain text,
fixed by using @verb.

------------------------- TEXT.TEXI START -------------------------
--- old/text.texi	2020-05-03 01:34:10.677385800 +0200
+++ new/text.texi	2020-05-05 23:47:52.987559000 +0200
@@ -421,13 +421,11 @@
  @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
-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{
+using straight apostrophes @verb{|'like this'|} or double-quotes
+@verb{|"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{
  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 +443,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 +459,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 +471,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
------------------------- TEXT.TEXI END -------------------------

- Quotes are fixed, so FIXME is no longer needed.
- 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).


Optionally, I would also suggest replacing @kbd for ` ' `` '' with
@verb for the same reason as stated above, i.e. instead of ` in plain
text, with @kbd we're getting ‘`’, which looks quite interesting in
e.g. "Quotation Marks" section: "(...) it optionally converts ‘`’ to
‘, ‘'’ to ’, ‘``’ to “, and ‘''’ to ”."


 >> 2.  Header style should be changed.
 >> It shows page number in right upper corner on every page, but it
 >> should show it in right upper corner for odd (right-side) pages and in
 >> left upper corner for even (left-side) pages - just like in normal
 >> book.
 >>
 >> 3.  Add numbers to sections (& subsect.) for bookmark/navigation pane.
 >> When you open it in any PDF reader with manual loaded, it only shows
 >> names of sections, and without numbers it's difficult to navigate.
 >
 > These are beyond our control (well, unless we want to write a lot of
 > TeX glue in the manual): this is how Texinfo works.

With the up-to-date version of TEXINFO.TEX, header style could be
changed with this:

------------------------- EMACS.TEXI START -------------------------
--- old/emacs.texi       2020-05-10 21:24:52.351021900 +0200
+++ new/emacs.texi       2020-05-10 21:23:30.621478300 +0200
@@ -99,10 +99,13 @@

  @end titlepage

+@evenheading @thispage @| @|
+@oddheading @| @| @thispage

  @summarycontents
  @contents

+@headings double

  @ifnottex
  @node Top
------------------------- EMACS.TEXI END -------------------------

which will print this:
+--------------------------+ +------------------------+
| PAGE_NUM       DOC_TITLE | |CHAPTER        PAGE_NUM |

This is something I wanted to do in point 2.  It would certainly make
PDF look better.


As for chapters/sections numbering: chapters (level) will be numbered,
but sections won't for now (more opinions from other people are
needed).  As for me, chapter numeration (only) is good enough to mark
it as done.


Optional, further reading:

- quotes problem thread & PDF bookmarks numeration thread:
https://lists.gnu.org/archive/html/help-texinfo/2020-05/msg00005.html

- headers thread:
https://lists.gnu.org/archive/html/help-texinfo/2020-04/msg00000.html
CONTINUED
https://lists.gnu.org/archive/html/help-texinfo/2020-05/msg00000.html


S. U.

P.S.  If separate bug report is preferred, let me know, I'll send it
       again.

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

--- old/basic.texi	2020-05-03 01:28:18.576838200 +0200
+++ new/basic.texi	2020-05-05 23:07:21.487684600 +0200
@@ -115,7 +115,7 @@
 starting with @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
@@ -146,11 +146,11 @@
 how many copies of the character to insert (@pxref{Arguments}).
 
   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}.
+accent and apostrophe @verb{|`like this'|}, it is converted to a form
+using single quotation marks @t{‘like this’}, even without @kbd{C-x 8}
+commands.  Similarly, typing a quotation using double grave accent and
+apostrophe @verb{|``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-05-03 01:29:34.852965900 +0200
+++ new/display.texi	2020-05-05 23:00:10.014126600 +0200
@@ -1629,10 +1629,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}).
@@ -1641,7 +1641,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: modes.diff --]
[-- Type: text/plain, Size: 493 bytes --]

--- old/modes.texi	2020-05-03 01:32:48.773267500 +0200
+++ new/modes.texi	2020-05-05 20:23:41.217738900 +0200
@@ -207,7 +207,7 @@
 
 @item
 Electric Quote mode automatically converts quotation marks.  For
-example, it requotes text typed @kbd{`like this'} to text @t{‘like
+example, it requotes text typed @verb{|`like this'|} to text @t{‘like
 this’}.  You can control what kind of text it operates in, and you can
 disable it entirely in individual buffers.  @xref{Quotation Marks}.
 

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

--- old/text.texi	2020-05-03 01:34:10.677385800 +0200
+++ new/text.texi	2020-05-05 23:47:52.987559000 +0200
@@ -421,13 +421,11 @@
 @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
-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{
+using straight apostrophes @verb{|'like this'|} or double-quotes
+@verb{|"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{
 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 +443,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 +459,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 +471,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