Editorial guidelines for Emacs Lisp

- These are the guidelines I follow in the Emacs Lisp source files I maintain.

description, of a procedure
/ Formed e.g. as a documentation string.
: see https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
- Write the first paragraph in the imperative mood, subsequent paragraphs in the indicative.
: see https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
/ I think it incoherent, but here it is the custom.
, of a `defun` procedure
- Put the opening quote on the same line as the first character.
/ Viz. do not use the `"\` trick on the preceding line.
- Otherwise the body of the function indents too far.
face referencing
- Quote each reference to a face where the reference:
a) is formed, as usual, from the proper face name, and
b) will be passed to an evaluator.
- In the case of Font Lock, for example, quote each *facespec* (a) so formed
(or indeed, formed as a list) because (b) Font lock will evaluate it.
: see https://www.gnu.org/software/emacs/manual/html_node/elisp/Search_002dbased-Fontification.html
- That might seem obvious, but many packages define a namesake variable for each face symbol in
order to make this quoting optional. ‘In the vast majority of cases, this is not necessary’.
: see https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Faces.html
- ‘Simply using faces directly is enough.’
: see http://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/font-lock.el?id=fd1b34bfba
setting variables: `setq` vs. `set`
: https://www.gnu.org/software/emacs/manual/html_node/elisp/Setting-Variables.html
- Avoid `set`.
∵ It is blind to lexical bindings.
∵ All of the ‘functions which take a symbol argument (like `symbol-value`, `boundp`,
and `set`) can only retrieve or modify a variable’s dynamic binding (i.e., the contents
of its symbol’s value cell).’
: see https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html
∵ Using it consistently requires a sacrifice of code simplicity and clarity.
∵ It sets at most one variable, whereas `setq` sets any number.