From 4e2e971033664ec257b3b6dabc053deb6cff17e1 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Thu, 31 May 2018 21:14:21 +1000 Subject: [PATCH] Update commands.asciidoc, options.asciidoc and expansions.asciidoc pages --- doc/pages/commands.asciidoc | 4 +-- doc/pages/expansions.asciidoc | 15 ++++++----- doc/pages/options.asciidoc | 50 ++++++++++++++++++----------------- 3 files changed, 37 insertions(+), 32 deletions(-) diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc index cd79d26a0..6a8b241bb 100644 --- a/doc/pages/commands.asciidoc +++ b/doc/pages/commands.asciidoc @@ -243,8 +243,8 @@ but not really useful in that context. *alias* reg + set register *name* to *content* (See <>) -*select* .,.:...:: - replace the current selections with the one described in the argument +*select* .,....:: + replace the current selections with the ones described in the arguments *debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}:: print some debug information in the *\*debug** buffer diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index ac7838f8c..2a02cc581 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -64,15 +64,14 @@ informations about Kakoune's state: content of the main selection *kak_selections*:: - content of the selection separated by colons, colons in the selection - contents are escaped with a backslash + quoted list of the contents of the selections. *kak_selection_desc*:: range of the main selection, represented as anchor,cursor; anchor and cursor are in this format: line.column *kak_selections_desc*:: - range of the selections separated by colons + unquoted list range of the selections. *kak_bufname*:: name of the current buffer @@ -82,7 +81,7 @@ informations about Kakoune's state: associated file *kak_buflist*:: - the current buffer list, each buffer separated by a colon + quoted list of the currently opened buffer names *kak_buf_line_count*:: the current buffer line count @@ -127,7 +126,7 @@ informations about Kakoune's state: process id of the current client *kak_client_list*:: - list of clients connected to the current session + unquoted list of the names of clients connected to the current session *kak_source*:: path of the file currently getting executed (through the source @@ -168,7 +167,11 @@ informations about Kakoune's state: (e.g. *$kak_client_env_SHELL* is the SHELL variable) *kak_user_modes*:: - the user modes list, each modes separated by a colon + unquoted list of user modes. + +Quoted lists are separated by spaces, and each element is surrounded by +`'` with contained `'` doubled. Unquoted lists are simply separated by +spaces and is used for values that will not contain whitespaces. Note that in order for Kakoune to pass a value in the environment, the variable has to be spelled out within the body of the expansion. diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc index b8a66cc5b..f17e0c336 100644 --- a/doc/pages/options.asciidoc +++ b/doc/pages/options.asciidoc @@ -9,14 +9,17 @@ scripts. [[set-option]] Options can be modified using the `set-option` command: ---------------------------------- -set-option [-add] ---------------------------------- +-------------------------------------------- +set-option [-add] ... +-------------------------------------------- can be *global*, *buffer*, *window* or *current* (See <>). *current* relates to the narrowest scope in which the option is already set. +Multiple can be given as separate arguments when the option is a +list or map. + If `-add` is specified, the new value is *added* to the current one instead of replacing it (the exact outcome depends on the type, see below). @@ -34,9 +37,9 @@ hence options cannot be unset from the *global* scope. [[declare-option]] New options can be declared using the `declare-option` command: ------------------------------------------------- -declare-option [-hidden] [] ------------------------------------------------- +--------------------------------------------------- +declare-option [-hidden] [...] +--------------------------------------------------- If `-hidden` is specified, the option will not be displayed in completion suggestions. @@ -76,35 +79,34 @@ are exclusively available to built-in options. a line, column pair (separated by a comma) *-list*:: - a list, elements are separated by a colon (:) if an element needs - to contain a colon, it can be escaped with a backslash. + a list, elements are specified as separate arguments to the command. `set -add` appends the new element to the list *range-specs*:: - a `:` separated list of a pair of a buffer range (`.,.` or `.+`) and a string (separated by `|`), except for the - first element which is just the timestamp of the buffer. When the - `update-option` is used on an option of this type, its ranges gets - updated according to all the buffer modifications that happened - since its timestamp. + a list of a pair of a buffer range (`., + .` or `.+`) + and a string (separated by `|`), except for the first element which + is just the timestamp of the buffer. When the `update-option` is + used on an option of this type, its ranges gets updated according + to all the buffer modifications that happened since its timestamp. See <>) `set -add` appends the new pair to the list *line-specs*:: - a `:` separated list of a line number and a corresponding flag - (`|`), except for the first element which is just - the timestamp of the buffer. When the `update-option` is used on - an option of this type, its lines gets updated according to all the - buffer modifications that happened since its timestamp. + a list of a line number and a corresponding flag (`|`), except for the first element which is just the timestamp + of the buffer. When the `update-option` is used on an option of this + type, its lines gets updated according to all the buffer modifications + that happened since its timestamp. See <>) `set -add` appends the new spec to the list *completions*:: - a `:` separated list of `||` - candidates, except for the first element which follows the + a list of `||` candidates, + except for the first element which follows the `.[+]@` format to define where the completion apply in the buffer. Markup can be used in the menu text. + `set -add` adds a new completion to the list *enum(value1|value2|...)*:: an enum, taking one of the given values @@ -115,7 +117,7 @@ are exclusively available to built-in options. `set -add` adds the new flag to the combination *-to--map*:: - a `:` separated list of `key=value` pairs. + a list of `key=value` pairs. `set -add` adds the new pair to the hashmap or replace an already existing key. @@ -254,7 +256,7 @@ are exclusively available to built-in options. The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]' *ui_options* `str-to-str-map`:: - colon separated list of key=value pairs that are forwarded to the user + a list of `key=value` pairs that are forwarded to the user interface implementation. The NCurses UI support the following options: *ncurses_set_title*:::