bug#56217: 26.3; Elisp manual: Document keyword parameters to a function (lambda list)

bug#56217: 26.3; Elisp manual: Document keyword parameters to a function (lambda list)

[Drew Adams]

Searching the Index of the Elisp manual for "keyword", I don't see any
entries that help you get to doc about keyword parameters in a lambda
list.  (I mean the use of a keyword such as :keymap with
`define-minor-mode', not a description of things like `&rest'.)

Please add some index entries for this.

What's more, I don't even find any presentation in the manual about
keyword parameters, except for the mention more or less in passing of
some specific keyword parameters in node `Defining Minor Modes'.  Please
add a description.  Users should get info about how
actual arguments are processed - e.g., in what order, when for example,
optional and keyword args are both accepted by a function.

(It's possible that there _is_ some such specification/explanation of
what keyword parameters are, and how they're processed - e.g., in what
order, but I didn't find any.)

Keyword args are particular, in that to pass one you pass _two_ Lisp
values: first the keyword symbol and then the value for that keyword.
That isn't the case for other arguments.

In addition there's the question of whether supplied keyword args
are included in those accumulated for the &rest arg.

See Common Lisp for how it handles this:

  Next, any keyword parameters are processed. For this purpose the
  same arguments are processed that would be made into a list for a
  rest parameter. (Indeed, it is permitted to specify both &rest and
  &key. In this case the remaining arguments are used for both
  purposes; that is, all remaining arguments are made into a list
  for the &rest parameter and are also processed for the &key
  parameters. This is the only situation in which an argument is
  used in the processing of more than one parameter specifier.)

  -- Common Lisp The Language (2), section 5.2.2, Lambda-Expressions

Whatever the Elisp way of handling keyword parameters might be,
it should be clearly specified somewhere in the manual.  So far,
all I've found it a bit of hand-waving.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19044
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''