Update commands.asciidoc, options.asciidoc and expansions.asciidoc pages

doc/pages/commands.asciidoc

@@ -243,8 +243,8 @@ but not really useful in that context.
     *alias* reg +
     set register *name* to *content* (See <<registers#,`:doc registers`>>)
 
-*select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...::
+*select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>...::
-    replace the current selections with the one described in the argument
+    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

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
+    quoted list of the contents of the selections.
-    contents are escaped with a backslash
 
 *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.

doc/pages/options.asciidoc

@@ -9,14 +9,17 @@ scripts.
 [[set-option]]
 Options can be modified using the `set-option` command:
 
----------------------------------
+--------------------------------------------
-set-option [-add] <scope> <name> <value>
+set-option [-add] <scope> <name> <values>...
----------------------------------
+--------------------------------------------
 
 <scope> can be *global*, *buffer*, *window* or *current* (See
 <<scopes#,`:doc scopes`>>). *current* relates to the narrowest scope in
 which the option is already set.
 
+Multiple <values> 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] <type> <name> [<value>]
+declare-option [-hidden] <type> <name> [<value>...]
-------------------------------------------------
+---------------------------------------------------
 
 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)
 
 *<type>-list*::
-    a list, elements are separated by a colon (:) if an element needs
+    a list, elements are specified as separate arguments to the command.
-    to contain a colon, it can be escaped with a backslash.
     `set -add` appends the new element to the list
 
 *range-specs*::
-    a `:` separated list of a pair of a buffer range (`<begin
+    a list of a pair of a buffer range (`<begin line>.<begin column>,
-    line>.<begin column>,<end line>.<end column>` or `<begin line>.<begin
+    <end line>.<end column>` or `<begin line>.<begin column>+<length>`)
-    column>+<length>`) and a string (separated by `|`), except for the
+    and a string (separated by `|`), except for the first element which
-    first element which is just the timestamp of the buffer. When the
+    is just the timestamp of the buffer. When the `update-option` is
-    `update-option` is used on an option of this type, its ranges gets
+    used on an option of this type, its ranges gets updated according
-    updated according to all the buffer modifications that happened
+    to all the buffer modifications that happened since its timestamp.
-    since its timestamp.
     See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
     `set -add` appends the new pair to the list
 
 *line-specs*::
-    a `:` separated list of a line number and a corresponding flag
+    a list of a line number and a corresponding flag (`<line>|<flag
-    (`<line>|<flag text>`), except for the first element which is just
+    text>`), except for the first element which is just the timestamp
-    the timestamp of the buffer. When the `update-option` is used on
+    of the buffer. When the `update-option` is used on an option of this
-    an option of this type, its lines gets updated according to all the
+    type, its lines gets updated according to all the buffer modifications
-    buffer modifications that happened since its timestamp.
+    that happened since its timestamp.
     See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
     `set -add` appends the new spec to the list
 
 *completions*::
-    a `:` separated list of `<text>|<docstring>|<menu text>`
+    a list of `<text>|<docstring>|<menu text>` candidates,
-    candidates, except for the first element which follows the
+    except for the first element which follows the
     `<line>.<column>[+<length>]@<timestamp>` 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
 
 *<type>-to-<type>-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*:::