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

From: Sebastian Urban <[email-masked]>
Date: Sat, 22 Aug 2020 12:19:17 +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.

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.