Suggestion: minor change to TUTORIAL(.*)

Suggestion: minor change to TUTORIAL(.*)

[CHENG Gao]

In TUTORIAL, line 42-45 (latest cvs source): 

,----
| 	C-l	Clear screen and redisplay all the text,
| 		 moving the text around the cursor
| 		 to the center of the screen.
| 		 (That's CONTROL-L, not CONTROL-1.)
`----
Certainly Ctrl-L is not Ctrl-l.
How about changing to:
,----
| (Here l is lower case of L.)
`----

This affects all TUTORIAL.* files.

Another minor problem is copyright year in TUTORIAL.cn should be updated
to add 2006. TUTORIAL.cn is the only tutoril file missing 2006.

Re: Suggestion: minor change to TUTORIAL(.*)

[CHENG Gao]

Seems Ctrl-Shift-l does same thing as Ctrl-l. "C-h k Ctrl-Shift-l"
describes it as Ctrl-l. With Caps Lock on, "C-h k Ctrl-l" still shows it
as Ctrl-l. Is it right or wrong?

Re: Suggestion: minor change to TUTORIAL(.*)

[CHENG Gao]

In TUTORIAL, line 247-248 (latest cvs source):
,----
| If you have typed an <ESC> by mistake, you can get rid of it
| with a C-g.
`----

I read in TUTORIAL.cn translator added a comment that:
ESC, then Ctrl-g, will be translated to C-M-g. He suggested that the
right way is to press ESC two times to get rid of it.

My test shows "ESC Ctrl-u" triggered a "C-M-g is undefined" error. "ESC
ESC ESC" works right.

Re: Suggestion: minor change to TUTORIAL(.*)

[CHENG Gao]

TUTORIAL, line 773:
,----
| >> Type M-x text mode<Return>.
`----
"-" missing here.

Line 808:
,----[ (info "(emacs)Scrolling") ]
| >> Type M-x auto fill mode<Return> now. 
`----
same case.

It should be changed in other TUTORIAL.* files also.

Re: Suggestion: minor change to TUTORIAL(.*)

[Andreas Schwab]

CHENG Gao <chenggao@gmail.com> writes:

> TUTORIAL, line 773:
> ,----
> | >> Type M-x text mode<Return>.
> `----
> "-" missing here.

The space works as well, it will do completion which inserts the dash.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Suggestion: minor change to TUTORIAL(.*)

[Richard Stallman]

    | >> Type M-x text mode<Return>.
    `----
    "-" missing here.

That is correct.  The user should type a space.

Re: Suggestion: minor change to TUTORIAL(.*)

[Kevin Rodgers]

Richard Stallman wrote:
>     | >> Type M-x text mode<Return>.
>     `----
>     "-" missing here.
> 
> That is correct.  The user should type a space.

Isn't the conventional way to display that:

Type `M-x text SPC mode RET'.

-- 
Kevin

Re: Suggestion: minor change to TUTORIAL(.*)

[Richard Stallman]

    > That is correct.  The user should type a space.

    Isn't the conventional way to display that:

    Type `M-x text SPC mode RET'.

In the manual, yes.  But I am not sure which is clearer to a
beginner reading the tutorial.

RE: Suggestion: minor change to TUTORIAL(.*)

[Drew Adams]

    Richard Stallman wrote:
    >     | >> Type M-x text mode<Return>.
    >     `----
    >     "-" missing here.
    >
    > That is correct.  The user should type a space.

    Isn't the conventional way to display that:

    Type `M-x text SPC mode RET'.


I would say it should be `M-x t e x t SPC m o d e RET'.

Neither `text' nor `mode' is a key name. These are instructions for typing a
key sequence; this is not the name of a key sequence that includes keys
named `text' and `mode'.

Re: Suggestion: minor change to TUTORIAL(.*)

[Lennart Borgman]

Drew Adams wrote:
>     Richard Stallman wrote:
>     >     | >> Type M-x text mode<Return>.
>     >     `----
>     >     "-" missing here.
>     >
>     > That is correct.  The user should type a space.
>
>     Isn't the conventional way to display that:
>
>     Type `M-x text SPC mode RET'.
>
>
> I would say it should be `M-x t e x t SPC m o d e RET'.
>
> Neither `text' nor `mode' is a key name. These are instructions for typing a
> key sequence; this is not the name of a key sequence that includes keys
> named `text' and `mode'.
>
>   

But I would guess that most users would understand `M-x text-mode RET' 
(which I prefer) or `M-x text mode RET' much more easily.

Logical thinking is not at the beginning. You are looking for an 
overview then.

RE: Suggestion: minor change to TUTORIAL(.*)

[Drew Adams]

    >     >     | >> Type M-x text mode<Return>.
    >     >     `----
    >     >     "-" missing here.
    >     >
    >     > That is correct.  The user should type a space.
    >
    >     Isn't the conventional way to display that:
    >     Type `M-x text SPC mode RET'.
    >
    > I would say it should be `M-x t e x t SPC m o d e RET'.
    >
    > Neither `text' nor `mode' is a key name. These are
    > instructions for typing a key sequence; this is not the name
    > of a key sequence that includes keys named `text' and `mode'.

    But I would guess that most users would understand `M-x text-mode
    RET' (which I prefer) or `M-x text mode RET' much more easily.
    Logical thinking is not at the beginning. You are looking for an
    overview then.

Sometimes, what seems immediately readable is fraught with difficulty or
ambiguity when you try to apply it consistently. It is better to adopt, from
the beginning, a single notation that works unambiguously, and stick to it.

The convention used, whatever it is, should work for all contexts, that is,
all "Type this:" instructions. And it should be used consistently throughout
the manual.

The keystroke (key-typing) notation can be introduced in an overview. It is
not difficult to understand this convention:

- Single-quotes ("`", "'") set off keystroke instructions.

- Spaces separate keystrokes. Only spaces do this.
  A sequence of characters not separated by spaces
  represents a single keystroke (possibly a chord).

- `M-x' means hold the meta key depressed while
  hitting the `x' key. It is a chord, meaning that it
  is a single keystroke that uses more than one key.

- `SPC' means hit the space key.

- `RET' means hit the enter/return key.

There are no key names that contain spaces. This notation is unambiguous and
simple.

Spaces have no meaning as keystroke instructions in this notation.  They do
not represent keystrokes; they serve only to separate keystrokes.  So
multiple successive spaces can be used to enhance readability.

Is the following hard to understand?

  `M-x  t e x t  SPC  m o d e  RET'

[Note: None of this is about key-sequence notation (and that difference too
can be taught in the overview). This is about notation for keystroke
instructions. The key sequences involved here are in fact `M-x' (bound to
`execute-extended-command'), the individual letters (each bound to
`self-insert-command'), SPC (bound to `minibuffer-complete-word'), and `RET'
(bound to `exit-minibuffer').]

