options.asciidoc: Document other option commands, remove tabs

doc/pages/options.asciidoc

@@ -2,18 +2,31 @@
 
 == Description
 
-Kakoune can store named and typed values that can be used both to customize
+Kakoune can store named and typed values that can be used both to
-the core editor behaviour, and to store data used by extension scripts.
+customize the core editor behaviour, and to store data used by extension
+scripts.
 
-Options can be modified using the *set-option* command:
+Options can be modified using the `set-option` command:
 
 ---------------------------------
 set-option <scope> <name> <value>
 ---------------------------------
 
-<scope> can be *global*, *buffer* or *window* (See <<scopes#,`:doc scopes`>>)
+<scope> can be *global*, *buffer*, *window* or *current* (See
+<<scopes#,`:doc scopes`>>). *current* relate to the narrowest scope in
+which the option is already set.
 
-New options can be declared using the *declare-option* command:
+Options values can be unset in a specific scope with the `unset-option`
+command:
+
+---------------------------
+unset-option <scope> <name>
+---------------------------
+
+Unsetting an option will make it fallback to the value of its parent mode,
+hence options cannot be unset from the *global* scope.
+
+New options can be declared using the `declare-option` command:
 
 ------------------------------------------------
 declare-option [-hidden] <type> <name> [<value>]
@@ -22,120 +35,138 @@ declare-option [-hidden] <type> <name> [<value>]
 If `-hidden` is specified, the option will not be displayed in completion
 suggestions.
 
+Certain option type can be *updated*, usually to match potential changes
+in the buffer they relate to. This can be triggered by the `update-option`
+command:
+
+----------------------------
+update-option <scope> <name>
+----------------------------
+
 == Types
 
-All options have a type, which defines how they are translated to/from text
+All options have a type, which defines how they are translated to/from
-and their set of valid values.
+text and their set of valid values.
 
 Some types are usable for user defined options while some other types
 are exclusively available to built-in options.
 
 *int*::
     an integer number
+
 *bool*::
     a boolean value, yes/true or no/false
+
 *str*::
     a string, some freeform text
+
 *regex*::
     as a string but the set commands will complain if the entered text
     is not a valid regex
+
 *coord*::
     a line, column pair (separated by comma)
+
 *<type>-list*::
     a list, elements are separated by a colon (:) if an element needs
     to contain a colon, it can be escaped with a backslash
+
 *range-specs*::
     a `:` separated list of a pair of a buffer range (`<begin
-	line>.<begin column>,<end line>.<end column>` or `<begin
+    line>.<begin column>,<end line>.<end column>` or `<begin line>.<begin
-	line>.<begin column>+<length>`) and a string (separated by `|`),
+    column>+<length>`) and a string (separated by `|`), except for the
-	except for the first element which is just the timestamp of
+    first element which is just the timestamp of the buffer.  When the
-	the buffer.  When the `update-option` is used on an option of
+    `update-option` is used on an option of this type, its ranges gets
-	this type, its ranges gets updated according to all the buffer
+    updated according to all the buffer modifications that happened
-	modifications that happened since its timestamp.
+    since its timestamp.
+
 *line-specs*::
     a `:` separated list of a line number and a corresponding flag
-	(`<line>|<flag text>`), except for the first element which is
+    (`<line>|<flag text>`), except for the first element which is just
-	just the timestamp of the buffer. When the `update-option` is
+    the timestamp of the buffer. When the `update-option` is used on
-	used on an option of this type, its lines gets updated according
+    an option of this type, its lines gets updated according to all the
-	to all the buffer modifications that happened since its timestamp.
+    buffer modifications that happened since its timestamp.
+
 *completions*::
     a `:` separated list of `<text>|<docstring>|<menu text>`
     candidates, 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.
+
 *enum(value1|value2|...)*::
     an enum, taking one of the given values
+
 *flags(value1|value2|...)*::
     a set of flags, taking a combination of the given values joined by a
     '|' character
 
 == Builtin options
 
-*tabstop* 'int'::
+*tabstop* `int`::
     *default* 8 +
     width of a tab character
 
-*indentwidth* 'int'::
+*indentwidth* `int`::
     *default* 4 +
     width (in spaces) used for indentation, 0 means a tab character
 
-*scrolloff* 'coord'::
+*scrolloff* `coord`::
     *default* 0,0 +
     number of lines, columns to keep visible around the cursor when
     scrolling
 
-*eolformat* 'enum(lf|crlf)'::
+*eolformat* `enum(lf|crlf)`::
     *default* lf +
     the format of end of lines when writing a buffer, this is autodetected
     on load; values of this option assigned to the `window` scope are
     ignored
 
-*BOM* 'enum(none|utf8)'::
+*BOM* `enum(none|utf8)`::
     *default* none +
     define if the file should be written with a unicode byte order mark;
     values of this option assigned to the `window` scope are ignored
 
-*readonly* 'bool'::
+*readonly* `bool`::
     *default* false +
     prevent modifications from being saved to disk, all buffers if set
     to `true` in the `global` scope, or current buffer if set in the
     `buffer` scope; values of this option assigned to the `window`
     scope are ignored
 
-*incsearch* 'bool'::
+*incsearch* `bool`::
     *default* true +
     execute search as it is typed
 
-*aligntab* 'bool'::
+*aligntab* `bool`::
     *default* false +
     use tabs for alignment command
 
-*autoinfo* 'flags(command|onkey|normal)'::
+*autoinfo* `flags(command|onkey|normal)`::
     *default* command|onkey +
     display automatic information box in the enabled contexts
 
-*autoshowcompl* 'bool'::
+*autoshowcompl* `bool`::
     *default* true +
     automatically display possible completions when editing a prompt
 
-*ignored_files* 'regex'::
+*ignored_files* `regex`::
-	filenames matching this regex won't be considered as candidates on
+    filenames matching this regex won't be considered as candidates
-	filename completion (except if the text being completed already
+    on filename completion (except if the text being completed already
     matches it)
 
-*disabled_hooks* 'regex'::
+*disabled_hooks* `regex`::
     hooks whose group matches this regex won't be executed. For example
-	indentation hooks can be disabled with '.*-indent'
+    indentation hooks can be disabled with `.*-indent`
 
-*filetype* 'str'::
+*filetype* `str`::
     arbitrary string defining the type of the file filetype dependant
     actions should hook on this option changing for activation/deactivation
 
-*path* 'str-list'::
+*path* `str-list`::
     *default* ./:/usr/include +
     directories to search for gf command
 
-*completers* 'completer-list'::
+*completers* `completer-list`::
     *default* filename:word=all +
     completion engines to use for insert mode completion (they are tried
     in order until one generates candidates). Existing completers are:
@@ -155,36 +186,36 @@ are exclusively available to built-in options.
         where *opt-name* is an option of type 'completions' whose
         contents will be used
 
-*static_words* 'str-list'::
+*static_words* `str-list`::
     list of words that are always added to completion candidates
     when completing words in insert mode
 
-*extra_word_chars* 'codepoint-list'::
+*extra_word_chars* `codepoint-list`::
     a list of all additional codepoints that should be considered
     as word character for the purpose of insert mode completion.
 
-*autoreload* 'enum(yes|no|ask)'::
+*autoreload* `enum(yes|no|ask)`::
     *default* ask +
     auto reload the buffers when an external modification is detected
 
-*debug* 'flags(hooks|shell|profile|keys|commands)'::
+*debug* `flags(hooks|shell|profile|keys|commands)`::
     dump various debug information in the '\*debug*' buffer
 
-*idle_timeout* 'int'::
+*idle_timeout* `int`::
     *default* 50 +
     timeout, in milliseconds, with no user input that will trigger the
     *PromptIdle*, *InsertIdle* and *NormalIdle* hooks, and autocompletion.
 
-*fs_checkout_timeout* 'int'::
+*fs_checkout_timeout* `int`::
     *default* 500 +
     timeout, in milliseconds, between checks in normal mode of modifications
     of the file associated with the current buffer on the filesystem.
 
-*modelinefmt* 'string'::
+*modelinefmt* `string`::
-	A format string used to generate the mode line, that string is first
+    A format string used to generate the mode line, that string is
-	expanded as a command line would be (expanding '%...{...}' strings),
+    first expanded as a command line would be (expanding '%...{...}'
-	then markup tags are applied (c.f. the 'Expansions' documentation page.)
+    strings), then markup tags are applied (c.f. the 'Expansions'
-	Two special atoms are available as markup:
+    documentation page.)  Two special atoms are available as markup:
 
         *`{{mode_info}}`*:::
             Information about the current mode, such as `insert 3 sel` or
@@ -197,7 +228,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'::
+*ui_options* `str-to-str-map`::
     colon separated list of key=value pairs that are forwarded to the user
     interface implementation. The NCurses UI support the following options: