From: Sebastian Urban <mrsebastianurban@gmail.com>
To: mrsebastianurban@gmail.com
Cc: 35885@debbugs.gnu.org
Subject: bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals)
Date: Sun, 10 May 2020 22:02:16 +0200 [thread overview]
Message-ID: <c27a8c46-68d3-f9f4-2e92-05e0b6496b53@gmail.com> (raw)
In-Reply-To: <cf31e2b2-3ad4-57f0-8847-e5f01ff35fc8@gmail.com>
[-- Attachment #1: Type: text/plain, Size: 10433 bytes --]
I'm revisiting this bug report, because, thanks to patches to
TEXINFO.TEX by Gavin Smith, I believe we can finally fix the issues
for good. TEXINFO.TEX version >= 2020-05-10.15 is required.
Additionally bug about heading not appearing sometimes on last page of
the chapter (present in official PDF version updated for 26.3), was
fixed as well.
I decided to went through places pointed out in this report, to see if
any changes are needed, here are diffs based on master branch from
03.05.2020 (I also attached them):
------------------------- BASIC.TEXI START -------------------------
--- old/basic.texi 2020-05-03 01:28:18.576838200 +0200
+++ new/basic.texi 2020-05-05 23:07:21.487684600 +0200
@@ -115,7 +115,7 @@
starting with @kbd{C-x 8}. For example, @kbd{C-x 8 [} inserts @t{‘}
which is Unicode code-point U+2018 @sc{left single quotation mark},
sometimes called a left single ``curved quote'' or ``curly quote''.
-Similarly, @kbd{C-x 8 ]}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
+Similarly, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}}
insert the
curved quotes @t{’}, @t{“} and @t{”}, respectively. Also, a working
@key{Alt} key acts like @kbd{C-x 8} (unless followed by @key{RET});
e.g., @kbd{A-[} acts like @kbd{C-x 8 [} and inserts @t{‘}. To see
@@ -146,11 +146,11 @@
how many copies of the character to insert (@pxref{Arguments}).
In addition, in some contexts, if you type a quotation using grave
-accent and apostrophe @kbd{`like this'}, it is converted to a form
-@t{‘like this’} using single quotation marks, even without @kbd{C-x 8}
-commands. Similarly, typing a quotation @kbd{``like this''} using
-double grave accent and apostrophe converts it to a form @t{“like
-this”} using double quotation marks. @xref{Quotation Marks}.
+accent and apostrophe @verb{|`like this'|}, it is converted to a form
+using single quotation marks @t{‘like this’}, even without @kbd{C-x 8}
+commands. Similarly, typing a quotation using double grave accent and
+apostrophe @verb{|``like this''|}, converts it to a form using double
+quotation marks @w{@t{“like this”}}. @xref{Quotation Marks}.
@node Moving Point
@section Changing the Location of Point
------------------------- BASIC.TEXI END -------------------------
1st change @w - in PDF this key is split on two pages, which looks
bad.
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;
- @w, because last example is split between 2 lines;
- I also moved examples to the end of part of the sentence, this
way we have: description followed by an example, instead of
example being in the middle of description.
------------------------- DSIPLAY.TEXI START -------------------------
--- old/display.texi 2020-05-03 01:29:34.852965900 +0200
+++ new/display.texi 2020-05-05 23:00:10.014126600 +0200
@@ -1629,10 +1629,10 @@
@cindex curved quotes, and terminal capabilities
@cindex @code{homoglyph} face
-Emacs tries to determine if the curved quotes @samp{‘} and @samp{’}
+Emacs tries to determine if the curved quotes @t{‘} and @t{’}
can be displayed on the current display. By default, if this seems to
-be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`}
-and @samp{'}), when they appear in messages and help texts, to these
+be so, then Emacs will translate the @acronym{ASCII} quotes @w{(@kbd{`}
+and @kbd{'})}, when they appear in messages and help texts, to these
curved quotes. You can influence or inhibit this translation by
customizing the user option @code{text-quoting-style} (@pxref{Keys in
Documentation,,, elisp, The Emacs Lisp Reference Manual}).
@@ -1641,7 +1641,7 @@
known to look just like @acronym{ASCII} characters, they are shown
with the @code{homoglyph} face. Curved quotes that are known not to
be displayable are shown as their @acronym{ASCII} approximations
-@t{`}, @t{'}, and @t{"} with the @code{homoglyph} face.
+@kbd{`}, @kbd{'}, and @kbd{"} with the @code{homoglyph} face.
@node Cursor Display
@section Displaying the Cursor
------------------------- DSIPLAY.TEXI END -------------------------
Basically, I got rid of @samp in favour of @t and @kbd; the @w
prevents line break after "`".
------------------------- MODES.TEXI START -------------------------
--- old/modes.texi 2020-05-03 01:32:48.773267500 +0200
+++ new/modes.texi 2020-05-05 20:23:41.217738900 +0200
@@ -207,7 +207,7 @@
@item
Electric Quote mode automatically converts quotation marks. For
-example, it requotes text typed @kbd{`like this'} to text @t{‘like
+example, it requotes text typed @verb{|`like this'|} to text @t{‘like
this’}. You can control what kind of text it operates in, and you can
disable it entirely in individual buffers. @xref{Quotation Marks}.
------------------------- MODES.TEXI END -------------------------
Another example surrounded by unnecessary curved quotes in plain text,
fixed by using @verb.
------------------------- TEXT.TEXI START -------------------------
--- old/text.texi 2020-05-03 01:34:10.677385800 +0200
+++ new/text.texi 2020-05-05 23:47:52.987559000 +0200
@@ -421,13 +421,11 @@
@cindex curved quotes
@cindex guillemets
@findex electric-quote-mode
-@c The funny quoting below is to make the printed version look
-@c correct. FIXME.
One common way to quote is the typewriter convention, which quotes
-using straight apostrophes @t{'like this'} or double-quotes @t{"like
-this"}. Another common way is the curved quote convention, which uses
-left and right single or double quotation marks `@t{like this}' or
-``@t{like this}''@footnote{
+using straight apostrophes @verb{|'like this'|} or double-quotes
+@verb{|"like this"|}. Another common way is the curved quote
+convention, which uses left and right single or double quotation marks
+@t{‘like this’} or @t{“like this”}@footnote{
The curved single quote characters are U+2018 @sc{left single quotation
mark} and U+2019 @sc{right single quotation mark}; the curved double
quotes
are U+201C @sc{left double quotation mark} and U+201D @sc{right double
@@ -445,7 +443,7 @@
@code{electric-quote-chars}, a list of four characters, where the
items correspond to the left single quote, the right single quote, the
left double quote and the right double quote, respectively, whose
-default value is @code{'(?@r{`} ?@r{'} ?@r{``} ?@r{''})}.
+default value is @w{@code{'(@w{?}‘ @w{?}’ @w{?}“ @w{?}”)}}.
@vindex electric-quote-paragraph
@vindex electric-quote-comment
@@ -461,7 +459,7 @@
@vindex electric-quote-replace-double
You can also set the option @code{electric-quote-replace-double} to
-a non-@code{nil} value. Then, typing @t{"} insert an appropriate
+a non-@code{nil} value. Then, typing @kbd{"} insert an appropriate
curved double quote depending on context: @t{“} at the beginning of
the buffer or after a line break, whitespace, opening parenthesis, or
quote character, and @t{”} otherwise.
@@ -473,7 +471,7 @@
type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To
insert a curved quote even when Electric Quote is disabled or
inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for
-@t{’}, @kbd{C-x 8 @{} for ``, and @kbd{C-x 8 @}} for ''.
+@t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}.
@xref{Inserting Text}. Note that the value of
@code{electric-quote-chars} does not affect these keybindings, they
are not keybindings of @code{electric-quote-mode} but bound in
------------------------- TEXT.TEXI END -------------------------
- Quotes are fixed, so FIXME is no longer needed.
- Value of "electric-quote-chars" has so many @w, because:
A. To prevent splitting between lines, which happens;
B. ?‘ expands to ¿, so I had to prevent it (@w near ?’ ?“ ?”, are
unnecessary, but I put them anyway for consistency and just in case
something in the future change, i.e. for safety).
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 ”."
>> 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.
>>
>> 3. Add numbers to sections (& subsect.) for bookmark/navigation pane.
>> When you open it in any PDF reader with manual loaded, it only shows
>> names of sections, and without numbers it's difficult to navigate.
>
> These are beyond our control (well, unless we want to write a lot of
> TeX glue in the manual): this is how Texinfo works.
With the up-to-date version of TEXINFO.TEX, header style could be
changed with this:
------------------------- EMACS.TEXI START -------------------------
--- old/emacs.texi 2020-05-10 21:24:52.351021900 +0200
+++ new/emacs.texi 2020-05-10 21:23:30.621478300 +0200
@@ -99,10 +99,13 @@
@end titlepage
+@evenheading @thispage @| @|
+@oddheading @| @| @thispage
@summarycontents
@contents
+@headings double
@ifnottex
@node Top
------------------------- EMACS.TEXI END -------------------------
which will print this:
+--------------------------+ +------------------------+
| PAGE_NUM DOC_TITLE | |CHAPTER PAGE_NUM |
This is something I wanted to do in point 2. It would certainly make
PDF look better.
As for chapters/sections numbering: chapters (level) will be numbered,
but sections won't for now (more opinions from other people are
needed). As for me, chapter numeration (only) is good enough to mark
it as done.
Optional, further reading:
- quotes problem thread & PDF bookmarks numeration thread:
https://lists.gnu.org/archive/html/help-texinfo/2020-05/msg00005.html
- headers thread:
https://lists.gnu.org/archive/html/help-texinfo/2020-04/msg00000.html
CONTINUED
https://lists.gnu.org/archive/html/help-texinfo/2020-05/msg00000.html
S. U.
P.S. If separate bug report is preferred, let me know, I'll send it
again.
[-- Attachment #2: basic.diff --]
[-- Type: text/plain, Size: 1628 bytes --]
--- old/basic.texi 2020-05-03 01:28:18.576838200 +0200
+++ new/basic.texi 2020-05-05 23:07:21.487684600 +0200
@@ -115,7 +115,7 @@
starting with @kbd{C-x 8}. For example, @kbd{C-x 8 [} inserts @t{‘}
which is Unicode code-point U+2018 @sc{left single quotation mark},
sometimes called a left single ``curved quote'' or ``curly quote''.
-Similarly, @kbd{C-x 8 ]}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
+Similarly, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the
curved quotes @t{’}, @t{“} and @t{”}, respectively. Also, a working
@key{Alt} key acts like @kbd{C-x 8} (unless followed by @key{RET});
e.g., @kbd{A-[} acts like @kbd{C-x 8 [} and inserts @t{‘}. To see
@@ -146,11 +146,11 @@
how many copies of the character to insert (@pxref{Arguments}).
In addition, in some contexts, if you type a quotation using grave
-accent and apostrophe @kbd{`like this'}, it is converted to a form
-@t{‘like this’} using single quotation marks, even without @kbd{C-x 8}
-commands. Similarly, typing a quotation @kbd{``like this''} using
-double grave accent and apostrophe converts it to a form @t{“like
-this”} using double quotation marks. @xref{Quotation Marks}.
+accent and apostrophe @verb{|`like this'|}, it is converted to a form
+using single quotation marks @t{‘like this’}, even without @kbd{C-x 8}
+commands. Similarly, typing a quotation using double grave accent and
+apostrophe @verb{|``like this''|}, converts it to a form using double
+quotation marks @w{@t{“like this”}}. @xref{Quotation Marks}.
@node Moving Point
@section Changing the Location of Point
[-- Attachment #3: display.diff --]
[-- Type: text/plain, Size: 1316 bytes --]
--- old/display.texi 2020-05-03 01:29:34.852965900 +0200
+++ new/display.texi 2020-05-05 23:00:10.014126600 +0200
@@ -1629,10 +1629,10 @@
@cindex curved quotes, and terminal capabilities
@cindex @code{homoglyph} face
-Emacs tries to determine if the curved quotes @samp{‘} and @samp{’}
+Emacs tries to determine if the curved quotes @t{‘} and @t{’}
can be displayed on the current display. By default, if this seems to
-be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`}
-and @samp{'}), when they appear in messages and help texts, to these
+be so, then Emacs will translate the @acronym{ASCII} quotes @w{(@kbd{`}
+and @kbd{'})}, when they appear in messages and help texts, to these
curved quotes. You can influence or inhibit this translation by
customizing the user option @code{text-quoting-style} (@pxref{Keys in
Documentation,,, elisp, The Emacs Lisp Reference Manual}).
@@ -1641,7 +1641,7 @@
known to look just like @acronym{ASCII} characters, they are shown
with the @code{homoglyph} face. Curved quotes that are known not to
be displayable are shown as their @acronym{ASCII} approximations
-@t{`}, @t{'}, and @t{"} with the @code{homoglyph} face.
+@kbd{`}, @kbd{'}, and @kbd{"} with the @code{homoglyph} face.
@node Cursor Display
@section Displaying the Cursor
[-- Attachment #4: modes.diff --]
[-- Type: text/plain, Size: 493 bytes --]
--- old/modes.texi 2020-05-03 01:32:48.773267500 +0200
+++ new/modes.texi 2020-05-05 20:23:41.217738900 +0200
@@ -207,7 +207,7 @@
@item
Electric Quote mode automatically converts quotation marks. For
-example, it requotes text typed @kbd{`like this'} to text @t{‘like
+example, it requotes text typed @verb{|`like this'|} to text @t{‘like
this’}. You can control what kind of text it operates in, and you can
disable it entirely in individual buffers. @xref{Quotation Marks}.
[-- Attachment #5: text.diff --]
[-- Type: text/plain, Size: 2477 bytes --]
--- old/text.texi 2020-05-03 01:34:10.677385800 +0200
+++ new/text.texi 2020-05-05 23:47:52.987559000 +0200
@@ -421,13 +421,11 @@
@cindex curved quotes
@cindex guillemets
@findex electric-quote-mode
-@c The funny quoting below is to make the printed version look
-@c correct. FIXME.
One common way to quote is the typewriter convention, which quotes
-using straight apostrophes @t{'like this'} or double-quotes @t{"like
-this"}. Another common way is the curved quote convention, which uses
-left and right single or double quotation marks `@t{like this}' or
-``@t{like this}''@footnote{
+using straight apostrophes @verb{|'like this'|} or double-quotes
+@verb{|"like this"|}. Another common way is the curved quote
+convention, which uses left and right single or double quotation marks
+@t{‘like this’} or @t{“like this”}@footnote{
The curved single quote characters are U+2018 @sc{left single quotation
mark} and U+2019 @sc{right single quotation mark}; the curved double quotes
are U+201C @sc{left double quotation mark} and U+201D @sc{right double
@@ -445,7 +443,7 @@
@code{electric-quote-chars}, a list of four characters, where the
items correspond to the left single quote, the right single quote, the
left double quote and the right double quote, respectively, whose
-default value is @code{'(?@r{`} ?@r{'} ?@r{``} ?@r{''})}.
+default value is @w{@code{'(@w{?}‘ @w{?}’ @w{?}“ @w{?}”)}}.
@vindex electric-quote-paragraph
@vindex electric-quote-comment
@@ -461,7 +459,7 @@
@vindex electric-quote-replace-double
You can also set the option @code{electric-quote-replace-double} to
-a non-@code{nil} value. Then, typing @t{"} insert an appropriate
+a non-@code{nil} value. Then, typing @kbd{"} insert an appropriate
curved double quote depending on context: @t{“} at the beginning of
the buffer or after a line break, whitespace, opening parenthesis, or
quote character, and @t{”} otherwise.
@@ -473,7 +471,7 @@
type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To
insert a curved quote even when Electric Quote is disabled or
inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for
-@t{’}, @kbd{C-x 8 @{} for ``, and @kbd{C-x 8 @}} for ''.
+@t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}.
@xref{Inserting Text}. Note that the value of
@code{electric-quote-chars} does not affect these keybindings, they
are not keybindings of @code{electric-quote-mode} but bound in
next prev parent reply other threads:[~2020-05-10 20:02 UTC|newest]
Thread overview: 48+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-24 15:59 bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals) Sebastian Urban
2019-06-02 22:50 ` Sebastian Urban
2019-06-03 16:36 ` Eli Zaretskii
2019-06-04 10:48 ` Sebastian Urban
2019-06-04 15:12 ` Eli Zaretskii
2019-06-05 10:40 ` Sebastian Urban
2019-06-05 16:52 ` Eli Zaretskii
2019-06-06 9:49 ` Sebastian Urban
2019-06-06 21:19 ` Sebastian Urban
2019-06-09 8:31 ` Eli Zaretskii
2019-06-09 8:22 ` Eli Zaretskii
2019-06-10 10:30 ` Sebastian Urban
2019-06-10 17:01 ` Eli Zaretskii
2019-06-11 10:32 ` Sebastian Urban
2019-06-11 16:59 ` Eli Zaretskii
2019-06-12 8:44 ` Sebastian Urban
2019-06-12 13:25 ` Drew Adams
2019-06-03 16:32 ` Eli Zaretskii
2020-05-10 20:02 ` Sebastian Urban [this message]
2020-08-13 9:11 ` Sebastian Urban
2020-08-13 13:20 ` Eli Zaretskii
2020-08-13 14:06 ` Sebastian Urban
2020-08-13 14:16 ` Eli Zaretskii
2020-08-14 0:01 ` Sebastian Urban
2020-08-15 13:18 ` Lars Ingebrigtsen
2020-08-15 13:34 ` Eli Zaretskii
2020-08-15 13:52 ` Lars Ingebrigtsen
2020-08-15 14:11 ` Sebastian Urban
2020-08-16 11:16 ` Lars Ingebrigtsen
2020-08-16 13:00 ` Sebastian Urban
2020-08-18 14:54 ` Lars Ingebrigtsen
2020-08-18 15:07 ` Eli Zaretskii
2020-08-19 10:15 ` Lars Ingebrigtsen
2020-08-19 8:44 ` Sebastian Urban
2020-08-19 10:19 ` Lars Ingebrigtsen
2020-08-19 12:14 ` Sebastian Urban
2020-08-20 12:44 ` Lars Ingebrigtsen
2020-08-20 13:35 ` Eli Zaretskii
2020-08-20 18:24 ` Sebastian Urban
2020-08-22 7:20 ` Eli Zaretskii
2020-08-22 10:19 ` Sebastian Urban
2020-10-19 18:52 ` Sebastian Urban
2021-05-12 14:47 ` Lars Ingebrigtsen
2021-05-13 11:48 ` Sebastian Urban
2021-05-16 13:30 ` Lars Ingebrigtsen
2021-05-18 9:17 ` Sebastian Urban
2021-05-18 13:15 ` bug#42199: " Lars Ingebrigtsen
[not found] <<cf31e2b2-3ad4-57f0-8847-e5f01ff35fc8@gmail.com>
[not found] ` <<f2fff09b-fc97-795b-dc3b-4175c48234db@gmail.com>
[not found] ` <<83k1e2tym6.fsf@gnu.org>
[not found] ` <<e083f8bd-8c77-3558-c373-a8d9d9ef6079@gmail.com>
[not found] ` <<835zpltme6.fsf@gnu.org>
[not found] ` <<d1695e2e-7f87-7493-fbd9-97cd6347d837@gmail.com>
[not found] ` <<83muiwrn2u.fsf@gnu.org>
[not found] ` <<1583c6b3-2421-794d-8c8b-86287ef3fd5a@gmail.com>
[not found] ` <<83tvczb236.fsf@gnu.org>
[not found] ` <<616312d4-0faf-0382-3f21-5b66327d8d8b@gmail.com>
[not found] ` <<83tvcx9xyl.fsf@gnu.org>
2019-06-10 17:44 ` Drew Adams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=c27a8c46-68d3-f9f4-2e92-05e0b6496b53@gmail.com \
--to=mrsebastianurban@gmail.com \
--cc=35885@debbugs.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.