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

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

[Sebastian Urban]

Hello,

I gathered few mistakes in the manual and 3 proposals for it, in one
report, because they are small (maybe except 2nd and 3rd proposal) and
sending them one by one would be spam-ish.  I found them in GNU Emacs
25.2.1 (i686-w64-mingw32) of 2017-04-24 and PDFs updated for 25.2 and
26.2.

* INFO
====================

1.  In INFO 11.7 Disabling Transient Mark Mode:
- ‘M-x transient-mark-mode’, or with the ‘Active Region Highlighting’ menu
+ ‘M-x transient-mark-mode’, or with the ‘Highlight Active Region’ menu
This is correct name of menu item.

2.  In INFO 13.2 Saving Text in Registers:
- activating it.  With a numeric argument, it instead puts point before
+ activating it.  With a prefix argument, it instead puts point before
Help window of 'insert-register' has prefix arg.

3.  In INFO 13.3 Saving Rectangles in Registers:
-      (‘copy-rectangle-to-register’).  With numeric argument, delete it
+      (‘copy-rectangle-to-register’).  With prefix argument, delete it
Help window of 'copy-rectangle-to-register' has prefix arg.

4.  In INFO 14.2 Recentering:
in paragraph starting with "You can also give ‘C-l’ a prefix
argument.", expressions:
    - "recenters point" should be "recenters line"
    - "puts point" (3 occurrences) should rather be "moves current
    line", because point is moved this way by 'M-r'
    ('move-to-window-line-top-bottom') and also in help window for
    'recenter-top-bottom' we have "move current line".

5.  In INFO 14.19 How Text Is Displayed:
- have an integer value between 1 and 1000, inclusive.  Note that how the
+ have an integer value between 1 and 1000, inclusive.  Note how the
I think "that" is unnecessary, "Note that how the tab character
(...)", will change into "Note how the tab character (...)".  Although
I'm not sure of it, maybe current form is correct?

* PDF
====================

1.  In PDF 4.1 Inserting Text:
in paragraph starting with "A few common Unicode characters can be
inserted (...)" (near word "respectively"), "left double quotation
mark" (curved) is displayed as "backslash" and "right double quotation
mark" (curved) is displayed as "straight double quotes".  In INFO it
looks ok.

2.  In PDF 4.1 Inserting Text:
in paragraph starting with "In some contexts, if you type a quotation
(...)", display of quotes is messed up, quotes surrounding Nth
occurrence of "like this" should be:
    - 1st - "grave accent" and "apostrophe",
    - 2nd - is ok,
    - 3rd - 2x "grave accent" and 2x "apostrophe",
    - 4th - "left double quotation mark" (curved) and "right double
      quotation mark" (curved)
Or just look into INFO, it's ok there.

3.  In PDF 11.19 How Text Is Displayed:
in last paragraph, first line, "left double quotation mark" (curved)
is displayed as "backslash" and "right double quotation mark" (curved)
is displayed as "straight double quotes".  In INFO it looks ok.

* Small proposals
====================

1.  Emphasize a word
In both INFO(7.10 Numeric arguments) and PDF(4.10 Numeric Arguments),
in last paragraph, there is a word "before", I suggest to emphasize
this word (or maybe make it slanted, up to you).  It will have
stronger (visual) connection to slanted "prefix argument".

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.

---
S. U.

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

[Sebastian Urban]

Few more for INFO...
====================

6.  In INFO 15.1.1 Basics of Incremental Search:
- ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g C-g’ (‘isearch-abort’).
+ ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g’ (‘isearch-abort’).
Because `view-lossage' and `describe-bindings' and the last paragraph
of 15.1.4 say: `C-g'.

7. In INFO 17.4 Executing Macros with Variations:
-    ‘C-u C-x q’, which is ‘C-x q’ with a numeric argument, performs a
+    ‘C-u C-x q’, which is ‘C-x q’ with a prefix argument, performs a
Help window of `kbd-macro-query' has prefix arg.

8. In INFO 17.5 Naming and Saving Keyboard Macros:
-    If you give ‘insert-kbd-macro’ a numeric argument, it makes
+    If you give ‘insert-kbd-macro’ a prefix argument, it makes
Help window of `insert-kbd-macro' has prefix arg.

9. In INFO 15.10.2 Regexp Replacement:
-   Repeating our example to exchange ‘x’ and ‘y’, we can thus do it also
-this way:
+   For example to exchange `x' and `y', we can do it this way:
Although I'm not sure of this, the sentence sounds like there is
another example of exchanging `x' and `y' (especially the word
``also''), but I cannot find it, therefore or I missed it, or there was
something, but it was deleted and someone forgot to update the text.

10. In both INFO and PDF:
   10.1. INFO 15.9 Lax Matching During Searching:
   - such as U+249C PARENTHESIZED LATIN SMALL LETTER A and U+2100 ACCOUNT OF
   + such as `U+249C' PARENTHESIZED LATIN SMALL LETTER A and `U+2100' 
ACCOUNT OF
   AND
   - matches U+FB00 LATIN SMALL LIGATURE FF.  Character sequences that are
   + matches `U+FB00' LATIN SMALL LIGATURE FF.  Character sequences that are
   In both cases in PDF (12.9) string from `U' to the end of character
   name (except `+' and digits) is written as "small caps shape" while
   it should be: code as "typewriter family" (or verbatim?) and name as
   normal upcase letters - just like in chapter "Inserting Text".

   10.2. INFO 25.5 Quotation Marks:
   -    (1) The curved single quote characters are U+2018 LEFT SINGLE
   - QUOTATION MARK and U+2018 RIGHT SINGLE QUOTATION MARK; the curved 
double
   - quotes are U+201C LEFT DOUBLE QUOTATION MARK and U+201D RIGHT DOUBLE
   - QUOTATION MARK. On text terminals which cannot display these characters
   +    (1) The curved single quote characters are `U+2018' LEFT SINGLE
   + QUOTATION MARK and `U+2018' RIGHT SINGLE QUOTATION MARK; the curved 
double
   + quotes are `U+201C' LEFT DOUBLE QUOTATION MARK and `U+201D' RIGHT 
DOUBLE
   + QUOTATION MARK. On text terminals which cannot display these characters
   Similar to the problem above, only this time in PDF (22.5), Unicode
   should be written as typewriter/verbatim, the name is OK - all
   uppercase.

OR... perhaps desired way was: typewriter/verbatim for the code and
small caps shape for the name?

... and for PDF...
==================

In PDF 22.5 Quotation Marks:
    In 1st paragraph, 2nd line: 1st "like this" is surrounded with single
curved quotes, while they should be single straight quotes.
    In 1st paragraph, 3rd&4th line: both "like this" are surrounded with
good quotes, but they have bad shape (normal text), while should be
typewriter/verbatim.
    In 2nd paragraph, 2nd line: there should be straight quotes
followed by their curved types, but unfortunately straight quotes are
curved as well.  Also curved have bad shape (normal text), should be
typewriter/verbatim.
    In 2nd paragraph, "value" at the end: curved quotes have bad shape
(normal text), should be typewriter/verbatim.
    In 4th paragraph, 5th line: curved quotes have bad shape (normal
text), should be typewriter/verbatim.

ALSO (addition)

In point 1 (previous message) in the same paragraph, line below, "(...)
C-x 8 [ and inserts (...)" and curved opening quote follows, which
is good, but it has shape of normal latex text, while it should has
typewriter/verbatim shape (bolder one).

... and another proposal
========================

In INFO 15.6 and PDF 12.6 Syntax of Regular Expressions:
Perhaps slanting word "special" or "special constructs" (I would opt
for first one) in...
    Regular expressions have a syntax in which a few characters are
special constructs and the rest are “ordinary”.  An ordinary character
... for (again) stronger visual connection with word "ordinary".

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Mon, 3 Jun 2019 00:50:55 +0200
> 
> 6.  In INFO 15.1.1 Basics of Incremental Search:
> - ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g C-g’ (‘isearch-abort’).
> + ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g’ (‘isearch-abort’).
> Because `view-lossage' and `describe-bindings' and the last paragraph
> of 15.1.4 say: `C-g'.

I left this unaltered, because in some cases you do need to type C-g
twice, so doing it twice always is safer.

> 7. In INFO 17.4 Executing Macros with Variations:
> -    ‘C-u C-x q’, which is ‘C-x q’ with a numeric argument, performs a
> +    ‘C-u C-x q’, which is ‘C-x q’ with a prefix argument, performs a
> Help window of `kbd-macro-query' has prefix arg.
> 
> 8. In INFO 17.5 Naming and Saving Keyboard Macros:
> -    If you give ‘insert-kbd-macro’ a numeric argument, it makes
> +    If you give ‘insert-kbd-macro’ a prefix argument, it makes
> Help window of `insert-kbd-macro' has prefix arg.

Fixed.

> 9. In INFO 15.10.2 Regexp Replacement:
> -   Repeating our example to exchange ‘x’ and ‘y’, we can thus do it also
> -this way:
> +   For example to exchange `x' and `y', we can do it this way:
> Although I'm not sure of this, the sentence sounds like there is
> another example of exchanging `x' and `y' (especially the word
> ``also''), but I cannot find it, therefore or I missed it, or there was
> something, but it was deleted and someone forgot to update the text.

There was a previous example, but it was deleted in Emacs 24.  I fixed
the wording.

> 10. In both INFO and PDF:
>    10.1. INFO 15.9 Lax Matching During Searching:
>    - such as U+249C PARENTHESIZED LATIN SMALL LETTER A and U+2100 ACCOUNT OF
>    + such as `U+249C' PARENTHESIZED LATIN SMALL LETTER A and `U+2100' 
> ACCOUNT OF
>    AND
>    - matches U+FB00 LATIN SMALL LIGATURE FF.  Character sequences that are
>    + matches `U+FB00' LATIN SMALL LIGATURE FF.  Character sequences that are
>    In both cases in PDF (12.9) string from `U' to the end of character
>    name (except `+' and digits) is written as "small caps shape" while
>    it should be: code as "typewriter family" (or verbatim?) and name as
>    normal upcase letters - just like in chapter "Inserting Text".

I don't see anything wrong with the current typeface, so I left it
alone.

>    10.2. INFO 25.5 Quotation Marks:
>    -    (1) The curved single quote characters are U+2018 LEFT SINGLE
>    - QUOTATION MARK and U+2018 RIGHT SINGLE QUOTATION MARK; the curved 
> double
>    - quotes are U+201C LEFT DOUBLE QUOTATION MARK and U+201D RIGHT DOUBLE
>    - QUOTATION MARK. On text terminals which cannot display these characters
>    +    (1) The curved single quote characters are `U+2018' LEFT SINGLE
>    + QUOTATION MARK and `U+2018' RIGHT SINGLE QUOTATION MARK; the curved 
> double
>    + quotes are `U+201C' LEFT DOUBLE QUOTATION MARK and `U+201D' RIGHT 
> DOUBLE
>    + QUOTATION MARK. On text terminals which cannot display these characters
>    Similar to the problem above, only this time in PDF (22.5), Unicode
>    should be written as typewriter/verbatim, the name is OK - all
>    uppercase.

Like earlier, I didn't change anything about the quotes, because I
think that was fixed already.  Please try the latest Texinfo sources.

> In PDF 22.5 Quotation Marks:
>     In 1st paragraph, 2nd line: 1st "like this" is surrounded with single
> curved quotes, while they should be single straight quotes.
>     In 1st paragraph, 3rd&4th line: both "like this" are surrounded with
> good quotes, but they have bad shape (normal text), while should be
> typewriter/verbatim.
>     In 2nd paragraph, 2nd line: there should be straight quotes
> followed by their curved types, but unfortunately straight quotes are
> curved as well.  Also curved have bad shape (normal text), should be
> typewriter/verbatim.
>     In 2nd paragraph, "value" at the end: curved quotes have bad shape
> (normal text), should be typewriter/verbatim.
>     In 4th paragraph, 5th line: curved quotes have bad shape (normal
> text), should be typewriter/verbatim.

Likewise.

> In point 1 (previous message) in the same paragraph, line below, "(...)
> C-x 8 [ and inserts (...)" and curved opening quote follows, which
> is good, but it has shape of normal latex text, while it should has
> typewriter/verbatim shape (bolder one).

Likewise.

> In INFO 15.6 and PDF 12.6 Syntax of Regular Expressions:
> Perhaps slanting word "special" or "special constructs" (I would opt
> for first one) in...
>     Regular expressions have a syntax in which a few characters are
> special constructs and the rest are “ordinary”.  An ordinary character
> ... for (again) stronger visual connection with word "ordinary".

Done.

Thanks again for reviewing the manual.

I'm marking this bug report done.

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

[Sebastian Urban]

Thanks for the fixes, but I don't think closing this bug was good
decision.  Even if we leave quotes behind (but we won't, right?),
Unicode code and name pairs bug will still be there.

> I believe you saw these in the Emacs 25 manual.

No, my reference is version updated for 26.2, downloaded from official
Emacs website with manuals.  For this e-mail I also looked into HTML
version.

> ... checkout the current emacs-26 branch...

Well after you said it, I did that - I downloaded basic.texi,
display.texi, search.texi, text.texi from:
http://git.savannah.gnu.org/cgit/emacs.git/tree/doc/emacs?h=emacs-26
and texinfo.tex from:
http://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc?h=emacs-26

Unfortunately I didn't make PDF out of them, but I looked into theirs
code/text.

> 1.  In PDF 4.1 Inserting Text:
> in paragraph starting with "A few common Unicode characters can be
> inserted (...)" (near word "respectively"), "left double quotation
> mark" (curved) is displayed as "backslash" and "right double quotation
> mark" (curved) is displayed as "straight double quotes".  In INFO it
> looks ok.

Well for this I have no answer...

In BASIC.TEXI (L119):
# curved quotes @t{’}, @t{“} and @t{”}, respectively.  Also, a working
While @t{...} works for
   single quotes - both curved (#x2018 & #x2019), probably including x2
   grave accent, including x2
   apostrophe, including x2
making all of them curved and in typewriter shape in PDF, it fails to
show LEFT (#x201c) and RIGHT (#x201d) DOUBLE QUOTATION MARK, and
displays instead BACKSLASH and QUOTATION MARK (#x22).  It also works
for QUOTATION MARK - @t{"}.  An ugly way to fix it would be @t{``} and
@t{''}, but I think it's not an option.

BTW This looks good in HTML version.

> ALSO (addition)
>
> In point 1 (previous message) in the same paragraph, line below, "(...)
> C-x 8 [ and inserts (...)" and curved opening quote follows, which
> is good, but it has shape of normal latex text, while it should has
> typewriter/verbatim shape (bolder one).

In BASIC.TEXI - LINE 121:
- and inserts `.  To see which characters have @kbd{C-x 8} ...
+ and inserts @t{‘}.  To see which characters have @kbd{C-x 8} ...
Just like in L115.  This bug is present in HTML version as well.

> 2.  In PDF 4.1 Inserting Text:
> in paragraph starting with "In some contexts, if you type a quotation
> (...)", display of quotes is messed up, quotes surrounding Nth
> occurrence of "like this" should be:
>    - 1st - "grave accent" and "apostrophe",
>    - 2nd - is ok,
>    - 3rd - 2x "grave accent" and 2x "apostrophe",
>    - 4th - "left double quotation mark" (curved) and "right double
>      quotation mark" (curved)
> Or just look into INFO, it's ok there.

As for 1st occurrence in BASIC.TEXI - L149:
# accent and apostrophe @t{`like this'}, it is converted to a form
It could be corrected with @kbd{`}@t{like this}@kbd{'}.  Looks good
in HTML.

As for 2nd - it also looks good in HTML.

As for 3rd occurrence in BASIC.TEXI - L151:
# commands.  Similarly, typing a quotation @t{``like this''} using
As above - @kbd{``}@t{like this}@kbd{''}...  Looks bad in HTML.

As for 4th occurrence, just like in first point - I don't know.
Looks good in HTML.

> 3.  In PDF 11.19 How Text Is Displayed:
> in last paragraph, first line, "left double quotation mark" (curved)
> is displayed as "backslash" and "right double quotation mark" (curved)
> is displayed as "straight double quotes".  In INFO it looks ok.

In DISPLAY.TEXI - L1560:
#  If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
Well here we have @samp{...} instead of @t{...}, which also fails to
show “ and ”, displaying instead \ and " (just like @t{...}).  But
it looks good in HTML.

> In PDF 22.5 Quotation Marks:

First little bonus from TEXT.TEXI (L424-425):
"The funny quoting below is to make the printed version look correct.
FIXME."

>    In 1st paragraph, 2nd line: 1st "like this" is surrounded with single
> curved quotes, while they should be single straight quotes.

In TEXT.TEXI - L427:
# using straight apostrophes @t{'like this'} or double-quotes @t{"like
Similar to above example, @kbd{'}@t{like this}@kbd{'}.  Looks good in
HTML.

>    In 1st paragraph, 3rd&4th line: both "like this" are surrounded with
> good quotes, but they have bad shape (normal text), while should be
> typewriter/verbatim.

In TEXT.TEXI - L429:
# left and right single or double quotation marks `@t{like this}' or
Switch to - @t{‘like this’} - with #x2018 & #x2019.

The second "like this" is L/R double quotation marks, so again no answer.

Both look bad in HTML.

>    In 2nd paragraph, 2nd line: there should be straight quotes
> followed by their curved types, but unfortunately straight quotes are
> curved as well.  Also curved have bad shape (normal text), should be
> typewriter/verbatim.

In TEXT.TEXI - L442-443:
- type characters it optionally converts @t{`} to ‘, @t{'} to ',
- @t{``} to ``, and @t{''} to ''.  It's possible to change the
+ type characters it optionally converts @kbd{`} to @t{‘}, @kbd{'} to @t{’},
+ @kbd{``} to ??, and @kbd{''} to ??.  It's possible to change the
Of course I don't know what to put for “ and ”, so I put ?? there.
Also it looks bad in HTML.

>    In 2nd paragraph, "value" at the end: curved quotes have bad shape
> (normal text), should be typewriter/verbatim.

In TEXT.TEXI - L448:
# default value is @code{'(?@r{`} ?@r{'} ?@r{``} ?@r{''})}.
Perhaps first two could be changed to normal @t{‘} and @t{’}.  Last
two - a mystery.  Also it looks bad in HTML.

>    In 4th paragraph, 5th line: curved quotes have bad shape (normal
> text), should be typewriter/verbatim.

In TEXT.TEXI - L469:
# @t{’}, @kbd{C-x 8 @{} for ``, and @kbd{C-x 8 @}} for ''.
Again L/R double quotation mark.  Also it looks bad in HTML.

====================

Now about Unicode code & name pairs.

> I don't see anything wrong with the current typeface, so I left it
> alone.

In BASIC.TEXI - L116 we have:
    @code{U+2018} LEFT SINGLE QUOTATION MARK
In SEARCH.TEXI - L1313-1314 and L1319-1320 we have:
    @sc{u+249c parenthesized latin small letter a}
    @sc{u+2100 account of}
    @sc{u+fb00 latin small ligature ff}
In TEXT.TEXI - L430 (inside footnote) we have:
    U+2018 LEFT SINGLE QUOTATION MARK
    U+2018 RIGHT SINGLE QUOTATION MARK <--- this has wrong code!
    U+201C LEFT DOUBLE QUOTATION MARK
    U+201D RIGHT DOUBLE QUOTATION MARK
So, 3 different styles.  I think @code{...} around Unicode code and
uppercase "U" is a must.  This is how they are displayed in many other
places.  Style of name - I don't know, I would pick normal uppercase,
because of simplicity, but it's up to you.

====================

>> 6.  In INFO 15.1.1 Basics of Incremental Search:
>> - ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g C-g’ (‘isearch-abort’).
>> + ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g’ (‘isearch-abort’).
>> Because `view-lossage' and `describe-bindings' and the last paragraph
>> of 15.1.4 say: `C-g'.
>
> I left this unaltered, because in some cases you do need to type C-g
> twice, so doing it twice always is safer.

Well I think the last paragraph of 15.1.4 pointed by me explains this
behaviour.  It exactly says that sometimes C-g needs to be typed twice
to exit search.  That's why I'm sticking to my version, unless you had
other cases in mind.  And "isearch-abort" is literally binded to "C-g"
so it may rise questions.

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 35885@debbugs.gnu.org
> Date: Tue, 4 Jun 2019 12:48:50 +0200
> 
> Thanks for the fixes, but I don't think closing this bug was good
> decision.  Even if we leave quotes behind (but we won't, right?),
> Unicode code and name pairs bug will still be there.

We can continue discussing this even though the bug is closed.  And
since this is a documentation "bug", closing it has no bearing on the
functionality of the software.

> > I believe you saw these in the Emacs 25 manual.
> 
> No, my reference is version updated for 26.2, downloaded from official
> Emacs website with manuals.  For this e-mail I also looked into HTML
> version.

Thanks, this wasn't obvious to me.

> In BASIC.TEXI (L119):
> # curved quotes @t{’}, @t{“} and @t{”}, respectively.  Also, a working
> While @t{...} works for
>    single quotes - both curved (#x2018 & #x2019), probably including x2
>    grave accent, including x2
>    apostrophe, including x2
> making all of them curved and in typewriter shape in PDF, it fails to
> show LEFT (#x201c) and RIGHT (#x201d) DOUBLE QUOTATION MARK, and
> displays instead BACKSLASH and QUOTATION MARK (#x22).  It also works
> for QUOTATION MARK - @t{"}.  An ugly way to fix it would be @t{``} and
> @t{''}, but I think it's not an option.

@t{} is the best trick we have for these characters, so if it doesn't
work, someone will have to suggest a better way and verify it works in
PDF.  At the time we tried other methods, but AFAIR they were worse.

> In BASIC.TEXI - LINE 121:
> - and inserts `.  To see which characters have @kbd{C-x 8} ...
> + and inserts @t{‘}.  To see which characters have @kbd{C-x 8} ...
> Just like in L115.  This bug is present in HTML version as well.

Thanks, fixed.

> As for 1st occurrence in BASIC.TEXI - L149:
> # accent and apostrophe @t{`like this'}, it is converted to a form
> It could be corrected with @kbd{`}@t{like this}@kbd{'}.  Looks good
> in HTML.

Does @kbd{`like this'} work?  I don't want to use @t here, as this is
keyboard input.

> As for 3rd occurrence in BASIC.TEXI - L151:
> # commands.  Similarly, typing a quotation @t{``like this''} using
> As above - @kbd{``}@t{like this}@kbd{''}...  Looks bad in HTML.

Does @kbd{``like this''} work?

> In DISPLAY.TEXI - L1560:
> #  If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
> Well here we have @samp{...} instead of @t{...}, which also fails to
> show “ and ”, displaying instead \ and " (just like @t{...}).  But
> it looks good in HTML.

I changed them all to use @t{}.

> In TEXT.TEXI - L427:
> # using straight apostrophes @t{'like this'} or double-quotes @t{"like
> Similar to above example, @kbd{'}@t{like this}@kbd{'}.  Looks good in
> HTML.

I don't understand why do we need to move away from @t{}.  the comment
clearly says that @t{} was found to do the job here.  What am I
missing?

> In TEXT.TEXI - L429:
> # left and right single or double quotation marks `@t{like this}' or
> Switch to - @t{‘like this’} - with #x2018 & #x2019.

Why?  `..' is converted by TeX to curve single quotes, and ``..'' to
curve double quotes.  What do you see in the PDF?

> In TEXT.TEXI - L442-443:
> - type characters it optionally converts @t{`} to ‘, @t{'} to ',
> - @t{``} to ``, and @t{''} to ''.  It's possible to change the
> + type characters it optionally converts @kbd{`} to @t{‘}, @kbd{'} to @t{’},
> + @kbd{``} to ??, and @kbd{''} to ??.  It's possible to change the
> Of course I don't know what to put for “ and ”, so I put ?? there.
> Also it looks bad in HTML.

I did what I could here.

> > I don't see anything wrong with the current typeface, so I left it
> > alone.
> 
> In BASIC.TEXI - L116 we have:
>     @code{U+2018} LEFT SINGLE QUOTATION MARK
> In SEARCH.TEXI - L1313-1314 and L1319-1320 we have:
>     @sc{u+249c parenthesized latin small letter a}
>     @sc{u+2100 account of}
>     @sc{u+fb00 latin small ligature ff}
> In TEXT.TEXI - L430 (inside footnote) we have:
>     U+2018 LEFT SINGLE QUOTATION MARK
>     U+2018 RIGHT SINGLE QUOTATION MARK <--- this has wrong code!
>     U+201C LEFT DOUBLE QUOTATION MARK
>     U+201D RIGHT DOUBLE QUOTATION MARK
> So, 3 different styles.

We need to use a consistent style, that's true.

I think the @sc style is the best, because that's how the Unicode
Standard itself typesets the names in its printed version.

> I think @code{...} around Unicode code and uppercase "U" is a must.

@sc produce capital letters, so that part is OK.  As for @code, I
don't agree, and neither does the Unicode Standard.  Eventually, this
is a judgment call, so it's not a big deal that we don't agree.

> >> 6.  In INFO 15.1.1 Basics of Incremental Search:
> >> - ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g C-g’ (‘isearch-abort’).
> >> + ‘<ESC> <ESC> <ESC>’ (‘isearch-cancel’) or ‘C-g’ (‘isearch-abort’).
> >> Because `view-lossage' and `describe-bindings' and the last paragraph
> >> of 15.1.4 say: `C-g'.
> >
> > I left this unaltered, because in some cases you do need to type C-g
> > twice, so doing it twice always is safer.
> 
> Well I think the last paragraph of 15.1.4 pointed by me explains this
> behaviour.  It exactly says that sometimes C-g needs to be typed twice
> to exit search.  That's why I'm sticking to my version, unless you had
> other cases in mind.  And "isearch-abort" is literally binded to "C-g"
> so it may rise questions.

This is a user manual, not a mathematical paper, it doesn't have to be
rigorously correct.  It must be useful, though, and I think the
current text is more useful because it avoids possible confusion, even
though the users may pay one more keystroke.  Okay?

Thanks.

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

[Sebastian Urban]

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

> @t{} is the best trick we have for these characters, so if it doesn't
> work, someone will have to suggest a better way and verify it works in
> PDF.  At the time we tried other methods, but AFAIR they were worse.

Hmmm... if I use @t{“} (but without \rawbackslash \plainfrenchspacing)
or {\ttfamily “} or \texttt{“} in my 'test.tex' -> 'test.pdf' it
prints left double quotation mark correctly (i.e. in typewriter
shape), so... maybe there is something wrong with \rawbackslash or
\plainfrenchspacing or you used some older tex distribution with bug?

Also '\tt' inside @t{} as stated in "LATEX2e: An unofficial reference
manual" (November 2018) is "older version of font switching", so maybe
try newer - '\ttfamily', unless this was intentional.

As I mentioned before @t{``} and t@{''} would do the job, but I think
putting specific characters, i.e. “ and ” is intended.

> Does @kbd{`like this'} work?  I don't want to use @t here, as this is
> keyboard input.
> ...
> Does @kbd{``like this''} work?

Hmmm... I still don't know how to turn texi to pdf, so please don't
expect 100% answers, but I'm guessing it could work.  Also you forgot
about 4th occurrence there, but this is l/r double quotation mark
problem so...

>> In DISPLAY.TEXI - L1560:
>> #  If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
>> Well here we have @samp{...} instead of @t{...}, which also fails to
>> show “ and ”, displaying instead \ and " (just like @t{...}).  But
>> it looks good in HTML.
>
> I changed them all to use @t{}.

Please revert this change.  I'm not sure what is the role of @samp{},
but they are everywhere in the manual.  I think they exist to
distinguish inserted (by something/someone in Emacs) characters that
are not part of the main text - they differ form @t{}, because they
add l/r single quotation marks in main (normal) text shape around
character.  With them we have problem only with l/r double quotation
mark, with @t{} problem won't be fixed and it'll cause additional
problems with some of the rest of quotes in this part of text.

Also I'm beginning to think, that our quotes should use @samp rather
than @t.  For example in "Inserting text" chapter if something inserts
thing, this thing is using @samp: user inserts ordinary graphic
character ‘a’, ‘B’, ‘3’, ‘=’, "C-q DEL" inserts ‘DEL’, "C-q 1 0 1 B"
inserts ‘AB’.  Maybe @t{} with "quotes" is mistake.

> In PDF 22.5 Quotation Marks:
> ...
> I don't understand why do we need to move away from @t{}.  the comment
> clearly says that @t{} was found to do the job here.  What am I
> missing?

Text says "using straight apostrophes" and with @t{'like this'} we'll
get curved ones (attached "pic2").  So @kbd{'like this'} should be ok.

> Why?  `..' is converted by TeX to curve single quotes, and ``..'' to
> curve double quotes.  What do you see in the PDF?

Yes, but they are in main text shape, not typewriter (again "pic2").

>> In TEXT.TEXI - L442-443:
> ...
> I did what I could here.

There will be problem of l/r double quotation mark, but it will look
better than before patch, so for now it's good.

> In TEXT.TEXI - L448:
> ...
> In TEXT.TEXI - L469:

You forgot about these, I cannot think of a solution for them.  First
one uses @code{} and I have no idea how it works, first apostrophe is
ok, so maybe just type @code{'(?‘ ?’ ?“ ?”)}?  Second one is typical
l/r double quotation mark, you could change it to @t{“} and @t{”} - it
won't fix it, but there will be some unification of bugs. :)

====================

As for Unicode, after reading your explanation and checking "The
Unicode Standard Version 12.0 – Core Specification" they seem to use
small caps for the name that is written in lowercase and main text
font for code with uppercase 'U' and letters if any in the code.

I can agree for small caps for name (lowercase!), but for code we
should go with @code{} - reason for this is that there are other
Unicode codes in the manual and they have @code{} "face", also
with main text or small caps Unicode code looks uglier (depends on
font) - letters are wider than numbers (sometimes higher), while with
typewriter (@code{}) they are equal.

So, my choice is:
@code{U+201D} @sc{right double quotation mark}

But if you really want to go with how Unicode docs do it, then:
U+201D @sc{right double quotation mark}

I made quick comparison:
\texttt{U+201D} \textsc{right double quotation mark}\\
\texttt{U+201D} \textsc{RIGHT DOUBLE QUOTATION MARK}\\
U+201D \textsc{right double quotation mark}\\
U+201D \textsc{RIGHT DOUBLE QUOTATION MARK}\\
\textsc{u+201d right double quotation mark}\\
\textsc{U+201D RIGHT DOUBLE QUOTATION MARK}
Each line corresponds to the line in "pic3".

====================

As for last part...

> This is a user manual, not a mathematical paper, it doesn't have to be
> rigorously correct.  It must be useful, though, and I think the
> current text is more useful because it avoids possible confusion, even
> though the users may pay one more keystroke.  Okay?

Well, maybe someone else will bring this up again in the future, until
then - OK.


In the meantime, I shouldn't do it but it's something similar so...

In INFO 15.10.4 (description of 'comma'):
... You can also type ‘C-x u’ to undo the replacement; this exits the
‘query-replace’,...
I just want to point out that other undo commands also work,
so maybe:
... You can also type any undo command to undo the replacement;...
or maybe combine both:
... You can also type any undo command (e.g. 'C-x u') to undo the...
Or is it nitpicking again? :)

[-- Attachment #2: pic3.png --]
[-- Type: image/png, Size: 26117 bytes --]

[-- Attachment #3: pic2.png --]
[-- Type: image/png, Size: 58519 bytes --]

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 35885@debbugs.gnu.org
> Date: Wed, 5 Jun 2019 12:40:29 +0200
> 
> > @t{} is the best trick we have for these characters, so if it doesn't
> > work, someone will have to suggest a better way and verify it works in
> > PDF.  At the time we tried other methods, but AFAIR they were worse.
> 
> Hmmm... if I use @t{“} (but without \rawbackslash \plainfrenchspacing)
> or {\ttfamily “} or \texttt{“} in my 'test.tex' -> 'test.pdf' it
> prints left double quotation mark correctly (i.e. in typewriter
> shape), so... maybe there is something wrong with \rawbackslash or
> \plainfrenchspacing or you used some older tex distribution with bug?
> 
> Also '\tt' inside @t{} as stated in "LATEX2e: An unofficial reference
> manual" (November 2018) is "older version of font switching", so maybe
> try newer - '\ttfamily', unless this was intentional.

Sorry, I don't understand what this means in practice.  We don't use
TeX/LaTeX in the manuals, we use Texinfo, so any raw TeX commands
could only come from texinfo.tex.  Is that where you saw \rawbackslash
etc.?  If not, where did you see them?

> As I mentioned before @t{``} and t@{''} would do the job, but I think
> putting specific characters, i.e. “ and ” is intended.

Yes, we intend to put these specific characters.

> > Does @kbd{`like this'} work?  I don't want to use @t here, as this is
> > keyboard input.
> > ...
> > Does @kbd{``like this''} work?
> 
> Hmmm... I still don't know how to turn texi to pdf, so please don't
> expect 100% answers, but I'm guessing it could work.

I changed that to @kbd already, so I guess we should leave that for
now, and wait for complaints.

> Also you forgot about 4th occurrence there, but this is l/r double
> quotation mark problem so...

That's why I didn't do anything about it, yes.

> >> In DISPLAY.TEXI - L1560:
> >> #  If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
> >> Well here we have @samp{...} instead of @t{...}, which also fails to
> >> show “ and ”, displaying instead \ and " (just like @t{...}).  But
> >> it looks good in HTML.
> >
> > I changed them all to use @t{}.
> 
> Please revert this change.  I'm not sure what is the role of @samp{},
> but they are everywhere in the manual.

@samp is used a lot, but there's no reason to use it in the above
context.  If nothing else, it looks badly in Info, because it produces
an extra pair of quotes.  I used @t{} because it produces the best
results with quotes, AFAIR.

> I think they exist to distinguish inserted (by something/someone in
> Emacs) characters that are not part of the main text - they differ
> form @t{}, because they add l/r single quotation marks in main
> (normal) text shape around character.  With them we have problem
> only with l/r double quotation mark, with @t{} problem won't be
> fixed and it'll cause additional problems with some of the rest of
> quotes in this part of text.

Once again, I think @t produces the best results with quotes.  That
was AFAIR our conclusion from when we worked on this issue during
development of Emacs 26.1.  If you can show that the PDF which is
produced by that is incorrect, then we could try other methods, but
they all require producing PDF and examining the results, there's no
"correct" and "incorrect" method here by any other criteria.

> Also I'm beginning to think, that our quotes should use @samp rather
> than @t.  For example in "Inserting text" chapter if something inserts
> thing, this thing is using @samp: user inserts ordinary graphic
> character ‘a’, ‘B’, ‘3’, ‘=’, "C-q DEL" inserts ‘DEL’, "C-q 1 0 1 B"
> inserts ‘AB’.  Maybe @t{} with "quotes" is mistake.

That's not how I recollect this.  I think we originally did use @samp,
but moved to @t in the case of quotes because @samp gave sub-optimal
or even incorrect results.

> > In PDF 22.5 Quotation Marks:
> > ...
> > I don't understand why do we need to move away from @t{}.  the comment
> > clearly says that @t{} was found to do the job here.  What am I
> > missing?
> 
> Text says "using straight apostrophes" and with @t{'like this'} we'll
> get curved ones (attached "pic2").  So @kbd{'like this'} should be ok.

I see nothing wrong with pic2, that's just how PDF renders "straight
apostrophes".  So I see no reason to move away from @t in this case.

> > Why?  `..' is converted by TeX to curve single quotes, and ``..'' to
> > curve double quotes.  What do you see in the PDF?
> 
> Yes, but they are in main text shape, not typewriter (again "pic2").

I don't understand what problems you see in the shape, the text as
typeset looks OK to me.

> > In TEXT.TEXI - L448:
> > ...
> > In TEXT.TEXI - L469:
> 
> You forgot about these, I cannot think of a solution for them.

I didn't forget, I just didn't know what to do, so I did nothing.

> As for Unicode, after reading your explanation and checking "The
> Unicode Standard Version 12.0 – Core Specification" they seem to use
> small caps for the name that is written in lowercase and main text
> font for code with uppercase 'U' and letters if any in the code.
> 
> I can agree for small caps for name (lowercase!), but for code we
> should go with @code{} - reason for this is that there are other
> Unicode codes in the manual and they have @code{} "face", also
> with main text or small caps Unicode code looks uglier (depends on
> font) - letters are wider than numbers (sometimes higher), while with
> typewriter (@code{}) they are equal.
> 
> So, my choice is:
> @code{U+201D} @sc{right double quotation mark}
> 
> But if you really want to go with how Unicode docs do it, then:
> U+201D @sc{right double quotation mark}

OK, done.

> In INFO 15.10.4 (description of 'comma'):
> ... You can also type ‘C-x u’ to undo the replacement; this exits the
> ‘query-replace’,...
> I just want to point out that other undo commands also work,
> so maybe:
> ... You can also type any undo command to undo the replacement;...
> or maybe combine both:
> ... You can also type any undo command (e.g. 'C-x u') to undo the...
> Or is it nitpicking again? :)

I rearranged the words there to indicate that there other bindings of
'undo'.

Thanks.

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

[Sebastian Urban]

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

  > ...
  > could only come from texinfo.tex.  Is that where you saw \rawbackslash
  > etc.?  If not, where did you see them?

Yes in texinfo.tex, in the definition of @t{} (L2836).

Another idea is that maybe texinfo somehow doesn't recognize “ and ”
and uses ASCII approximations?

  > I changed that to @kbd already, so I guess we should leave that for
  > now, and wait for complaints.

I agree.

  > ... If you can show that the PDF which is produced by that is
  > incorrect, then we could try other methods...

More pictures, all of them are from Emacs manual for 26.2 (that's six
not five).

Pictures from chapter PDF4.1 & INFO7.1 Inserting Text: 'p1', 'p2'.

Pictures from chapter PDF11.19 & INFO14.19 How Text Is Displayed: 'p3'.

Pictures from chapter PDF22.5 & INFO25.5 Quotation Marks: see 'pic2'
from previous e-mail and 'p4', 'p5', 'p6'.

  > That's not how I recollect this.  I think we originally did use @samp,
  > but moved to @t in the case of quotes because @samp gave sub-optimal
  > or even incorrect results.

Ok, but @samp{} shows grave accent ` and apostrophe ' correctly, while
@t{} makes them curved.

  > I see nothing wrong with pic2, that's just how PDF renders "straight
  > apostrophes".  So I see no reason to move away from @t in this case.
  > ...
  > I don't understand what problems you see in the shape, the text as
  > typeset looks OK to me.

See picture 'npic2' (= pic2 + zoom in), clearly:

A. quotes on first /like this/ are curved, they must be straight,
otherwise "... typewriter convention, which quotes using straight
apostrophes..." will make no sense, because we will show incorrect
form.

B. `..' and ``..'' (second in npic2) also must be in typewriter shape
because we want to show how curved quote convention looks like, so
they are part of example and not part of main text (see picture 'p0'
for example of quote that is part of main text).


  >> But if you really want to go with how Unicode docs do it, then:
  >> U+201D @sc{right double quotation mark}
  >
  > OK, done.

Cool, except you need to correct Unicode code for right single
quotation mark form U+2018 to U+2019 (Quotation Marks chapter -
footnote).

  > I rearranged the words there to indicate that there other bindings
  > of 'undo'.

Thanks.



[-- Attachment #2: p1.png --]
[-- Type: image/png, Size: 7333 bytes --]

[-- Attachment #3: p2.png --]
[-- Type: image/png, Size: 24276 bytes --]

[-- Attachment #4: p3.png --]
[-- Type: image/png, Size: 14662 bytes --]

[-- Attachment #5: p4.png --]
[-- Type: image/png, Size: 6391 bytes --]

[-- Attachment #6: p5.png --]
[-- Type: image/png, Size: 6119 bytes --]

[-- Attachment #7: p6.png --]
[-- Type: image/png, Size: 19111 bytes --]

[-- Attachment #8: npic2.png --]
[-- Type: image/png, Size: 27262 bytes --]

[-- Attachment #9: p0.png --]
[-- Type: image/png, Size: 6425 bytes --]

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

[Sebastian Urban]

 > Another idea is that maybe texinfo somehow doesn't recognize “ and ”
 > and uses ASCII approximations?

Small update.  The thing about quotes not being recognized may be good
idea, because when you compile:

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[OT4]{fontenc}
\begin{document}
{\ttfamily “like this”}
\end{document}

with OT4 or OT1 you will get \like this", but when you use 'T1' you
will get l/r double quotation marks.  So the problem may be in font
encoding.

As for straight apostrophe and grave accent someone who knows tex
should look into @kbd{} and @samp{} and @code{} to find what they
have, so they can display straight apostrophe and grave accent in
typewriter shape (i.e. not making them curved), and just apply the
code to @t{}.

I also found in MODES.TEXI - L210:
-example, it requotes text typed @t{`like this'} to text @t{‘like
+example, it requotes text typed @kbd{`like this'} to text @t{‘like
You may fix it just like you did in BASIC.TEXI.

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

[Eli Zaretskii]

> Cc: 35885@debbugs.gnu.org
> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Thu, 6 Jun 2019 23:19:56 +0200
> 
>  > Another idea is that maybe texinfo somehow doesn't recognize “ and ”
>  > and uses ASCII approximations?
> 
> Small update.  The thing about quotes not being recognized may be good
> idea, because when you compile:
> 
> \documentclass{article}
> \usepackage[utf8]{inputenc}
> \usepackage[OT4]{fontenc}
> \begin{document}
> {\ttfamily “like this”}
> \end{document}
> 
> with OT4 or OT1 you will get \like this", but when you use 'T1' you
> will get l/r double quotation marks.  So the problem may be in font
> encoding.
> 
> As for straight apostrophe and grave accent someone who knows tex
> should look into @kbd{} and @samp{} and @code{} to find what they
> have, so they can display straight apostrophe and grave accent in
> typewriter shape (i.e. not making them curved), and just apply the
> code to @t{}.

I'll leave this to someone who knows TeX.

> I also found in MODES.TEXI - L210:
> -example, it requotes text typed @t{`like this'} to text @t{‘like
> +example, it requotes text typed @kbd{`like this'} to text @t{‘like
> You may fix it just like you did in BASIC.TEXI.

Fixed, thanks.

>   >> But if you really want to go with how Unicode docs do it, then:
>   >> U+201D @sc{right double quotation mark}
>   >
>   > OK, done.
> 
> Cool, except you need to correct Unicode code for right single
> quotation mark form U+2018 to U+2019 (Quotation Marks chapter -
> footnote).

Fixed.

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 35885@debbugs.gnu.org
> Date: Thu, 6 Jun 2019 11:49:33 +0200
> 
>   > ... If you can show that the PDF which is produced by that is
>   > incorrect, then we could try other methods...
> 
> More pictures, all of them are from Emacs manual for 26.2 (that's six
> not five).

OK, thanks.  Assuming that you have the latest Texinfo and the latest
texinfo.tex installed, feel free to propose specific patches for each
of the problematic places for which you have a satisfactory solution.
Then let's use those patches to fix the cases we know how, and leave
the rest for a better day.

I don't think it makes sense to continue discussing this one place at
a time, because I, for one, am losing context and need to go several
messages back to understand what is being discussed and why.

Thanks again for your efforts.

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

[Sebastian Urban]

> I don't think it makes sense to continue discussing this one place
> at a time, because I, for one, am losing context and need to go
> several messages back to understand what is being discussed and why.

Alright, the following bug(?) is the last one in this thread form me,
i.e. I'll consider this thread closed and if I find anything new (or
a solution to quotes) I'll send new bug report.

In KILLING.TEXI - L125-127:
  leaves @var{n} spaces before point if @var{n} is positive; if @var{n}
  is negative, it deletes newlines in addition to spaces and tabs,
-leaving @var{-n} spaces before point.  The command @code{cycle-spacing}
+leaving @var{n} spaces before point.  The command @code{cycle-spacing}

There 'n' stands just for number of spaces, so no need for negative
or positive mark.  Also documentation string in SIMPLE.EL for
'just-one-space' will need correction, because there is '-N'.

Maybe we could even abridge whole sentence to something like this:

With a positive numeric argument @var{n}, it leaves @var{n} spaces
before point; if @var{n} is negative, it also deletes newlines.

Unless it works differently than I think it does.

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 35885@debbugs.gnu.org
> Date: Mon, 10 Jun 2019 12:30:52 +0200
> 
> In KILLING.TEXI - L125-127:
>   leaves @var{n} spaces before point if @var{n} is positive; if @var{n}
>   is negative, it deletes newlines in addition to spaces and tabs,
> -leaving @var{-n} spaces before point.  The command @code{cycle-spacing}
> +leaving @var{n} spaces before point.  The command @code{cycle-spacing}
> 
> There 'n' stands just for number of spaces, so no need for negative
> or positive mark.  Also documentation string in SIMPLE.EL for
> 'just-one-space' will need correction, because there is '-N'.

I don't think I understand (and if I do, I disagree).  The text says:

  if N is negative, ... leaving -N spaces before point.

When N is negative, -N is positive, so the original text sounds
correct to me.

> With a positive numeric argument @var{n}, it leaves @var{n} spaces
> before point; if @var{n} is negative, it also deletes newlines.

This has the same problem as omitting the minus sign in your
suggestion above.

Thanks.

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

[Sebastian Urban]

> When N is negative, -N is positive, so the original text sounds
> correct to me.

Of course this way it's correct, but as you wrote few mails before
"This is a user manual, not a mathematical paper (...)" and this
(-1) x (-N) seems like unnecessary burden.  And without it
expressions like "... leaving -N spaces..." or (look below) "mark the
previous −N files" makes no sense.  Readers will more likely to
interpret this '-' as negation of "previous" word.  Just like D. Adams
wrote "(...) it's not obvious - it's easy to misread it.  Of course,
it's not possible to leave a negative number of spaces (...).
A careful reader will figure it out, but that might mean having to
read it more than once."

I was curious how it looks in other examples where 'N' is present,
here is the list:

1. In INFO @ 11.2 Commands to Mark Textual Objects:
A negative argument moves the mark back by N words.

2. In INFO @ 12.1.2 Killing by Lines:
With a negative argument −N, it kills N lines preceding the current
line, together with the text on the current line before point.

3. In INFO @ 14.2 Recentering:
A negative argument -N puts point N lines from the bottom of the
window.

4. In INFO @ 25.2 Sentences
... with a negative argument −N, it kills back to the beginning of the
Nth preceding sentence.

5. In INFO @ 26.2.2 Moving by Defuns:
‘C-M-a’ with a negative argument −N moves forward N times to the next
beginning of a defun.

6. In INFO @ 26.5.1 Comment Commands:
A positive argument N adds N delimiters, while a negative argument -N
removes N delimiters.
...
With a positive prefix argument N, it operates on N lines starting
with the current one; with a negative N, it affects N preceding lines.

7. In INFO @ 30.6 Dired Marks vs. Flags :
[at '* m']... (if N is negative, mark the previous −N files)...
...
[at '* u']... (if N is negative, unmark the previous −N files)...
...
[at '* <DEL>']... (if N is negative, unmark the next −N files)...

8. In INFO @ 30.7 Operating on Files:
(If N is negative, the command operates on the −N files preceding the
current line.)

--- end of examples ---

So, in 2., 3., 4., 5., 6.(1st), we have pattern of "negative argument
-N ... something N something..."

In 1. it's something similar but without '-N' just "negative
argument", also 6.(2nd) is something similar but 'N' doesn't have
minus sign.

But in 7. and 8. (and the one I already sent) we have "if N is
negative... something -N something".

So, after looking at more examples, I think the best idea would be to
go with the most used pattern, therefore:
    - add '-N' to 1.,
    - add minus sign do 6.(2nd),
    - replace - in 7., 8., and the one I sent - "if N is negative"
      with "with negative argument -N" then change '-N' to 'N' in the
      rest of each sentence.

There is also a problem of minus sign, or to simply put - lack of it
in 3. and 6.(1st) and the one I sent - there we can see "hyphen-minus"
(#x2d).  In other cases it is "minus sign" (#x2212).

If we agree on this I could send message with "In FILENAME.TEXI
L?-? change this line to this" if it helps you (I don't know how
to make normal patches, sorry).

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 35885@debbugs.gnu.org
> Date: Tue, 11 Jun 2019 12:32:36 +0200
> 
> So, in 2., 3., 4., 5., 6.(1st), we have pattern of "negative argument
> -N ... something N something..."
> 
> In 1. it's something similar but without '-N' just "negative
> argument", also 6.(2nd) is something similar but 'N' doesn't have
> minus sign.
> 
> But in 7. and 8. (and the one I already sent) we have "if N is
> negative... something -N something".
> 
> So, after looking at more examples, I think the best idea would be to
> go with the most used pattern, therefore:
>     - add '-N' to 1.,
>     - add minus sign do 6.(2nd),
>     - replace - in 7., 8., and the one I sent - "if N is negative"
>       with "with negative argument -N" then change '-N' to 'N' in the
>       rest of each sentence.
> 
> There is also a problem of minus sign, or to simply put - lack of it
> in 3. and 6.(1st) and the one I sent - there we can see "hyphen-minus"
> (#x2d).  In other cases it is "minus sign" (#x2212).

I fixed the inconsistencies with the minus sign vs hyphen.  As for the
few examples saying "if N is negative <do something> −N times": sorry,
I cannot see anything wrong with such wording, so I left those few
examples alone.

Thanks.

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

[Sebastian Urban]

> As for the few examples saying "if N is negative <do something> −N
> times": sorry, I cannot see anything wrong with such wording, so
> I left those few examples alone.

Well I don't think I can explain this more clearly, so I'm going to
put this next to 'C-g C-g' "problem", i.e. we will wait for other
opinions if they ever appear.  Until then I'll consider this thread
closed.

And of course thank you for many other fixes from this thread.

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

[Drew Adams]

> > As for the few examples saying "if N is negative <do something> −N
> > times": sorry, I cannot see anything wrong with such wording, so
> > I left those few examples alone.
> 
> Well I don't think I can explain this more clearly, so I'm going to
> put this next to 'C-g C-g' "problem", i.e. we will wait for other
> opinions if they ever appear.  Until then I'll consider this thread
> closed.

"I cannot see anything wrong with such wording", versus
it could be improved a bit to avoid confusion like that
evidenced by this bug report.

A user reading "...-N..." CAN easily misread it.  Yes,
MISread.  There is not "anything wrong" with it, in the
sense that if you read it right you won't misunderstand
it.  But that's a low bar, and Emacs can do better.

To read it right you have to have grasped and recalled
that N is a placeholder for an integer value, and in
the context of that `-N' occurrence it is a placeholder
for a negative integer.

Understanding that that's the case, a reader will also
correctly interpret the `-' as a minus sign (not, e.g.,
as a dash or hyphen or whatever else in ordinary text).

MISunderstanding, a reader can easily not interpret the
math expression `-N' as math at all.  (And note that
it's not within `...', so it's likely not taken as Lisp
math.

If we instead use `(abs N)', that makes clear - yes, as
a reminder or a pay-attention note - that N is a number
and the result of that expression is its absolute value.
That clues a reader into the fact that N might be - in
fact is in this case - negative.

It's not about proving that the `-N' wording is guilty
or defending its innocence in a court case.  It's about
making things a little clearer.  It's about seeing it
from the point of view of someone who might misread it.

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Fri, 24 May 2019 17:59:09 +0200
> 
> I gathered few mistakes in the manual and 3 proposals for it, in one
> report, because they are small (maybe except 2nd and 3rd proposal) and
> sending them one by one would be spam-ish.  I found them in GNU Emacs
> 25.2.1 (i686-w64-mingw32) of 2017-04-24 and PDFs updated for 25.2 and
> 26.2.

Thanks.  I fixed most of the issues, see below.

> 1.  In INFO 11.7 Disabling Transient Mark Mode:
> - ‘M-x transient-mark-mode’, or with the ‘Active Region Highlighting’ menu
> + ‘M-x transient-mark-mode’, or with the ‘Highlight Active Region’ menu
> This is correct name of menu item.
> 
> 2.  In INFO 13.2 Saving Text in Registers:
> - activating it.  With a numeric argument, it instead puts point before
> + activating it.  With a prefix argument, it instead puts point before
> Help window of 'insert-register' has prefix arg.
> 
> 3.  In INFO 13.3 Saving Rectangles in Registers:
> -      (‘copy-rectangle-to-register’).  With numeric argument, delete it
> +      (‘copy-rectangle-to-register’).  With prefix argument, delete it
> Help window of 'copy-rectangle-to-register' has prefix arg.

Fixed these.

> 4.  In INFO 14.2 Recentering:
> in paragraph starting with "You can also give ‘C-l’ a prefix
> argument.", expressions:
>     - "recenters point" should be "recenters line"
>     - "puts point" (3 occurrences) should rather be "moves current
>     line", because point is moved this way by 'M-r'
>     ('move-to-window-line-top-bottom') and also in help window for
>     'recenter-top-bottom' we have "move current line".

I used a different wording, like "move point's line to ...".

> 5.  In INFO 14.19 How Text Is Displayed:
> - have an integer value between 1 and 1000, inclusive.  Note that how the
> + have an integer value between 1 and 1000, inclusive.  Note how the
> I think "that" is unnecessary, "Note that how the tab character
> (...)", will change into "Note how the tab character (...)".  Although
> I'm not sure of it, maybe current form is correct?

The current text is correct, but it's confusing.  I reworded it.

> 1.  In PDF 4.1 Inserting Text:
> in paragraph starting with "A few common Unicode characters can be
> inserted (...)" (near word "respectively"), "left double quotation
> mark" (curved) is displayed as "backslash" and "right double quotation
> mark" (curved) is displayed as "straight double quotes".  In INFO it
> looks ok.
> 
> 2.  In PDF 4.1 Inserting Text:
> in paragraph starting with "In some contexts, if you type a quotation
> (...)", display of quotes is messed up, quotes surrounding Nth
> occurrence of "like this" should be:
>     - 1st - "grave accent" and "apostrophe",
>     - 2nd - is ok,
>     - 3rd - 2x "grave accent" and 2x "apostrophe",
>     - 4th - "left double quotation mark" (curved) and "right double
>       quotation mark" (curved)
> Or just look into INFO, it's ok there.
> 
> 3.  In PDF 11.19 How Text Is Displayed:
> in last paragraph, first line, "left double quotation mark" (curved)
> is displayed as "backslash" and "right double quotation mark" (curved)
> is displayed as "straight double quotes".  In INFO it looks ok.

I believe you saw these in the Emacs 25 manual.  We did a lot of fixes
regarding these special characters in preparation for Emacs 26
release, so please be sure to look in the latest version (it is best
to checkout the current emacs-26 branch and produce PDF from its
sources).  I didn't change any of the issues with quotes, as I don't
have a PDF version of the manual handy, and couldn't myself check
whether there are leftovers.

> 1.  Emphasize a word
> In both INFO(7.10 Numeric arguments) and PDF(4.10 Numeric Arguments),
> in last paragraph, there is a word "before", I suggest to emphasize
> this word (or maybe make it slanted, up to you).  It will have
> stronger (visual) connection to slanted "prefix argument".

I did that.

> 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.

Thanks.

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

[Sebastian Urban]

[-- 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

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

[Sebastian Urban]

I'm reopening this bug, because last time I unarchived it, it was
automatically archived after 28d.

Since TEXINFO.TEX ver. 2020-05-14, this:

> --- 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

can be simplified to:

--8<---------------cut here---------------start------------->8---
--- old/emacs.texi
+++ new/emacs.texi
@@ -99,10 +99,13 @@

 @end titlepage

+@headings double

 @summarycontents
 @contents


 @ifnottex
 @node Top
--8<---------------cut here---------------end--------------->8---


S. U.

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Thu, 13 Aug 2020 11:11:15 +0200
> 
> I'm reopening this bug, because last time I unarchived it, it was
> automatically archived after 28d.
> 
> Since TEXINFO.TEX ver. 2020-05-14, this:
> 
> > --- 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
> 
> can be simplified to:
> 
> --8<---------------cut here---------------start------------->8---
> --- old/emacs.texi
> +++ new/emacs.texi
> @@ -99,10 +99,13 @@
> 
>  @end titlepage
> 
> +@headings double

Is it certain that the Emacs manuals are always processed using the
texinfo.tex that comes with that same version of Emacs?

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

[Sebastian Urban]

> Is it certain that the Emacs manuals are always processed using the
> texinfo.tex that comes with that same version of Emacs?

I'm not sure if I understand.  I don't know how they are build at all
by Emacs devs, e.g. which texinfo.tex version is chosen.  Right now
in "root/doc/misc" (Emacs repo) texinfo.tex version is: 2020-06-25.17
(master) and 2019-09-24.13 (emacs-27) and 2017-12-26.21 (emacs-26).
My changes require at least 2020-05-14.


S. U.

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

[Eli Zaretskii]

> Cc: 35885@debbugs.gnu.org
> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Thu, 13 Aug 2020 16:06:37 +0200
> 
> > Is it certain that the Emacs manuals are always processed using the
> > texinfo.tex that comes with that same version of Emacs?
> 
> I'm not sure if I understand.  I don't know how they are build at all
> by Emacs devs, e.g. which texinfo.tex version is chosen.  Right now
> in "root/doc/misc" (Emacs repo) texinfo.tex version is: 2020-06-25.17
> (master) and 2019-09-24.13 (emacs-27) and 2017-12-26.21 (emacs-26).
> My changes require at least 2020-05-14.

In general, texinfo.tex comes with the Texinfo package, and is
installed in some system-wide directory.  That we in Emacs have the
latest unreleased version is fine, but if someone processes the Emacs
manual with the older system-wide version, they will stumble on this
new feature.

However, I don't know if this is a real danger, hence my question.

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

[Sebastian Urban]

>>> Is it certain that the Emacs manuals are always processed using
>>> the texinfo.tex that comes with that same version of Emacs?
>>
>> (...)
>
> In general, texinfo.tex comes with the Texinfo package, and is
> installed in some system-wide directory.  That we in Emacs have the
> latest unreleased version is fine, but if someone processes the
> Emacs manual with the older system-wide version, they will stumble
> on this new feature.
>
> However, I don't know if this is a real danger, hence my question.

Ah, someone may use texinfo.tex form Texinfo package instead of - e.g
- newest one, got it.

Well, texinfo.tex is in emacs.texi.tar.gz (manual in TEXI format), so
I think that's like saying: "use this version of texinfo.tex (or maybe
newer)", and if someone uses older... well, his choice, but it may not
work.

Therefore that's not a problem, I guess.


S. U.

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

[Lars Ingebrigtsen]

Sebastian Urban <mrsebastianurban@gmail.com> writes:

> 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):

[...]

>  starting with @kbd{C-x 8}.  For example, @kbd{C-x 8 [} inserts @t{^X}
>  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

It looks like this patch has been severely mangled?  There's characters
like ^X in it (where there should be a `, I think)?

Could you re-send the patch?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sat, 15 Aug 2020 15:18:55 +0200
> Cc: 35885@debbugs.gnu.org
> 
> >  starting with @kbd{C-x 8}.  For example, @kbd{C-x 8 [} inserts @t{^X}
> >  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
> 
> It looks like this patch has been severely mangled?  There's characters
> like ^X in it (where there should be a `, I think)?
> 
> Could you re-send the patch?

Beware of the changes that are supposed to "fix" how quote characters
are typeset: there be dragons there.  We've done quite a lot of fixing
that during Emacs 26 release, and found out that there are different,
sometimes contradictory, requirements to have those display nicely in
HTML and in PDF.  But Sebastian keeps pushing for his changes although
I told him long ago they are not necessarily TRT.

If you want to install those changes now, be sure to produce Info,
HTML, and PDF versions of the manual, and examine the results of each
change in all three formats, before you decide whether installing them
is a good idea.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Beware of the changes that are supposed to "fix" how quote characters
> are typeset: there be dragons there.  We've done quite a lot of fixing
> that during Emacs 26 release, and found out that there are different,
> sometimes contradictory, requirements to have those display nicely in
> HTML and in PDF.  But Sebastian keeps pushing for his changes although
> I told him long ago they are not necessarily TRT.

I wasn't necessarily going to apply anything, but to see what he's
proposing, it's easier if the patches aren't mangled.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Sebastian Urban]

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

 > It looks like this patch has been severely mangled?  There's
 > characters like ^X in it (where there should be a `, I think)?

I'm sending them again, if it won't work, could you download them from:
https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-05/msg00618.html
?

[-- 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

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

[Lars Ingebrigtsen]

Sebastian Urban <mrsebastianurban@gmail.com> writes:

>> It looks like this patch has been severely mangled?  There's
>> characters like ^X in it (where there should be a `, I think)?
>
> I'm sending them again, if it won't work, could you download them from:
> https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-05/msg00618.html
> ?

The patches survived this time.  Gmail is notorious for destroying
patches, but including them as attachments (as you did here) usually
works.

> -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

Looking at the thread I don't think this @kbd -> @w{@kbd thing was
discussed?  What does that fix?

> -accent and apostrophe @kbd{`like this'}, it is converted to a form

[...]

> +accent and apostrophe @verb{|`like this'|}, it is converted to a form

Neither can I see a discussion of the @kbd -> @verb{| change.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Sebastian Urban]

>> -Similarly, @kbd{C-x 8 ]}, @kbd{C-x 8 @{} (...)
>> +Similarly, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} (...)
>
> Looking at the thread I don't think this @kbd -> @w{@kbd thing was
> discussed?  What does that fix?

As I wrote in original message describing these changes: "1st change
@w - in PDF this key is split on two pages, which looks bad."  The @w
prevents line breaking.  Or open Emacs 26.3 PDF manual on page 38
(bottom right) - 39 (top left), and see for yourself.

I just wanted to prevent this, so that shortcut is in one place.
I also just built PDF:
- with TEXI files from emacs-27 branch,
- with texinfo.tex: 2020-06-25.17,
- without my changes,
and "C-x 8 ]" is still split.

>> -accent and apostrophe @kbd{`like this'}, it is converted (...)
>> [...]
>> +accent and apostrophe @verb{|`like this'|}, it is converted (...)
>
> Neither can I see a discussion of the @kbd -> @verb{| change.

Again, as I wrote:
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;
Unfortunately (for me), in HTML, @kbd prints text in "italics", while
@verb doesn't.

So, in case of @verb, the choice is:
- stay with @kbd, and ignore extra quotes in plaintext, which are ok
   for shortcuts, but with text surrounded with ``...'' they look
   unnecessary and confusing,
- pick @verb for ``...'' as an exception, but without "italics" in
   HTML.

Although, there is other example later (in TEXT.TEXI), where @verb
would do a nice job in plaintext.  As I described it:
    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 ”."


S. U.

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

[Lars Ingebrigtsen]

Sebastian Urban <mrsebastianurban@gmail.com> writes:

> As I wrote in original message describing these changes: "1st change
> @w - in PDF this key is split on two pages, which looks bad."  The @w
> prevents line breaking.  Or open Emacs 26.3 PDF manual on page 38
> (bottom right) - 39 (top left), and see for yourself.

OK, that sounds reasonable, I guess?  Eli?

>>> -accent and apostrophe @kbd{`like this'}, it is converted (...)
>>> [...]
>>> +accent and apostrophe @verb{|`like this'|}, it is converted (...)
>>
>> Neither can I see a discussion of the @kbd -> @verb{| change.
>
> Again, as I wrote:
> 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;

That is really confusing, yes...  But I was wondering about the |
characters? 

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: 35885@debbugs.gnu.org, Eli Zaretskii <eliz@gnu.org>
> Date: Tue, 18 Aug 2020 16:54:28 +0200
> 
> Sebastian Urban <mrsebastianurban@gmail.com> writes:
> 
> > As I wrote in original message describing these changes: "1st change
> > @w - in PDF this key is split on two pages, which looks bad."  The @w
> > prevents line breaking.  Or open Emacs 26.3 PDF manual on page 38
> > (bottom right) - 39 (top left), and see for yourself.
> 
> OK, that sounds reasonable, I guess?  Eli?

Yes, it is.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> > As I wrote in original message describing these changes: "1st change
>> > @w - in PDF this key is split on two pages, which looks bad."  The @w
>> > prevents line breaking.  Or open Emacs 26.3 PDF manual on page 38
>> > (bottom right) - 39 (top left), and see for yourself.
>> 
>> OK, that sounds reasonable, I guess?  Eli?
>
> Yes, it is.

OK; I've now applied that bit.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Sebastian Urban]

>>>> -accent and apostrophe @kbd{`like this'}, it is converted (...)
>>>> [...]
>>>> +accent and apostrophe @verb{|`like this'|}, it is converted (...)
>>>
>>> Neither can I see a discussion of the @kbd -> @verb{| 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;
>
> That is really confusing, yes...  But I was wondering about the |
> characters?

TEXINFO manual:

    Like LaTeX's '\verb' command, the verbatim text can be quoted using
    any unique delimiter character.  Enclose the verbatim text, including
    the delimiters, in braces.  Text is printed in a fixed-width font:

         How many @verb{|@|}-escapes does one need to print this
         @verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this?

    produces

         How many @-escapes does one need to print this
         @a @b.@c string or @'e?`{}!`\ this?


I would prefer using @verb in these cases, but with good font outer
quotes (printed by the @kbd command) are "curved", so it's bearable.


S. U.

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

[Lars Ingebrigtsen]

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

Sebastian Urban <mrsebastianurban@gmail.com> writes:

>>>    - 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;

Whatever you're using to send emails, it keeps destroying the text,
which makes things hard to follow.  This is what the text looks like to
me:


[-- Attachment #2: Type: image/png, Size: 10365 bytes --]

[-- Attachment #3: Type: text/plain, Size: 429 bytes --]


> I would prefer using @verb in these cases, but with good font outer
> quotes (printed by the @kbd command) are "curved", so it's bearable.

So you think @kbd is fine in this case, after all?

If there's anything remaining you think should be done here, could you
spin new patches and explain each change you want to make?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Sebastian Urban]

 > Whatever you're using to send emails, it keeps destroying the text,
 > which makes things hard to follow.  This is what the text looks like
 > to me:

Thunderbird 68.11.0.  Are you sure it's not something on your end?
Because, here:
https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-08/msg01803.html
it looks OK (in FF, eww).

 >> I would prefer using @verb in these cases, but with good font outer
 >> quotes (printed by the @kbd command) are "curved", so it's bearable.
 >
 > So you think @kbd is fine in this case, after all?

Well, in INFO, go to "(emacs) Inserting Text" and "(emacs) Quotation
Marks" and see for yourself.  Maybe we should stick to @kbd until
someone writes it looks confusing in these cases.

 > If there's anything remaining you think should be done here, could
 > you spin new patches and explain each change you want to make?

By "here" do you mean BASIC.TEXI or all changes?  Let's make the
decision about whether to use or not @verb, then I could update DIFFs.


S. U.

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

[Lars Ingebrigtsen]

Sebastian Urban <mrsebastianurban@gmail.com> writes:

>> Whatever you're using to send emails, it keeps destroying the text,
>> which makes things hard to follow.  This is what the text looks like
>> to me:
>
> Thunderbird 68.11.0.  Are you sure it's not something on your end?
> Because, here:
> https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-08/msg01803.html
> it looks OK (in FF, eww).

Sorry; that was indeed the case -- when interfacing with debbugs via
Emacs, there's some decoding issues with an 8bit
Content-Transfer-Encoding.  I've now reported this as a bug.

>> If there's anything remaining you think should be done here, could
>> you spin new patches and explain each change you want to make?
>
> By "here" do you mean BASIC.TEXI or all changes?  Let's make the
> decision about whether to use or not @verb, then I could update DIFFs.

By "here" I mean "in this bug report".

I have no opinion on whether to use @verb here or not -- perhaps Eli has?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  35885@debbugs.gnu.org
> Date: Thu, 20 Aug 2020 14:44:30 +0200
> 
> I have no opinion on whether to use @verb here or not -- perhaps Eli has?

I don't think we should use @verb in this case, no.

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

[Sebastian Urban]

[-- 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

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

[Eli Zaretskii]

> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, 35885@debbugs.gnu.org
> Date: Thu, 20 Aug 2020 20:24:32 +0200
> 
> 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

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.

> * 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

This is an unrelated change.  Why would we want it?

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

[Sebastian Urban]

>> 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
>
> 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...


The point of changing @samp to @kbd is to get rid of additional curved
quotes, which surrounds the text, i.e. (‘`’ and ‘'’) --> (` and ').

But, since you emphasized, that @kbd is only meant for user input, and
point 2. is more likely an example of how ASCII quotes look, I guess
@samp could stay.  Otherwise, we could use @verb here...  We'll still
need @w to prevent page break inside parens, unless, in this case,
it's acceptable.


The point of changing @t to @kbd is to get ASCII quotes, because @t
prints curved ones, except for " (QUOTATION MARK).  Although, because
in change 3. in DISPLAY.TEXI we are showing an example, not user
input, we could use @samp there.

Also, in change 5. in TEXT.TEXI, even though @t will print ",
i.e. correct symbol, since the sentence says: "Then, typing @t{"}
insert...", I think we should use @kbd as it is user input.

>> * 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
>
> This is an unrelated change.  Why would we want it?

It is related (see https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35885#11):
    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.
    (...)

       These are beyond our control (well, unless we want to write a
       lot of TeX glue in the manual): this is how Texinfo works.

Now, all we need is one line in EMACS.TEXI.

BTW, 2 months ago there was a bug report about it:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=42199


S. U.

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

[Sebastian Urban]

Just a reminder - "This bug report was last modified 58 days ago."

Since it's not that far away from marking it as done, maybe we could
finish it anytime soon?

S. U.

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

[Lars Ingebrigtsen]

Sebastian Urban <mrsebastianurban@gmail.com> writes:

>> 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?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Sebastian Urban]

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

 >>> 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.

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

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

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

[Lars Ingebrigtsen]

Sebastian Urban <mrsebastianurban@gmail.com> writes:

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

Thanks; applied to Emacs 28, and I guess that's all the changes
discussed here, so I'm closing this bug report.  If there are other
issues, opening a new bug report would probably be more efficient than
reopening this one.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Sebastian Urban]

 > Thanks; applied to Emacs 28, and I guess that's all the changes
 > discussed here, so I'm closing this bug report. If there are other
 > issues, opening a new bug report would probably be more efficient
 > than reopening this one.

Looks good, even with TEXINFO.TEX updated to v. 2020-11-25 from MASTER
branch.


BTW, could you take a look at:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=42982#21
This part exactly:

 > Perhaps copy-pasting explanation from SCREEN.TEXI would be a better
 > solution, i.e. instead of
 >    (which is ``control h and then t'')
 > something like this:
 >    (hold down @key{Control} and type @kbd{h}, then let go of
 >    @key{Control} and type @kbd{t})
 > ?

If it's necessary, I'll open a new bug report.


I also believe it is now possible to close this bug report:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=42199
I mean at least the Emacs manual part is done.

--
S. U

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

[Lars Ingebrigtsen]

Sebastian Urban <mrsebastianurban@gmail.com> writes:

>> Perhaps copy-pasting explanation from SCREEN.TEXI would be a better
>> solution, i.e. instead of
>>    (which is ``control h and then t'')
>> something like this:
>>    (hold down @key{Control} and type @kbd{h}, then let go of
>>    @key{Control} and type @kbd{t})
>> ?
>
> If it's necessary, I'll open a new bug report.

Please do.

> I also believe it is now possible to close this bug report:
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=42199
> I mean at least the Emacs manual part is done.

OK; done.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> I don't think I understand (and if I do, I disagree).  The text says:
>   if N is negative, ... leaving -N spaces before point.
> When N is negative, -N is positive, so the original text sounds
> correct to me.

Yes, it's correct.  But it's not obvious - it's
easy to misread it.

Of course, it's not possible to leave a negative
number of spaces (at least I don't know what that
would mean).  A careful reader will figure it out,
but that might mean having to read it more than
once.

I think it would be clearer (by reminding that N
is negative) to say "leaving (abs N) spaces..."

(I do that in some of my doc strings, FWIW.)