Complex SPEC for variables/customization like font-lock-keywords/org-capture-templates/etc (was: Instead of pcase)

[Ihor Radchenko]

Philip Kaludercic <philipk@posteo.net> writes:

> Michael Heerdegen <michael_heerdegen@web.de> writes:
>
> ...  If one has to talk about difficult to understand/remember
> domain specific languages, then `font-lock-defaults' would be a much
> more pressing candidate.

Or font-lock-keywords... Last time I were seriously developing new
keywords, I had to do it by trial-and-error and even examine font-lock
sources.

We also have similar issues with complex specifications in Org mode -
org-capture-templates, org-agenda-custom-commands, etc.

I believe that it is a general problem relevant various non-trivial
variables/customization we have across Emacs and Emacs packages -
developers, or, more frequently, Emacs users have significant
difficulties understanding the obscure ad-hoc languages we have to
invent for font-locking, templates, etc.

The most common confusions are related to:

1. Quoting deeply nested lists
2. Keeping track of what each of the list elements refers to.
   For example, font-lock-keywords may contain something like
   
   (lisp--match-hidden-arg
   (0
    '(face font-lock-warning-face help-echo
           "Easy to misread; consider moving the element to the next line")
    prepend))

    It is hard to parse without constantly examining the docstring.

Customize interface somewhat helps with (2), but many users avoid it and
instead prefer to write init.el manually. Also, developers cannot even
use customize interface (for example when developing
font-lock-keywords).

(1) is also a rather common problem, especially when both quoted and
unquoted version of a list element are technically valid (for example,
consider 'face-name vs. face-name in font-lock-keywords - a rather
common confusion for me).

I do not know a good solution to the above, and thus would like to
discuss this problem.

Some possible ideas:

1. Provide some universal mechanism for type-validation of variables.
   Something similar to :type spec in defcustom, but for Elisp
   variables. This will at least catch invalid values.

2. Provide custom warning mechanism catching common mistakes in the
   variables SPEC. For example, 'face-name vs. face-name for
   font-lock-keywords in the above example.

3. Enhance eldoc to show a tip about variable value structure, similar
   to what is done for function arguments.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>