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.



                                                    \ Copyright © 2020-2021  Michael Allan.  Licence MIT.