Currently, expansions.asciidoc contains the following sections:
-
Strings describes how quoting works, which is described in more detail in
command-parsing.asciidoc - Typed expansions lists the kinds of typed expansions that exist, but doesn’t list the things each one can expand
- Shell expansions doesn’t say much about actual shell expansions, but does list the shell-encoded names of most or all available expansions
- Markup strings which aren’t expansions or expandable
I find this organisation frustrating, because if I’m looking at a Kakoune script and see some kind of expansion, I can’t just look it up in the expansions docs, I have to notice what type it is, apply the “how are expansions of type X converted to shell variables” rules, and then search for that name.
I think this document would be more useful if it were structured around what Kakoune expansions look like in Kakoune syntax, instead of what they look like in foreign sh syntax:
- an introduction that describes the idea of typed expansions and links to
command-parsing.asciidocfor more general information about string quoting -
arg expansion describes what
%arg{}can expand, and the contexts in which this expansion is available -
opt expansion describes what
%opt{}can expand, and maybe some caveats about scoping (Buf*hooks might not let you access window-scoped option values, for example -
reg expansion describes what
%reg{}can expand, and links toregisters.asciidoc - sh expansion describes how Kakoune’s shell integration works, including the rules for mapping other expansions into shell variable names
-
val expansion describes all the raw, unadorned expandable values, along with caveats about availability (
textis only available in the callback for apromptcommand, selection info is not available outside a window context, etc.)
I think the “Markup strings” information should probably be moved to faces.asciidoc or highlighters.asciidoc.
I’m happy to put in the actual work, but do you think this would be a useful change? Is there anything I’ve missed, or anything that would be better left alone?