bug#48504: Improve style of C-h t description (Preface)

bug#48504: Improve style of C-h t description (Preface)

[Sebastian Urban]

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.

bug#48504: Improve style of C-h t description (Preface)

[Eli Zaretskii]

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

bug#48504: Improve style of C-h t description (Preface)

[Sebastian Urban]

>> 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"?

bug#48504: Improve style of C-h t description (Preface)

[Eli Zaretskii]

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

bug#48504: Improve style of C-h t description (Preface)

[Sebastian Urban]

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

bug#48504: Improve style of C-h t description (Preface)

[Eli Zaretskii]

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

bug#48504: Improve style of C-h t description (Preface)

[Sebastian Urban]

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

bug#48504: Improve style of C-h t description (Preface)

[Eli Zaretskii]

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

bug#48504: Improve style of C-h t description (Preface)

[Sebastian Urban]

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

bug#48504: Improve style of C-h t description (Preface)

[Eli Zaretskii]

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

bug#48504: Improve style of C-h t description (Preface)

[Sebastian Urban]

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

bug#48504: Improve style of C-h t description (Preface)

[Stefan Kangas]

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

bug#48504: Improve style of C-h t description (Preface)

[Eli Zaretskii]

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

bug#48504: Improve style of C-h t description (Preface)

[Stefan Kangas]

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.

bug#48504: Improve style of C-h t description (Preface)

[Lars Ingebrigtsen]

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