GNU bug report logs - #60859
[PATCH] Remove reference to the kbd function from documentation

Previous Next

Full log

View this message in rfc822 format

From: Robert Pluim <rpluim <at> gmail.com>
To: Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net>
Cc: 60859 <at> debbugs.gnu.org
Subject: bug#60859: [PATCH] Remove reference to the kbd function from documentation
Date: Tue, 17 Jan 2023 18:16:54 +0100

>>>>> On Tue, 17 Jan 2023 18:09:50 +0200, Panagiotis Koutsourakis <kutsurak <at> slartibartfast.net> said:


    Panagiotis> The current situation is that the explanation refers to "kbd" as an easy
    Panagiotis> way to write a key binding, but the code example has changed and makes
    Panagiotis> no reference to it.

right

    >> 
    >> How about
    >> 
    >> --begin--
    >> There are several syntaxes that can be used to specify the binding,
    >> but the simplest and most consistent is the one accepted by
    >> @code{kbd}, which is basically a series of characters separated by
    >> spaces.  Keys with modifiers can be specified by prepending the
    >> modifier, such as @samp{C-} for Control, or @samp{M-} for Meta.  For
    >> example, to bind @samp{C-x} followed by @samp{a}, use
    >> 
    >> @example
    >> kbd("C-x a")
    >> @end example
    >> --end--

    Panagiotis> This goes into some detail for a currently deprecated way to bind keys
    Panagiotis> (or at least that's what the current lisp reference manual says). 

    Panagiotis> So, to recap:

    Panagiotis> 1. I think currently there is a documentation bug: "kbd" is mentioned in
    Panagiotis> text but not used in the example immediately following it.

yes

    Panagiotis> 2. Other documentation sources (emacs lisp reference manual in emacs-29
    Panagiotis> branch) explicitly state that the preferred way to bind keys in emacs 29
    Panagiotis> is using "the syntax supported by 'key-valid-p'" and that "[the old
    Panagiotis> functions] should not be used in new code." (section 23.13 of elisp
    Panagiotis> reference in emacs-29)

yes

    Panagiotis> So, assuming that we want the documentation as a whole to be consistent,
    Panagiotis> I see two ways forward: either we eliminate or reduce the importance of
    Panagiotis> the old functions in the user manual, or we remove the effective
    Panagiotis> deprecation of the old functions in the emacs lisp reference manual and
    Panagiotis> expand on the use of 'kbd', 'global-set-key' and 'define-key'.

    Panagiotis> What do you think?

The syntax accepted by the new functions is that of `kbd', so as long
as that syntax is explained somewhere I guess we can remove references
to `kbd' itself.

Robert
-- 

Previous Next

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