Proposal: Reorganising the expansions documentation

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.asciidoc for 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 to registers.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 (text is only available in the callback for a prompt command, 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?

I agree with this change, it makes more sense to specify the expansions in kakoune itself and describe how to transfer them to bash variables. Instead of the other way around.

I agree it makes more sense to do it that way, the current way is the result of history, where %val{...} appeared later on as a way to avoid a shell scope to just access an exported env var.

The associated PR is ready for review: