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

From: Sebastian Urban <[email-masked]>
Date: Sun, 16 Aug 2020 15:00:17 +0200

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