Re: Suggestion: minor change to TUTORIAL(.*)

[Stefan Monnier]

> Is the following hard to understand?

>   `M-x  t e x t  SPC  m o d e  RET'

Yes.  And it's never used.  Check this mailing-list and you'll see that
people would rather write it `M-x text SPC mode RET'.


        Stefan

RE: Suggestion: minor change to TUTORIAL(.*)

[Drew Adams]

    > Is the following hard to understand?

    >   `M-x  t e x t  SPC  m o d e  RET'

    Yes.  And it's never used.  Check this mailing-list and
    you'll see that people would rather write it
    `M-x text SPC mode RET'.

1. The mailing list is informal, and notation in email messages needs to be
unambiguous only within a limited context, not consistently for multiple
examples, as in a manual. I too write "Type `foobar'" in bug reports,
figuring it will be understood or, if not, a dialog will clear things up.

2. Never used? The following are all from instructions to type keystrokes.
They all unambiguously use the convention of separating keystrokes with
spaces. They are all from our manuals.

I did not include other examples of typing instructions that are equivalent
to key bindings, such as "type `7 d'" (not `7d') for the diary, because it
could be argued that the key-sequence notation, not the keystroke notation,
is being used in such cases. I don't think that can be argued in any of the
examples shown here.


Emacs manual nodes
------------------

. Blank Lines - `C-o F O O', `F O O <RET>'

. VC Dired Commands - `* l t k'

. Input Methods - `e ' '', `e e <DEL> ''

. Nroff Mode - `. ( b <RET>'

. Abbrevs - `f o o <SPC>'

. Abbrev Concepts - `f o o .'

. Dynamic Abbrevs - `f o M-/'

. Dabbrev Customization - `v a M-/'

. History References - `! m v <TAB>'


Info manual nodes
-----------------

. Help-] - `[ n [', `] p ]'

