From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail
From: Eli Zaretskii <eliz@gnu.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals)
Date: Tue, 04 Jun 2019 18:12:33 +0300
Message-ID: <835zpltme6.fsf@gnu.org>
References: <cf31e2b2-3ad4-57f0-8847-e5f01ff35fc8@gmail.com>
	<f2fff09b-fc97-795b-dc3b-4175c48234db@gmail.com>
	<83k1e2tym6.fsf@gnu.org>
	<e083f8bd-8c77-3558-c373-a8d9d9ef6079@gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226";
	logging-data="97382"; mail-complaints-to="usenet@blaine.gmane.org"
Cc: 35885@debbugs.gnu.org
To: Sebastian Urban <mrsebastianurban@gmail.com>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Jun 04 17:15:32 2019
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Envelope-to: geb-bug-gnu-emacs@m.gmane.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1hYB9v-000PD9-Ok
	for geb-bug-gnu-emacs@m.gmane.org; Tue, 04 Jun 2019 17:15:31 +0200
Original-Received: from localhost ([127.0.0.1]:53906 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1hYB9u-0001Vp-Pz
	for geb-bug-gnu-emacs@m.gmane.org; Tue, 04 Jun 2019 11:15:30 -0400
Original-Received: from eggs.gnu.org ([209.51.188.92]:49994)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1hYB7X-00082u-VN
	for bug-gnu-emacs@gnu.org; Tue, 04 Jun 2019 11:13:05 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1hYB7W-0007CH-Ni
	for bug-gnu-emacs@gnu.org; Tue, 04 Jun 2019 11:13:03 -0400
Original-Received: from debbugs.gnu.org ([209.51.188.43]:60286)
	by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16)
	(Exim 4.71) (envelope-from <Debian-debbugs@debbugs.gnu.org>)
	id 1hYB7W-0007C9-Jx
	for bug-gnu-emacs@gnu.org; Tue, 04 Jun 2019 11:13:02 -0400
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1hYB7W-0002gr-CB
	for bug-gnu-emacs@gnu.org; Tue, 04 Jun 2019 11:13:02 -0400
X-Loop: help-debbugs@gnu.org
Resent-From: Eli Zaretskii <eliz@gnu.org>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Tue, 04 Jun 2019 15:13:02 +0000
Resent-Message-ID: <handler.35885.B35885.155966117210323@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 35885
X-GNU-PR-Package: emacs
Original-Received: via spool by 35885-submit@debbugs.gnu.org id=B35885.155966117210323
	(code B ref 35885); Tue, 04 Jun 2019 15:13:02 +0000
Original-Received: (at 35885) by debbugs.gnu.org; 4 Jun 2019 15:12:52 +0000
Original-Received: from localhost ([127.0.0.1]:45597 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1hYB7L-0002gR-JC
	for submit@debbugs.gnu.org; Tue, 04 Jun 2019 11:12:51 -0400
Original-Received: from eggs.gnu.org ([209.51.188.92]:35530)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <eliz@gnu.org>) id 1hYB7J-0002gD-1x
	for 35885@debbugs.gnu.org; Tue, 04 Jun 2019 11:12:49 -0400
Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:37722)
	by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <eliz@gnu.org>)
	id 1hYB7D-0006xW-VN; Tue, 04 Jun 2019 11:12:44 -0400
Original-Received: from [176.228.60.248] (port=1231 helo=home-c4e4a596f7)
	by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256)
	(Exim 4.82) (envelope-from <eliz@gnu.org>)
	id 1hYB7C-0003FF-5F; Tue, 04 Jun 2019 11:12:43 -0400
In-reply-to: <e083f8bd-8c77-3558-c373-a8d9d9ef6079@gmail.com> (message from
	Sebastian Urban on Tue, 4 Jun 2019 12:48:50 +0200)
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]
X-BeenThere: debbugs-submit@debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]
X-Received-From: 209.51.188.43
X-BeenThere: bug-gnu-emacs@gnu.org
List-Id: "Bug reports for GNU Emacs,
	the Swiss army knife of text editors" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/bug-gnu-emacs/>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org
Original-Sender: "bug-gnu-emacs"
	<bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Xref: news.gmane.org gmane.emacs.bugs:160115
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/160115>

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