GNU bug report logs - #48504
Improve style of C-h t description (Preface)

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 48504 in the body.
You can then email your comments to 48504 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Bug GNU Emacs <bug-gnu-emacs <at> gnu.org>
Subject: Improve style of C-h t description (Preface)
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}).

That's all.

--
S. U.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Tue, 18 May 2021 22:19:16 +0300

> From: Sebastian Urban <mrsebastianurban <at> 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.

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

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
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"?

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Wed, 19 May 2021 05:24:10 +0300

> Cc: 48504 <at> debbugs.gnu.org
> From: Sebastian Urban <mrsebastianurban <at> 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.

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

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
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})

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Wed, 19 May 2021 14:56:17 +0300

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

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

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
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?

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Wed, 19 May 2021 17:06:11 +0300

> Cc: 48504 <at> debbugs.gnu.org
> From: Sebastian Urban <mrsebastianurban <at> 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.

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

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Thu, 20 May 2021 08:21:01 +0200

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Thu, 20 May 2021 10:06:24 +0300

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

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

From: Sebastian Urban <mrsebastianurban <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Thu, 20 May 2021 15:42:14 +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.

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

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Sebastian Urban <mrsebastianurban <at> gmail.com>, 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Wed, 29 Sep 2021 05:07:09 -0700

Eli Zaretskii <eliz <at> 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".)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: mrsebastianurban <at> gmail.com, 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Wed, 29 Sep 2021 15:18:24 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Wed, 29 Sep 2021 05:07:09 -0700
> Cc: Sebastian Urban <mrsebastianurban <at> gmail.com>, 48504 <at> 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?

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: mrsebastianurban <at> gmail.com, 48504 <at> debbugs.gnu.org
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Wed, 29 Sep 2021 06:11:47 -0700

Eli Zaretskii <eliz <at> 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.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 48504 <at> debbugs.gnu.org,
 mrsebastianurban <at> gmail.com
Subject: Re: bug#48504: Improve style of C-h t description (Preface)
Date: Wed, 13 Jul 2022 14:00:59 +0200

Stefan Kangas <stefan <at> 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

Previous Next

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