* bug#48504: Improve style of C-h t description (Preface)
@ 2021-05-18 19:05 Sebastian Urban
2021-05-18 19:19 ` Eli Zaretskii
0 siblings, 1 reply; 15+ messages in thread
From: Sebastian Urban @ 2021-05-18 19:05 UTC (permalink / raw)
To: 48504
Currently, in the Preface of the Emacs manual (EMACS.TEXI - L1291),
there is:
To run the tutorial, start Emacs and type @kbd{C-h t} (which is
``control h and then t'').
I think, the part between parens should look better, e.g. similar to
this part of SCREEN.TEXI (L126):
...(hold down @key{Ctrl} and type @kbd{x}, then let go of
@key{Ctrl} and type @kbd{=})...
...i.e.:
...(hold down @key{Ctrl} and type @kbd{h}, then let go of
@key{Ctrl} and type @kbd{t}).
That's all.
--
S. U.
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-18 19:05 bug#48504: Improve style of C-h t description (Preface) Sebastian Urban
@ 2021-05-18 19:19 ` Eli Zaretskii
2021-05-18 20:35 ` Sebastian Urban
0 siblings, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2021-05-18 19:19 UTC (permalink / raw)
To: Sebastian Urban; +Cc: 48504
> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Tue, 18 May 2021 21:05:14 +0200
>
> Currently, in the Preface of the Emacs manual (EMACS.TEXI - L1291),
> there is:
> To run the tutorial, start Emacs and type @kbd{C-h t} (which is
> ``control h and then t'').
>
> I think, the part between parens should look better, e.g. similar to
> this part of SCREEN.TEXI (L126):
> ...(hold down @key{Ctrl} and type @kbd{x}, then let go of
> @key{Ctrl} and type @kbd{=})...
> ...i.e.:
> ...(hold down @key{Ctrl} and type @kbd{h}, then let go of
> @key{Ctrl} and type @kbd{t}).
We didn't yet introduce the Ctrl etc. notation at that place.
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-18 19:19 ` Eli Zaretskii
@ 2021-05-18 20:35 ` Sebastian Urban
2021-05-19 2:24 ` Eli Zaretskii
0 siblings, 1 reply; 15+ messages in thread
From: Sebastian Urban @ 2021-05-18 20:35 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 48504
>> Currently, in the Preface of the Emacs manual (EMACS.TEXI - L1291),
>> there is:
>> To run the tutorial, start Emacs and type @kbd{C-h t} (which is
>> ``control h and then t'').
>>
>> I think, the part between parens should look better, e.g. similar to
>> this part of SCREEN.TEXI (L126):
>> ...(hold down @key{Ctrl} and type @kbd{x}, then let go of
>> @key{Ctrl} and type @kbd{=})...
>> ...i.e.:
>> ...(hold down @key{Ctrl} and type @kbd{h}, then let go of
>> @key{Ctrl} and type @kbd{t}).
>
> We didn't yet introduce the Ctrl etc. notation at that place.
What about "Control" instead of "Ctrl"?
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-18 20:35 ` Sebastian Urban
@ 2021-05-19 2:24 ` Eli Zaretskii
2021-05-19 11:17 ` Sebastian Urban
0 siblings, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2021-05-19 2:24 UTC (permalink / raw)
To: Sebastian Urban; +Cc: 48504
> Cc: 48504@debbugs.gnu.org
> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Tue, 18 May 2021 22:35:37 +0200
>
> >> Currently, in the Preface of the Emacs manual (EMACS.TEXI - L1291),
> >> there is:
> >> To run the tutorial, start Emacs and type @kbd{C-h t} (which is
> >> ``control h and then t'').
> >>
> >> I think, the part between parens should look better, e.g. similar to
> >> this part of SCREEN.TEXI (L126):
> >> ...(hold down @key{Ctrl} and type @kbd{x}, then let go of
> >> @key{Ctrl} and type @kbd{=})...
> >> ...i.e.:
> >> ...(hold down @key{Ctrl} and type @kbd{h}, then let go of
> >> @key{Ctrl} and type @kbd{t}).
> >
> > We didn't yet introduce the Ctrl etc. notation at that place.
>
> What about "Control" instead of "Ctrl"?
You mean, just capitalize what the text already says? no objections
here.
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-19 2:24 ` Eli Zaretskii
@ 2021-05-19 11:17 ` Sebastian Urban
2021-05-19 11:56 ` Eli Zaretskii
0 siblings, 1 reply; 15+ messages in thread
From: Sebastian Urban @ 2021-05-19 11:17 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 48504
>>> We didn't yet introduce the Ctrl etc. notation at that place.
>>
>> What about "Control" instead of "Ctrl"?
>
> You mean, just capitalize what the text already says? no objections
> here.
No, I mean to change this:
(which is ``control h and then t'')
into this:
(hold down @key{Control} and type @kbd{h}, then let go of
@key{Control} and type @kbd{t})
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-19 11:17 ` Sebastian Urban
@ 2021-05-19 11:56 ` Eli Zaretskii
2021-05-19 13:44 ` Sebastian Urban
2021-09-29 12:07 ` Stefan Kangas
0 siblings, 2 replies; 15+ messages in thread
From: Eli Zaretskii @ 2021-05-19 11:56 UTC (permalink / raw)
To: Sebastian Urban; +Cc: 48504
> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 48504@debbugs.gnu.org
> Date: Wed, 19 May 2021 13:17:28 +0200
>
> >>> We didn't yet introduce the Ctrl etc. notation at that place.
> >>
> >> What about "Control" instead of "Ctrl"?
> >
> > You mean, just capitalize what the text already says? no objections
> > here.
>
> No, I mean to change this:
> (which is ``control h and then t'')
> into this:
> (hold down @key{Control} and type @kbd{h}, then let go of
> @key{Control} and type @kbd{t})
That's awkward. How about
To run the tutorial, start Emacs and type @kbd{C-h t} (that is,
press and hold Control, then type h, then release Control and type
t).
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-19 11:56 ` Eli Zaretskii
@ 2021-05-19 13:44 ` Sebastian Urban
2021-05-19 14:06 ` Eli Zaretskii
2021-09-29 12:07 ` Stefan Kangas
1 sibling, 1 reply; 15+ messages in thread
From: Sebastian Urban @ 2021-05-19 13:44 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 48504
>> No, I mean to change this:
>> (which is ``control h and then t'')
>> into this:
>> (hold down @key{Control} and type @kbd{h}, then let go of
>> @key{Control} and type @kbd{t})
>
> That's awkward.
What exactly? It's basically copy-paste from SCREEN.TEXI (L126). Is it
awkward there as well?
> How about
>
> To run the tutorial, start Emacs and type @kbd{C-h t} (that is,
> press and hold Control, then type h, then release Control and type
> t).
Why @kbd/@key (commands for indication) can't be used here for
"Control"/"h"/"t"?
The complete sentence would look (in EMACS.TEXI) like this:
To run the tutorial, start Emacs and type @kbd{C-h t} (that/which
is, hold down @key{Control} and type @kbd{h}, then let go of
@key{Control} and type @kbd{t}).
Whether there will be "that is" or "which is" - it's up to you.
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-19 13:44 ` Sebastian Urban
@ 2021-05-19 14:06 ` Eli Zaretskii
2021-05-20 6:21 ` Sebastian Urban
0 siblings, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2021-05-19 14:06 UTC (permalink / raw)
To: Sebastian Urban; +Cc: 48504
> Cc: 48504@debbugs.gnu.org
> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Date: Wed, 19 May 2021 15:44:51 +0200
>
> >> No, I mean to change this:
> >> (which is ``control h and then t'')
> >> into this:
> >> (hold down @key{Control} and type @kbd{h}, then let go of
> >> @key{Control} and type @kbd{t})
> >
> > That's awkward.
>
> What exactly? It's basically copy-paste from SCREEN.TEXI (L126). Is it
> awkward there as well?
Maybe, I didn't look.
> > How about
> >
> > To run the tutorial, start Emacs and type @kbd{C-h t} (that is,
> > press and hold Control, then type h, then release Control and type
> > t).
>
> Why @kbd/@key (commands for indication) can't be used here for
> "Control"/"h"/"t"?
Because we didn't yet explain this notation, that comes later in the
manual.
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-19 14:06 ` Eli Zaretskii
@ 2021-05-20 6:21 ` Sebastian Urban
2021-05-20 7:06 ` Eli Zaretskii
0 siblings, 1 reply; 15+ messages in thread
From: Sebastian Urban @ 2021-05-20 6:21 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 48504
>>> How about
>>>
>>> To run the tutorial, start Emacs and type @kbd{C-h t} (that is,
>>> press and hold Control, then type h, then release Control and type
>>> t).
>>
>> Why @kbd/@key (commands for indication) can't be used here for
>> "Control"/"h"/"t"?
>
> Because we didn't yet explain this notation, that comes later in the
> manual.
This is becoming a surprisingly confusing issue...
So, we can't present keys or other KBD input with @key/@kbd style,
because of the notation, that e.g. makes keys like Control use @key
style, which is introduced later? Until that section - "(emacs) User
Input" perhaps - we can only write "Control"/"h"/"t" just like an
ordinary text? BTW, isn't @kbd{C-h t}, in the same sentence, and
@kbd{h}, in the same file (EMACS.TEXI - L128), against this rule as
well?
What is to explain at all? The fact that - e.g. in PDF - @kbd/@key
change font from Roman to Typewriter. It helps to distinguish the
input keys/chars from the rest of the paragraph. In your example "h"
and "t" may look like leftovers from a partially removed words...
which is something I want to avoid.
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-05-20 6:21 ` Sebastian Urban
@ 2021-05-20 7:06 ` Eli Zaretskii
2021-05-20 13:42 ` Sebastian Urban
0 siblings, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2021-05-20 7:06 UTC (permalink / raw)
To: Sebastian Urban; +Cc: 48504
> From: Sebastian Urban <mrsebastianurban@gmail.com>
> Cc: 48504@debbugs.gnu.org
> Date: Thu, 20 May 2021 08:21:01 +0200
>
> So, we can't present keys or other KBD input with @key/@kbd style,
> because of the notation, that e.g. makes keys like Control use @key
> style, which is introduced later?
Using some notation before explaining it is confusing, especially when
you are telling the reader how to start the tutorial, which is
probably the first document about Emacs for that reader.
> What is to explain at all? The fact that - e.g. in PDF - @kbd/@key
> change font from Roman to Typewriter. It helps to distinguish the
> input keys/chars from the rest of the paragraph. In your example "h"
> and "t" may look like leftovers from a partially removed words...
> which is something I want to avoid.
Look, you don't have to agree with my reasoning. As long as I
explained it, and the explanation is clear (as I think it is, based on
your response), we don't have to continue to argue. Just accept that
this is my reasoning for doing things this way, and it's based on some
experience in this area.
^ permalink raw reply [flat|nested] 15+ messages in thread
* bug#48504: Improve style of C-h t description (Preface)
2021-05-20 7:06 ` Eli Zaretskii
@ 2021-05-20 13:42 ` Sebastian Urban
0 siblings, 0 replies; 15+ messages in thread
From: Sebastian Urban @ 2021-05-20 13:42 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 48504
>> So, we can't present keys or other KBD input with @key/@kbd style,
>> because of the notation, that e.g. makes keys like Control use @key
>> style, which is introduced later?
>
> Using some notation before explaining it is confusing, especially when
> you are telling the reader how to start the tutorial, which is
> probably the first document about Emacs for that reader.
This means - for me - that the problem is "C-h t", actually. Perhaps,
this is the mysterious notation (next to the Ctrl instead of Control?)
you were writing about, from the very beginning? Then, basically the
whole sentence, not only the text between parens, has to be rewritten
to get rid of "C-h t".
BTW, since you didn't write where the definition of this notation is
written, I still assume that it's in the beginning of the
COMMANDS.TEXI (Kinds of User Input).
^ permalink raw reply [flat|nested] 15+ messages in thread
* bug#48504: Improve style of C-h t description (Preface)
2021-05-19 11:56 ` Eli Zaretskii
2021-05-19 13:44 ` Sebastian Urban
@ 2021-09-29 12:07 ` Stefan Kangas
2021-09-29 12:18 ` Eli Zaretskii
1 sibling, 1 reply; 15+ messages in thread
From: Stefan Kangas @ 2021-09-29 12:07 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Sebastian Urban, 48504
Eli Zaretskii <eliz@gnu.org> writes:
>> No, I mean to change this:
>> (which is ``control h and then t'')
>> into this:
>> (hold down @key{Control} and type @kbd{h}, then let go of
>> @key{Control} and type @kbd{t})
>
> That's awkward. How about
>
> To run the tutorial, start Emacs and type @kbd{C-h t} (that is,
> press and hold Control, then type h, then release Control and type
> t).
All users already know the notation Ctrl+X if they have ever used a
computer. We can safely assume this most basic level of computer
literacy.
So this is better written as:
> To run the tutorial, start Emacs and type @kbd{C-h t} (that is,
> @kbd{Ctrl+H}, then @kbd{T}).
(There is no confusion here with regards to @kbd{T} and @kbd{t}, because
everywhere else our "T" is written as "Shift+T".)
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-09-29 12:07 ` Stefan Kangas
@ 2021-09-29 12:18 ` Eli Zaretskii
2021-09-29 13:11 ` Stefan Kangas
0 siblings, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2021-09-29 12:18 UTC (permalink / raw)
To: Stefan Kangas; +Cc: mrsebastianurban, 48504
> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 29 Sep 2021 05:07:09 -0700
> Cc: Sebastian Urban <mrsebastianurban@gmail.com>, 48504@debbugs.gnu.org
>
> > To run the tutorial, start Emacs and type @kbd{C-h t} (that is,
> > @kbd{Ctrl+H}, then @kbd{T}).
The first @kbd should be @kbd{@key{Ctrl} H}, I think. For two
reasons:
. "Ctrl" is a single key, not 4 characters C t r l
. "+" isn't something the user should type
IOW, what you suggest violates our (and Texinfo's) conventions for
markup of key sequences. Which is why I proposed a pure-English
description that doesn't use any fancy markup that could only confuse
at this point.
Question: what do we gain from using "Ctrl+H" instead?
^ permalink raw reply [flat|nested] 15+ messages in thread* bug#48504: Improve style of C-h t description (Preface)
2021-09-29 12:18 ` Eli Zaretskii
@ 2021-09-29 13:11 ` Stefan Kangas
2022-07-13 12:00 ` Lars Ingebrigtsen
0 siblings, 1 reply; 15+ messages in thread
From: Stefan Kangas @ 2021-09-29 13:11 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: mrsebastianurban, 48504
Eli Zaretskii <eliz@gnu.org> writes:
> Question: what do we gain from using "Ctrl+H" instead?
The benefit is that the text is shorter and less tedious to read.
This is all very minor of course, but that's my position. Precisely
because this is so minor, I hope that we can just take a decision (any
decision), close this bug and move on.
^ permalink raw reply [flat|nested] 15+ messages in thread
* bug#48504: Improve style of C-h t description (Preface)
2021-09-29 13:11 ` Stefan Kangas
@ 2022-07-13 12:00 ` Lars Ingebrigtsen
0 siblings, 0 replies; 15+ messages in thread
From: Lars Ingebrigtsen @ 2022-07-13 12:00 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Eli Zaretskii, 48504, mrsebastianurban
Stefan Kangas <stefan@marxist.se> writes:
> This is all very minor of course, but that's my position. Precisely
> because this is so minor, I hope that we can just take a decision (any
> decision), close this bug and move on.
Skimming this bug thread, I don't think any of the suggestions here are
clear improvements over what we already have, so I'd just rather leave
this as is, and I'm therefore closing this bug report.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2022-07-13 12:00 UTC | newest]
Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-05-18 19:05 bug#48504: Improve style of C-h t description (Preface) Sebastian Urban
2021-05-18 19:19 ` Eli Zaretskii
2021-05-18 20:35 ` Sebastian Urban
2021-05-19 2:24 ` Eli Zaretskii
2021-05-19 11:17 ` Sebastian Urban
2021-05-19 11:56 ` Eli Zaretskii
2021-05-19 13:44 ` Sebastian Urban
2021-05-19 14:06 ` Eli Zaretskii
2021-05-20 6:21 ` Sebastian Urban
2021-05-20 7:06 ` Eli Zaretskii
2021-05-20 13:42 ` Sebastian Urban
2021-09-29 12:07 ` Stefan Kangas
2021-09-29 12:18 ` Eli Zaretskii
2021-09-29 13:11 ` Stefan Kangas
2022-07-13 12:00 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).