Re: emacs-26 b90e91c: Fix last change of @key markup

Re: emacs-26 b90e91c: Fix last change of @key markup

[Michael Albinus]

eliz@gnu.org (Eli Zaretskii) writes:

Hi Eli,

for future changes I might apply, could you pls tell me what was wrong
with my changes?

>     Fix last change of @key markup
>     
>     * doc/lispref/display.texi (Specified Space):
>     * doc/emacs/programs.texi (C Modes):
>     * doc/emacs/killing.texi (Rectangles):
>     * doc/emacs/emacs.texi (Top):
>     * doc/emacs/display.texi (Useless Whitespace): Don't use @key
>     markup for characters and commands, only for keys.
> ---
>  doc/emacs/display.texi   | 6 +++---
>  doc/emacs/emacs.texi     | 2 +-
>  doc/emacs/killing.texi   | 2 +-
>  doc/emacs/programs.texi  | 2 +-
>  doc/lispref/display.texi | 2 +-
>  5 files changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
> index d0ab548..b2a4011 100644
> --- a/doc/emacs/display.texi
> +++ b/doc/emacs/display.texi
> @@ -1259,9 +1259,9 @@ Highlight empty lines.
>  @item big-indent
>  @vindex whitespace-big-indent-regexp
>  Highlight too-deep indentation.  By default any sequence of at least 4
> -consecutive @key{TAB} characters or 32 consecutive @key{SPC}
> -characters is highlighted.  To change that, customize the regular
> -expression @code{whitespace-big-indent-regexp}.
> +consecutive TAB characters or 32 consecutive SPC characters is
> +highlighted.  To change that, customize the regular expression
> +@code{whitespace-big-indent-regexp}.
>  
>  @item space-mark
>  Draw space and non-breaking characters with a special glyph.
> diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
> index b053922..0051868 100644
> --- a/doc/emacs/emacs.texi
> +++ b/doc/emacs/emacs.texi
> @@ -723,7 +723,7 @@ C and Related Modes
>  
>  * Motion in C::         Commands to move by C statements, etc.
>  * Electric C::          Colon and other chars can automatically reindent.
> -* Hungry Delete::       A more powerful @key{DEL} command.
> +* Hungry Delete::       A more powerful DEL command.
>  * Other C Commands::    Filling comments, viewing expansion of macros,
>                            and other neat features.
>  
> diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi
> index 7820393..6efcc9d 100644
> --- a/doc/emacs/killing.texi
> +++ b/doc/emacs/killing.texi
> @@ -857,7 +857,7 @@ region is active.
>  
>  Unlike the standard region, the region-rectangle can have its corners
>  extended past the end of buffer, or inside stretches of white space
> -that point normally cannot enter, like the @key{TAB}.
> +that point normally cannot enter, like the TAB.
>  
>  @findex rectangle-exchange-point-and-mark
>  @findex exchange-point-and-mark@r{, in rectangle-mark-mode}
> diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
> index 970647e..4289124 100644
> --- a/doc/emacs/programs.texi
> +++ b/doc/emacs/programs.texi
> @@ -1587,7 +1587,7 @@ with Emacs.
>  @menu
>  * Motion in C::                 Commands to move by C statements, etc.
>  * Electric C::                  Colon and other chars can automatically reindent.
> -* Hungry Delete::               A more powerful @key{DEL} command.
> +* Hungry Delete::               A more powerful DEL command.
>  * Other C Commands::            Filling comments, viewing expansion of macros,
>                                  and other neat features.
>  @end menu
> diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
> index bd1f671..fbf943a 100644
> --- a/doc/lispref/display.texi
> +++ b/doc/lispref/display.texi
> @@ -4599,7 +4599,7 @@ first character in the group of consecutive characters that have the
>  same @code{display} property.  The space width is the pixel width of
>  that character, multiplied by @var{factor}.  (On text-mode terminals,
>  the ``pixel width'' of a character is usually 1, but it could be more
> -for @key{TAB}s and double-width CJK characters.)
> +for TABs and double-width CJK characters.)
>  
>  @item :align-to @var{hpos}
>  Specifies that the space should be wide enough to reach @var{hpos}.

Best regards, Michael.

Re: emacs-26 b90e91c: Fix last change of @key markup

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Thu, 01 Feb 2018 19:48:24 +0100
> 
> for future changes I might apply, could you pls tell me what was wrong
> with my changes?

@key is only for names of keys, not for names of characters or
commands.  Your changes to add @key were mostly good, but they went a
notch too far, in that they included _any_ instance of "TAB" or "RET"
or "SPC", including, for example, this:

  @item big-indent
  @vindex whitespace-big-indent-regexp
  Highlight too-deep indentation.  By default any sequence of at least 4
  consecutive TAB characters or 32 consecutive SPC characters is
  highlighted.  To change that, customize the regular expression

Here, TAB and SPC refer to characters, not keys.

If that still doesn't make the criterion clear, consider this: the
purpose of @key is to avoid the erroneous interpretation of "RET" to
mean literal 3 characters R E T.  And such an erroneous interpretation
can only happen in the context of describing keyboard input or keys
the user presses, it cannot happen when the text refers to characters,
as in the above excerpt.  (Another way of looking at this is to see
how TeX renders @key: the result looks like a key on a keyboard, and
that is, of course, inappropriate when talking about anything other
than a keyboard key.)

HTH

Re: emacs-26 b90e91c: Fix last change of @key markup

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Before changing how we handle SPC and DEL,
let's look at the history of how this has been handled before
over the 32 years since the Emacs Manual was first written.
We might be cycling through choices tried before.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Skype: No way! See https://stallman.org/skype.html.