. Info Search - `i C - f <RET>'


Emacs-Lisp Introduction manual nodes
------------------------------------

. Keymaps - `@ g r o u p'


Org Mode manual, node
---------------------

. Agenda commands - `3 6 5 S-<right>'


Viper manual nodes
------------------

. New Commands - `# C 3 w'

. Vi Macros - `t e x t', `f 6'
  (actually, inconsistent notation is used in this node)


VIP manual nodes
----------------

. Undoing - `u . . .', `u u'

. Counts - `p p p', `o a b c <ESC>'

. Region Commands - `m . d R', `d d'

. New Commands - `# C 3 w'

. Numeric Arguments - `5 d d', `d d'

. Files - `v v <TAB> <RET>'

. Delete Commands - `3 d w', `" t 3 d w', `"T d w'

. Put Back Commands - `" c p'

. Change Commands - `c w', `b a r <RET>'


[Note: I'd prefer that we dispense with using angle brackets, because they
are unnecessary, which is why I wrote (as did both you and Lennart) `RET',
not `<RET>'. The manuals actually use `<RET>'.  This is not the question
under discussion now, however.]

Re: Suggestion: minor change to TUTORIAL(.*)

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 9 Oct 2006 18:27:38 -0700
> 
> There are no key names that contain spaces.

My keyboard has keys labeled like this:

   	    Page     Num
	    Down     Lock

etc.  It's hard to say about these that they don't contain spaces.

> Is the following hard to understand?
> 
>   `M-x  t e x t  SPC  m o d e  RET'

It's very hard to read, especially with longer commands.

RE: Suggestion: minor change to TUTORIAL(.*)

[Drew Adams]

    > There are no key names that contain spaces.

    My keyboard has keys labeled like this:

       Page     Num
    	 Down     Lock

    etc.  It's hard to say about these that they don't contain spaces.

I'm talking about the key names that are used by Emacs - logical key names,
not physical keyboard key names.

See my previous email on that (subject line "bug in read-kbd-macro"), which
you declined to read because of its length. Your physical key "Page Down" is
referred to by Emacs (in both the manual and the UI messages and *Help*) by
the logical-key name `<next>', which has no spaces.

There are no logical-key names that contain spaces, at least none that I am
aware of. We do not use `<mode line>', for instance; we use `<mode-line>'.
(This is a precondition for my argument to dispense with using angle
brackets.)

[I don't know where our key names come from. Perhaps they are derived from
the X-Window names in file keysymdef.h? None of the keysymdef.h key names
have embedded spaces, either, including the keys XK_Next and XK_Page_Down.]

    > Is the following hard to understand?
    >
    >   `M-x  t e x t  SPC  m o d e  RET'

    It's very hard to read, especially with longer commands.

There are relatively few instructions to type keys in the manuals, and the
above, fictitious example (not from a manual) is much longer than any I have
seen in the manual - about twice as long. So the length problem you cite
does not seem to be a problem in practice.

The problem of ambiguity between, say, "Type `M-x'" (3 keystrokes) and "Type
`M-x'" (1 chord keystroke), is, however, real - the former should be written
"Type `M - x'".

RE: Suggestion: minor change to TUTORIAL(.*)

[Drew Adams]

    [I don't know where our key names come from. Perhaps they are 
    derived from the X-Window names in file keysymdef.h? None of
    the keysymdef.h key names have embedded spaces, either, 
    including the keys XK_Next and XK_Page_Down.]
    
Likewise, the names in XKeysymDB, AFAICT.

Re: Suggestion: minor change to TUTORIAL(.*)

[Richard Stallman]

I have already stated that I see no need to change this.
Pleae stop arguing about it -- you are distracting people
from useful work.

Re: Suggestion: minor change to TUTORIAL(.*)

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 9 Oct 2006 22:06:55 -0700
> 
> Your physical key "Page Down" is
> referred to by Emacs (in both the manual and the UI messages and *Help*) by
> the logical-key name `<next>', which has no spaces.

info.texi uses "PageDown".

>     > Is the following hard to understand?
>     >
>     >   `M-x  t e x t  SPC  m o d e  RET'
> 
>     It's very hard to read, especially with longer commands.
> 
> There are relatively few instructions to type keys in the manuals, and the
> above, fictitious example (not from a manual) is much longer than any I have
> seen in the manual - about twice as long. So the length problem you cite
> does not seem to be a problem in practice.

