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.