GNU bug report logs - #35885
25.2; Few mistakes in Emacs Manual (+ proposals)

Previous Next

Full log

Message #22 received at 35885 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 35885 <at> debbugs.gnu.org
Subject: Re: bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals)
Date: Tue, 04 Jun 2019 18:12:33 +0300

> From: Sebastian Urban <mrsebastianurban <at> gmail.com>
> Cc: 35885 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.