Every time you see @kbd{whatever} in the manual means "type
whatever".  Here's a random example:

    There is a spiffy customize interface, which may be reached by typing
    @kbd{M-x customize-option erc-modules @key{RET}}.

Imagine having everything inside @kbd written with spaces between the
letters!

Re: Suggestion: minor change to TUTORIAL(.*)

[Robert J. Chassell]

    The convention used, whatever it is, should work for all contexts,
    that is, all "Type this:" instructions.

The current, consistent Texinfo convention is to use @kbd for all inputs.

    File: texinfo,  Node: kbd

    9.1.3 `@kbd'{KEYBOARD-CHARACTERS}
    ---------------------------------

    Use the `@kbd' command for characters of input to be typed by
    users.  For example, to refer to the characters `M-a', write:

         @kbd{M-a}

    and to refer to the characters `M-x shell', write:

         @kbd{M-x shell}

      By default, the `@kbd' command produces a different font
    (slanted typewriter instead of normal typewriter) in the printed
    manual, so users can distinguish the characters that they are
    supposed to type from those that the computer outputs.

      In Info output, `@kbd' is usually the same as `@code', producing
    `quotes' around its argument.  However, in typewriter-like
    contexts such as the `@example' environment (*note example::) and
    `@code' command itself, the quotes are omitted, since Info format
    cannot use distinguishing fonts.

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Suggestion: minor change to TUTORIAL(.*)

[Robert J. Chassell]

    - `RET' means hit the enter/return key.

In Texinfo, the current and consistent convention is to write
@key{RET}.  No one uses single quote marks.  As you would expect, the
output formats vary among the seven you can obtain directly from a
single Texinfo source file.

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Suggestion: minor change to TUTORIAL(.*)

[Richard Stallman]

    I read in TUTORIAL.cn translator added a comment that:
    ESC, then Ctrl-g, will be translated to C-M-g.

Yes, but it doesn't matter -- C-M-g is undefined.
So there is no need for the added comment.

Re: Suggestion: minor change to TUTORIAL(.*)

[David Kastrup]

CHENG Gao <chenggao@gmail.com> writes:

> In TUTORIAL, line 42-45 (latest cvs source): 
>
> ,----
> | 	C-l	Clear screen and redisplay all the text,
> | 		 moving the text around the cursor
> | 		 to the center of the screen.
> | 		 (That's CONTROL-L, not CONTROL-1.)
> `----
> Certainly Ctrl-L is not Ctrl-l.

Well, the key _is_ labelled "L" on keyboards.  The Emacs notation is
"C-l" (as written correctly above), and you get it by pressing the
keys labelled "Ctrl" and "L".

> How about changing to:
> ,----
> | (Here l is lower case of L.)
> `----

I think it is not really helpful here to make much unclearer what the
parenthetical remark is actually referring to, for the sake of forcing
Emacs key sequence description semantics partly into a place that is
used to clarify the semantics by using non-Emacs terminology.

> This affects all TUTORIAL.* files.

I would lean towards not changing anything.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Suggestion: minor change to TUTORIAL(.*)

[CHENG Gao]

*On Sat, 07 Oct 2006 09:32:42 +0200
* David Kastrup <dak@gnu.org> climbed out of the dark hell and cried out:

> Well, the key _is_ labelled "L" on keyboards.  The Emacs notation is
> "C-l" (as written correctly above), and you get it by pressing the
> keys labelled "Ctrl" and "L".

Thanks. I dont know that. Sorry I am a little washed head by Emacs.

Re: Suggestion: minor change to TUTORIAL(.*)

[CHENG Gao]

*On Sat, 07 Oct 2006 15:40:32 +0800
* CHENG Gao <chenggao@gmail.com> climbed out of the dark hell and cried out:


> Thanks. I dont know that. Sorry I am a little washed head by Emacs.
s/head/brain/
Sorry I am braindamaged.

Re: Suggestion: minor change to TUTORIAL(.*)

[Richard Stallman]

    Certainly Ctrl-L is not Ctrl-l.

There is no need for beginners to make a distinction between C-l and C-L.
They do the same thing in Emacs unless you make unusual rebindings.