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

[Sebastian Urban]

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.

basic.diff
Description: Text document

display.diff
Description: Text document

emacs.diff
Description: Text document

text.diff
Description: Text document