options.asciidoc: Document other option commands, remove tabs

This commit is contained in:
Maxime Coste 2017-11-02 17:36:10 +08:00
parent 730e5725e9
commit 3c2159f06c

View File

@ -2,18 +2,31 @@
== Description == 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> 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>] declare-option [-hidden] <type> <name> [<value>]
@ -22,203 +35,221 @@ declare-option [-hidden] <type> <name> [<value>]
If `-hidden` is specified, the option will not be displayed in completion If `-hidden` is specified, the option will not be displayed in completion
suggestions. 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 == 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 Some types are usable for user defined options while some other types
are exclusively available to built-in options. are exclusively available to built-in options.
*int*:: *int*::
an integer number an integer number
*bool*:: *bool*::
a boolean value, yes/true or no/false a boolean value, yes/true or no/false
*str*:: *str*::
a string, some freeform text a string, some freeform text
*regex*:: *regex*::
as a string but the set commands will complain if the entered text as a string but the set commands will complain if the entered text
is not a valid regex is not a valid regex
*coord*:: *coord*::
a line, column pair (separated by comma) a line, column pair (separated by comma)
*<type>-list*:: *<type>-list*::
a list, elements are separated by a colon (:) if an element needs a list, elements are separated by a colon (:) if an element needs
to contain a colon, it can be escaped with a backslash to contain a colon, it can be escaped with a backslash
*range-specs*:: *range-specs*::
a `:` separated list of a pair of a buffer range (`<begin 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*:: *line-specs*::
a `:` separated list of a line number and a corresponding flag 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*:: *completions*::
a `:` separated list of `<text>|<docstring>|<menu text>` a `:` separated list of `<text>|<docstring>|<menu text>`
candidates, except for the first element which follows the candidates, except for the first element which follows the
`<line>.<column>[+<length>]@<timestamp>` format to define where the `<line>.<column>[+<length>]@<timestamp>` format to define where the
completion apply in the buffer. Markup can be used in the menu text. completion apply in the buffer. Markup can be used in the menu text.
*enum(value1|value2|...)*:: *enum(value1|value2|...)*::
an enum, taking one of the given values an enum, taking one of the given values
*flags(value1|value2|...)*:: *flags(value1|value2|...)*::
a set of flags, taking a combination of the given values joined by a a set of flags, taking a combination of the given values joined by a
'|' character '|' character
== Builtin options == Builtin options
*tabstop* 'int':: *tabstop* `int`::
*default* 8 + *default* 8 +
width of a tab character width of a tab character
*indentwidth* 'int':: *indentwidth* `int`::
*default* 4 + *default* 4 +
width (in spaces) used for indentation, 0 means a tab character width (in spaces) used for indentation, 0 means a tab character
*scrolloff* 'coord':: *scrolloff* `coord`::
*default* 0,0 + *default* 0,0 +
number of lines, columns to keep visible around the cursor when number of lines, columns to keep visible around the cursor when
scrolling scrolling
*eolformat* 'enum(lf|crlf)':: *eolformat* `enum(lf|crlf)`::
*default* lf + *default* lf +
the format of end of lines when writing a buffer, this is autodetected 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 on load; values of this option assigned to the `window` scope are
ignored ignored
*BOM* 'enum(none|utf8)':: *BOM* `enum(none|utf8)`::
*default* none + *default* none +
define if the file should be written with a unicode byte order mark; define if the file should be written with a unicode byte order mark;
values of this option assigned to the `window` scope are ignored values of this option assigned to the `window` scope are ignored
*readonly* 'bool':: *readonly* `bool`::
*default* false + *default* false +
prevent modifications from being saved to disk, all buffers if set prevent modifications from being saved to disk, all buffers if set
to `true` in the `global` scope, or current buffer if set in the to `true` in the `global` scope, or current buffer if set in the
`buffer` scope; values of this option assigned to the `window` `buffer` scope; values of this option assigned to the `window`
scope are ignored scope are ignored
*incsearch* 'bool':: *incsearch* `bool`::
*default* true + *default* true +
execute search as it is typed execute search as it is typed
*aligntab* 'bool':: *aligntab* `bool`::
*default* false + *default* false +
use tabs for alignment command use tabs for alignment command
*autoinfo* 'flags(command|onkey|normal)':: *autoinfo* `flags(command|onkey|normal)`::
*default* command|onkey + *default* command|onkey +
display automatic information box in the enabled contexts display automatic information box in the enabled contexts
*autoshowcompl* 'bool':: *autoshowcompl* `bool`::
*default* true + *default* true +
automatically display possible completions when editing a prompt 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) matches it)
*disabled_hooks* 'regex':: *disabled_hooks* `regex`::
hooks whose group matches this regex won't be executed. For example 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 arbitrary string defining the type of the file filetype dependant
actions should hook on this option changing for activation/deactivation actions should hook on this option changing for activation/deactivation
*path* 'str-list':: *path* `str-list`::
*default* ./:/usr/include + *default* ./:/usr/include +
directories to search for gf command directories to search for gf command
*completers* 'completer-list':: *completers* `completer-list`::
*default* filename:word=all + *default* filename:word=all +
completion engines to use for insert mode completion (they are tried completion engines to use for insert mode completion (they are tried
in order until one generates candidates). Existing completers are: in order until one generates candidates). Existing completers are:
*word=all*, *word=buffer*::: *word=all*, *word=buffer*:::
which complete using words in all buffers (*word=all*) which complete using words in all buffers (*word=all*)
or only the current one (*word=buffer*) or only the current one (*word=buffer*)
*filename*::: *filename*:::
which tries to detect when a filename is being entered and which tries to detect when a filename is being entered and
provides completion based on local filesystem provides completion based on local filesystem
*line*::: *line*:::
which complete using lines in current buffer which complete using lines in current buffer
*option=<opt-name>*::: *option=<opt-name>*:::
where *opt-name* is an option of type 'completions' whose where *opt-name* is an option of type 'completions' whose
contents will be used contents will be used
*static_words* 'str-list':: *static_words* `str-list`::
list of words that are always added to completion candidates list of words that are always added to completion candidates
when completing words in insert mode 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 a list of all additional codepoints that should be considered
as word character for the purpose of insert mode completion. as word character for the purpose of insert mode completion.
*autoreload* 'enum(yes|no|ask)':: *autoreload* `enum(yes|no|ask)`::
*default* ask + *default* ask +
auto reload the buffers when an external modification is detected 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 dump various debug information in the '\*debug*' buffer
*idle_timeout* 'int':: *idle_timeout* `int`::
*default* 50 + *default* 50 +
timeout, in milliseconds, with no user input that will trigger the timeout, in milliseconds, with no user input that will trigger the
*PromptIdle*, *InsertIdle* and *NormalIdle* hooks, and autocompletion. *PromptIdle*, *InsertIdle* and *NormalIdle* hooks, and autocompletion.
*fs_checkout_timeout* 'int':: *fs_checkout_timeout* `int`::
*default* 500 + *default* 500 +
timeout, in milliseconds, between checks in normal mode of modifications timeout, in milliseconds, between checks in normal mode of modifications
of the file associated with the current buffer on the filesystem. 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}}`*::: *`{{mode_info}}`*:::
Information about the current mode, such as `insert 3 sel` or Information about the current mode, such as `insert 3 sel` or
`prompt`. The faces used are StatusLineMode, StatusLineInfo, `prompt`. The faces used are StatusLineMode, StatusLineInfo,
and StatusLineValue. and StatusLineValue.
*`{{context_info}}`*::: *`{{context_info}}`*:::
Information such as `[+][recording (@)][no-hooks][new file][fifo]`, Information such as `[+][recording (@)][no-hooks][new file][fifo]`,
in face Information. in face Information.
The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]' 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 colon separated list of key=value pairs that are forwarded to the user
interface implementation. The NCurses UI support the following options: interface implementation. The NCurses UI support the following options:
*ncurses_set_title*::: *ncurses_set_title*:::
if *yes* or *true*, the terminal emulator title will if *yes* or *true*, the terminal emulator title will
be changed be changed
*ncurses_status_on_top*::: *ncurses_status_on_top*:::
if *yes*, or *true* the status line will be placed if *yes*, or *true* the status line will be placed
at the top of the terminal rather than at the bottom at the top of the terminal rather than at the bottom
*ncurses_assistant*::: *ncurses_assistant*:::
specify the nice assistant you get in info boxes, specify the nice assistant you get in info boxes,
can be *clippy* (the default), *cat*, *dilbert* or *none* can be *clippy* (the default), *cat*, *dilbert* or *none*
*ncurses_enable_mouse*::: *ncurses_enable_mouse*:::
boolean option that enables mouse support boolean option that enables mouse support
*ncurses_change_colors*::: *ncurses_change_colors*:::
boolean option that can disable color palette changing if the boolean option that can disable color palette changing if the
terminfo enables it but the terminal does not support it. terminfo enables it but the terminal does not support it.
*ncurses_wheel_down_button*, *ncurses_wheel_up_button*::: *ncurses_wheel_down_button*, *ncurses_wheel_up_button*:::
specify which button send for wheel down/up events specify which button send for wheel down/up events