doc.kak: Render documentation internally instead of relying on man

doc.kak now behaves as a basic asciidoc renderer. Asciidoc is unfortunately
still a dependency to generate the manpage of the `kak` command.
This commit is contained in:
Maxime Coste 2017-11-02 10:03:24 +08:00
parent 90865b65cd
commit 4fabba3d12
15 changed files with 162 additions and 285 deletions

View File

@ -1,12 +1,6 @@
kakoune(k)
==========
= Commands
NAME
----
commands - a
Builtins
--------
== Builtins
Some commands take an exclamation mark (*!*), which can be used to force
the execution of the command (i.e. to quit a modified buffer, the
@ -169,8 +163,8 @@ command *q!* has to be used). Aliases are mentionned below each commands.
remove the highlighter whose id is *highlighter_id* (c.f. the
'highlighters' documentation page)
Helpers
-------
== Helpers
Kakoune provides some helper commands that can be used to define composite
commands:
@ -230,14 +224,14 @@ commands:
Note that those commands are also available in the interactive mode, but
are not really useful in that context.
Multiple commands
-----------------
== Multiple commands
Commands (c.f. previous sections) can be chained, by being separated either
by new lines or by semicolons, as such a semicolon must be escaped with a
backslash (\;) to be considered as a literal semicolon argument
Declaring new commands
----------------------
== Declaring new commands
New commands can be defined using the *define-command* command:
*define-command* [flags] <command_name> <commands>::

View File

@ -1,12 +1,7 @@
kakoune(k)
==========
= Exec and Eval
NAME
----
execeval - a
== Description
Description
-----------
The *exec* and *eval* commands can be used to run Kakoune commands, and
should be used as follows:
@ -23,8 +18,8 @@ the last key/command is reached, or an error is raised.
These two commands also save the following registers, who are then restored
when the commands have been executed: */*, *"*, *|*, *^*, *@*.
Optional flags
--------------
== Optional flags
*-client* <name>::
execute in the context of the client named *name*

View File

@ -1,12 +1,7 @@
kakoune(k)
==========
= Expansions
NAME
----
expansions - a
== Strings
Strings
-------
\'strings'::
uninterpreted strings, use a backslash (\') to escape the separator
"strings"::
@ -29,8 +24,7 @@ e.g. %[string], %<string>, %(string), %~string~, %!string!
e.g. %{ roger {}; } is a valid string, %{ marcel \} as well
-----------------------------------------------------------
Typed expansions
----------------
== Typed expansions
%\{strings\} can have an expansion type between the *%* and the opening
character. They will be written *%<type>\{<content>\}*. They will be
@ -54,8 +48,8 @@ parameter:
argument expansion, expand to the arguments of the current
command, *<content>* can be a number, or @ for all arguments
Shell expansions
----------------
== Shell expansions
The '%sh{...}' expansion replaces its content with the output of the
shell commands in it. The following environment variables are used to pass
informations about Kakoune's state:
@ -131,8 +125,8 @@ informations about Kakoune's state:
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
Markup strings
--------------
== Markup strings
In certain contexts, Kakoune can take a markup string, which is a string
containing formatting informations. In these strings, the {facename}
syntax will enable the face facename until another face gets activated,

View File

@ -1,12 +1,7 @@
kakoune(k)
==========
= Faces
NAME
----
faces - a
== Declaration
Declaration
-----------
A 'face' refers how the specified text is displayed, it has a foreground
color, a background color, and some attributes. The value of a face has the
following format:
@ -42,8 +37,8 @@ fg_color[,bg_color][+attributes]
exclusive, override previous faces instead of merging
with them
Builtin faces
-------------
== Builtin faces
The following default faces are used by color schemes to highlight certain
areas of the user interface:

View File

@ -1,19 +1,12 @@
kakoune(k)
==========
= FAQ
NAME
----
faq - a
How to pronounce the name of the project and what does it mean ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== How to pronounce the name of the project and what does it mean ?
The name of the project is pronounced "Kak-oon", and is a word taken from a
New Caledonian dialect based on french. It means a hard blow, usually a punch,
but generally refers to a blow into which all of one's strength went.
Is there going to be a Windows port of Kakoune ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Is there going to be a Windows port of Kakoune ?
As many features provided by UNIX systems would be missing, or if anything
much less efficient on a Windows system, the incentive to porting the
@ -22,8 +15,7 @@ project to this operating system is pretty low.
Moreover, you can get pretty decent performance by using Kakoune on Cygwin
(which is officially supported).
Kakoune is very slow on big files, what can I do about it ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Kakoune is very slow on big files, what can I do about it ?
The default build mode (set in the `Makefile` of the `src` directory of the
project) is "debug", which makes it convenient to track issues but also
@ -34,21 +26,18 @@ Note that if your distribution provides a "kakoune" package, the program should
already be built in non-debug mode (if you still experience slowness, please
report the issue on the bug tracker).
Can I use Kakoune as a pager ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Can I use Kakoune as a pager ?
Kakoune can be used as a pager, either by setting the `PAGER` environment
variable to `kak`, or by writing data directly to its standard input using a
shell pipeline.
Are there any non-console based frontends available ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Are there any non-console based frontends available ?
No graphical frontend is currently officially maintained, you can however
try experimental community-developed ones.
Why are colors misrendered in my Kakoune clients ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Why are colors misrendered in my Kakoune clients ?
The most probable cause for that is a very widespread practice that consists
in setting the `TERM` environment variable in the shell's configuration file.
@ -60,16 +49,14 @@ Note that if you're using `tmux`, the proper -official- way to get Kakoune to
work is to add the following line to your `tmux` configuration file:
`set -sg default-terminal screen-256color`
Why does leaving insert mode take more than half a second in `tmux` ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Why does leaving insert mode take more than half a second in `tmux` ?
Upon hitting the escape key, `tmux` waits for a short period of time to
determine whether it's part of a function or a meta key sequence. In order
to fix this "lag", set the waiting period in your `tmux` configuration file
to a short time, e.g. 25ms: `set -sg escape-time 25`
How do I automatically indent code, as Vim does with `=` ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== How do I automatically indent code, as Vim does with `=` ?
As `Kakoune` doesn't parse the contents of the buffers, there is no builtin
equivalent for this Vim feature. Use a formatter/prettifier dedicated to
@ -80,8 +67,7 @@ Example: `%|indent<ret>` to indent an entire buffer with C code.
Note that some languages have a default formatter set, which you can use
with the `:format` command.
Can Kakoune automatically complete the parameters of my functions ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Can Kakoune automatically complete the parameters of my functions ?
As mentioned in the above question about Vim's `=` key, Kakoune does not
parse the contents of a buffer by itself, which makes it impossible for
@ -95,8 +81,7 @@ editing a C/C++ file, and completion will work on function parameters.
Note that the same features are available for python buffers, with the
`jedi` script.
Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Why aren't widely known command line shortcuts such as <c-w> or <c-u> available in Kakoune ?
Despite their widespread availability in multiple tools, those shortcuts do
not fit the paradigm that Kakoune implements, which is based on selections
@ -106,8 +91,7 @@ However, you can easily declare key mappings in your configuration file
to be able to use those control-based shortcuts in insert mode (c.f. the
"map" command in the "commands" documentation page).
How can I explore the filesystem the way Vim's NerdTree does ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== How can I explore the filesystem the way Vim's NerdTree does ?
The builtin file completion engine used when opening a file for editing
(using the `:edit` command and letting the suggestions popup in the menu
@ -119,8 +103,7 @@ which should in return send an "edit" command followed by the path of the
file you selected to the current Kakoune session (e.g. `echo "eval -client
$kak_client edit /path/to/file" | kak -p $kak_session`).
Why aren't there other scopes similar to `%sh{}` e.g. python ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Why aren't there other scopes similar to `%sh{}` e.g. python ?
Supporting custom scopes would add hard dependencies to the project, which
is too much of a drawback when balanced against the low cost of using
@ -129,8 +112,7 @@ The shell scope allows users to spawn any interpreter they want, for a minimal
cost in terms of performance, it is therefore the reason why it's the only
one available by default.
What shell is used to expand `%sh{}` scopes ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== What shell is used to expand `%sh{}` scopes ?
The server expands shell scopes using the `sh` binary, stored in one of the
directories where all the POSIX standard utilities can be found -this list
@ -139,22 +121,19 @@ by Kakoune at startup.
In most distributions, `/bin/sh` will end up being used.
Can I disable auto-indentation completely ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Can I disable auto-indentation completely ?
All the indentation hooks are conventionally named `<lang>-indent`, which
allows us to use the `disabled_hooks` variable to disable indentation
globally with the following command: `set global disabled_hooks '.+-indent'`
How to enable syntax highlighting ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== How to enable syntax highlighting ?
The mimetype of the files opened in new buffers is detected using the
`file` command, and syntax highlighting enabled automatically when
possible.
My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ?
The `file` utility has several short comings, such as detecting the
wrong mimetype for a file containing data with different syntax, e.g.
@ -166,16 +145,14 @@ for a given format for instance), but not much can be done about those
ambiguous cases. You might consider writing a custom `$HOME/.magic` file
if needed.
Can I disable syntax highlighting completely ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Can I disable syntax highlighting completely ?
Similarly to the indentation hooks, the name format followed by the
highlighting hooks is `<lang>-highlight`. You can thus disable syntax
highlighting using the following command: `set global disabled_hooks
'.+-highlight'`
Why does a dot `.` in a regex select newline characters ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Why does a dot `.` in a regex select newline characters ?
Data in buffers is a stream of characters, and newlines do not receive special
treatment compared to other characters, with regards to regex matching. In
@ -183,8 +160,7 @@ order to select data in a line without any trailing newline characters, one coul
use the `[^\n]+` pattern, which is arguably a good compromise when
balanced against the ability to select data over several lines.
Can I split the window to display different buffers in them ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Can I split the window to display different buffers in them ?
As a fairly compliant follower of the UNIX philosophy, Kakoune does not
try to implement features that are best handled by separate, dedicated
@ -198,8 +174,7 @@ In order to open buffers in the same window simultaneously using `tmux`
and simply use the `:new` command to spawn new clients as you would
have otherwise in an X11 environment.
Why does `a` extend the current selection, but `i` leaves it untouched ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
== Why does `a` extend the current selection, but `i` leaves it untouched ?
Selections are ranges of characters whose delimiters are an "anchor" and
a "cursor", and inserting characters is always done before the cursor in

View File

@ -1,12 +1,6 @@
kakoune(k)
==========
= Highlighters
NAME
----
highlighters - a
Description
-----------
== Description
Manipulation of the displayed text is done through highlighters, which can
be added or removed with the following commands:
@ -30,8 +24,8 @@ separated path starting with a scope. Scopes are *global*, *buffer*,
completion in a prompt on the *remove-highlighter* command to see the existing highlighters
ids.
General highlighters
--------------------
== General highlighters
*regex* <ex> <capture_id>:<face> ...::
highlight a regex, takes the regex as first parameter, followed by
any number of face parameters. For example:
@ -119,8 +113,8 @@ add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red
*line* <number> <face>::
highlight line *number* with face *face*
Highlighting Groups
-------------------
== Highlighting Groups
The *group* highlighter is a container for other highlighters. You can add a
a subgroup to an existing group, or scope using:
@ -143,8 +137,7 @@ or several (separated with a pipe sign) of *colorize*, *move* or *wrap* (default
add-highlighter window group -passes colorize|move|wrap <name>
--------------------------------------------------------------
Regions highlighters
--------------------
== Regions highlighters
A special highlighter provides a way to segment the buffer into regions,
which are to be highlighted differently.
@ -221,8 +214,7 @@ add-highlighter <path>/<lang>/string ...
add-highlighter <path>/<lang>/comment ...
-----------------------------------------------------------------
Shared Highlighters
-------------------
== Shared Highlighters
Highlighters are often defined for a specific filetype, and it makes then
sense to share the highlighters between all the windows on the same filetypes.

View File

@ -1,12 +1,6 @@
kakoune(k)
==========
= Hooks
NAME
----
hooks - a
Description
-----------
== Description
Commands can be registered to be executed when certain events arise. To
register a hook use the following command:
@ -38,8 +32,8 @@ remove-hooks <scope> <group>
A call to the command above will remove every hooks in *scope* that are part
of the given *group*.
Default hooks
-------------
== Default hooks
*NormalIdle*::
a certain duration has passed since last key was pressed in normal mode
@ -172,8 +166,7 @@ the following expansions:
* `kak_hook_param`: filtering text passed to the currently executing hook
* `kak_hook_param_capture_N`: text captured by the hook filter regex capture N
Disabling Hooks
---------------
== Disabling Hooks
Any normal mode command can be prefixed with `\` which will disable hook
execution for the duration for the command (including the duration of modes

View File

@ -1,12 +1,7 @@
kakoune(k)
==========
= Keys
NAME
----
keys - a
== Key Syntax
Key Syntax
----------
Usual keys are written using their ascii character, including capital
keys. Non printable keys use an alternate name, written between *<*
and *>*, such as *<esc>* or *<del>*. Modified keys are written between
@ -17,8 +12,8 @@ name or ascii character), for example *<c-x>*, *<a-space>*.
In order to bind some keys to arbitrary ones, refer to the 'mapping'
documentation page.
Insert mode
-----------
== Insert mode
*<esc>*::
leave insert mode
@ -73,8 +68,7 @@ Insert mode
*<a-;>*::
escape to normal mode for a single command
Using Counts
------------
== Using Counts
In normal mode, commands can be prefixed with a numeric count, which can control
the command behaviour.
@ -82,8 +76,7 @@ the command behaviour.
For example, *3W* selects 3 consecutive words and *3w* select the third word on
the right of selection end.
Disabling Hooks
---------------
== Disabling Hooks
Any normal mode command can be prefixed with *\* which will disable hook execution
for the duration for the command (including the duration of modes the command could
@ -92,8 +85,8 @@ move to, so *\i* will disable hooks for the whole insert session).
As autoindentation is implemented in terms of hooks, this can be used to disable
it when pasting text.
Movement
--------
== Movement
'word' is a sequence of alphanumeric characters or underscore, and 'WORD'
is a sequence of non whitespace characters
@ -212,8 +205,7 @@ is a sequence of non whitespace characters
*<a-.>*::
repeat last object or *f*/*t* selection command
Changes
-------
== Changes
*i*::
enter insert mode before current selection
@ -364,8 +356,7 @@ Changes
rotate (1, 2, 3) and (3, 4, 6) independently
Goto Commands
-------------
== Goto Commands
*g*, *G*::
When a count is specified, *G* only extends the current selection to the given line,
@ -408,8 +399,7 @@ Goto Commands
*.*:::
go to last buffer modification position
View commands
-------------
== View commands
*v*, *V*::
*V* enters lock view mode (which will be left when the <esc> is hit),
@ -441,8 +431,8 @@ View commands
scroll the window count columns right
Marks
-----
== Marks
Marks use the *^* register by default.
*Z*::
@ -477,8 +467,8 @@ Marks use the *^* register by default.
*-*:::
select the shortest selection
Macros
------
== Macros
Macros use the *@* register by default
*<esc>*::
@ -490,8 +480,8 @@ Macros use the *@* register by default
*q*::
play a recorded macro
Searching
---------
== Searching
Searches use the */* register by default
***::
@ -502,8 +492,8 @@ Searches use the */* register by default
set the search pattern to the current selection (verbatim, no smart
detection)
Jump list
---------
== Jump list
*<c-i>*::
Jump forward
@ -514,8 +504,7 @@ Jump list
*<c-s>*::
save current selections
Multiple selections
-------------------
== Multiple selections
*s*::
create a selection
@ -548,8 +537,7 @@ Multiple selections
pipe each selection to the given shell command and keep the ones
for which the shell returned 0
Object Selection
----------------
== Object Selection
*<a-a>*::
selects the whole object
@ -620,8 +608,7 @@ object you want
*c*::
select user defined object, will prompt for open and close text
Prompt Commands
---------------
== Prompt Commands
*<ret>*::
validate prompt

View File

@ -1,12 +1,7 @@
kakoune(k)
==========
= Mapping
NAME
----
mapping - a
== Description
Description
-----------
Creating and removing shortcuts boils down to the following commands,
respectively:
@ -51,8 +46,7 @@ set to the same sequence of keys passed using the *expected* argument.
For more information about the values of the *scope* parameter, refer to
the 'scopes' documentation page.
Mappable keys
-------------
== Mappable keys
For *key* and *keys* in the *map* command, the following key names can
be used:

View File

@ -1,12 +1,6 @@
kakoune(k)
==========
= Options
NAME
----
options - a
Options
-------
== Description
Kakoune can store named and typed values that can be used both to customize
the core editor behaviour, and to store data used by extension scripts.
@ -28,8 +22,7 @@ declare-option [-hidden] <type> <name> [<value>]
If `-hidden` is specified, the option will not be displayed in completion
suggestions.
Types
-----
== Types
All options have a type, which defines how they are translated to/from text
and their set of valid values.
@ -76,8 +69,7 @@ are exclusively available to built-in options.
a set of flags, taking a combination of the given values joined by a
'|' character
Builtin options
---------------
== Builtin options
*tabstop* 'int'::
*default* 8 +

View File

@ -1,20 +1,13 @@
kakoune(k)
==========
= Regex
NAME
----
regex - a
Regex Syntax
------------
== Regex Syntax
Kakoune regex syntax is based on the ECMAScript syntax, as defined by the
ECMA-262 standard (see <<Compatibility>>).
Kakoune's regex always run on Unicode codepoint sequences, not on bytes.
Literals
--------
== Literals
Every character except the syntax characters `\^$.*+?[]{}|().` match
themselves. Syntax characters can be escaped with a backspace so `\$`
@ -32,8 +25,7 @@ Some literals are available as escape sequences:
* `\xXX` matches the character whose codepoint is XX (in hexadecimal).
* `\uXXXX` matches the character whose codepoint is XXXX (in hexadecimal).
Character classes
-----------------
== Character classes
The `[` character introduces a character class, matching one character
from a set of characters.
@ -76,13 +68,11 @@ non-digit character.
Character class escapes can be used outside of a character class, `\d`
is equivalent to `[\d]`.
Any character
-------------
== Any character
`.` matches any character, including new lines.
Groups
------
== Groups
Regex atoms can be grouped using `(` and `)` or `(?:` and `)`. If `(` is
used, the group will be a capturing group, which means the positions from
@ -95,8 +85,7 @@ for the whole sequence that matched.
`(?:` introduces a non capturing group, which will not record the
matching positions.
Alternations
------------
== Alternations
`|` introduces an alternation, which will either match its left-hand side,
or its right-hand side (preferring the left-hand side)
@ -104,8 +93,7 @@ or its right-hand side (preferring the left-hand side)
For example, `foo|bar` matches either `foo` or `bar`, `foo(bar|baz|qux)`
matches `foo` followed by either `bar`, `baz` or `qux`.
Quantifier
----------
== Quantifier
Literals, Character classes, Any characters and groups can be followed
by a quantifier, which specifies the number of times they can match.
@ -123,8 +111,7 @@ match more characters if possible. Suffixing a quantifier with `?` will
make it non-greedy, meaning it will prefer to match as few characters
as possible.
Zero width assertions
---------------------
== Zero width assertions
Assertions do not consume any character, but will prevent the regex
from matching if they are not fulfilled.
@ -163,8 +150,7 @@ For example, `(?<!bar)(?=foo).` will match any character which is not
preceded by `bar` and where `foo` matches from the current position
(which means the character has to be an `f`).
Modifiers
---------
== Modifiers
Some modifiers can control the matching behavior of the atoms following
them:
@ -172,8 +158,7 @@ them:
* `(?i)` enables case-insensitive matching
* `(?I)` disables case-insensitive matching
Quoting
-------
== Quoting
`\Q` will start a quoted sequence, where every character is treated as
a literal. That quoted sequence will continue until either the end of
@ -182,8 +167,7 @@ the regex, or the appearance of `\E`.
For example `.\Q.^$\E$` will match any character followed by the literal
string `.^$` followed by an end of line.
Compatibility
-------------
== Compatibility
The syntax tries to follow the ECMAScript regex syntax as defined by
https://www.ecma-international.org/ecma-262/8.0/ some divergences

View File

@ -1,18 +1,13 @@
kakoune(k)
==========
= Registers
NAME
----
registers - a
== Description
Description
-----------
Registers are named lists of text -instead of simply text- in order to interact
well with multiselection. They are used for various purposes, like storing
the last yanked text, or the captured groups associated with the selections.
Interacting
-----------
== Interacting
*<c-r><c>*::
when in insert mode or in a prompt, insert the value stored in the
*c* register (single character)
@ -20,14 +15,13 @@ Interacting
*"<c>*::
in normal mode, select the *<c>* register (single character)
Alternate names
---------------
== Alternate names
Non alphanumeric registers have an alternative name that can be used
in contexts where only alphanumeric identifiers are possible.
Default registers
-----------------
== Default registers
Most commands using a register default to a specific one if not specified:
*"* (dquote)::
@ -48,8 +42,8 @@ Most commands using a register default to a specific one if not specified:
default shell command register, used by command that spawn a subshell such as
*|*, *<a-|>*, *!* or *<a-!>*
Special registers
-----------------
== Special registers
Some registers are not general purposes, they cannot be written to, but they
contain some special data
@ -68,8 +62,8 @@ contain some special data
*:* (colon)::
last entered command
Integer registers
-----------------
== Integer registers
Registers *1* to *9* hold the grouped sub-matches of the regular
expression used to make the last selection. Example: applying the
following regular expression to the date of the day would put the day of

View File

@ -1,19 +1,12 @@
kakoune(k)
==========
= Scopes
NAME
----
scopes - a
Description
-----------
== Description
Scopes are groups in which a particular Kakoune object (a variable,
hook, alias etc) can have different values, depending on the group the
value was declared in.
Names and hierarchy
-------------------
== Names and hierarchy
Scopes are named as follows:
@ -34,8 +27,7 @@ The above priority line implies that objects can have individual values that
will be resolved first in the *window* scope (highest priority), then in
the *buffer* scope, and finally in the *global* scope (lowest priority).
Uses
----
== Uses
The scope paradigm is very useful as it allows the user to customize the
behavior of the editor without modifying the configuration globally, as
@ -56,8 +48,7 @@ Examples:
customized in the *buffer* scope with 'set', c.f. the 'options'
documentation page)
Execution context
-----------------
== Execution context
Some commands work in a specific context that might exclude one or
several scopes altogether, consequently ignoring some values of a given

View File

@ -1,54 +1,64 @@
decl -docstring "name of the client in which documentation is to be displayed" \
str docsclient
def -hidden -params 1..2 doc-open %{
%sh{
manout=$(mktemp "${TMPDIR:-/tmp}"/kak-man-XXXXXX)
declare-option -hidden range-specs doc_render_ranges
# This option is handled by the `man-db` implementation
export MANWIDTH=${kak_window_width}
if man "$1" > "${manout}" 2>/dev/null; then
readonly manout_noescape=$(mktemp "${TMPDIR:-/tmp}"/kak-man-XXXXXX)
sed -e $(printf 's/.\x8//g') -e 's,\x1B\[[0-9;]*[a-zA-Z],,g' "${manout}" > "${manout_noescape}"
mv -f "${manout_noescape}" "${manout}"
printf %s\\n "
edit! -scratch '*doc*'
exec |cat<space>${manout}<ret>gg
nop %sh{rm ${manout}}
set buffer filetype man
remove-hooks window man-hooks
"
if [ $# -gt 1 ]; then
needle=$(printf %s\\n "$2" | sed 's,<,<lt>,g')
printf %s\\n "try %{ exec '%<a-s><a-k>(?i)^\h+[^\n]*?\Q${needle}\E<ret>\z' } catch %{ exec <space>gg }"
fi
else
printf %s\\n "echo -markup %{{Error}doc '$@' failed: see *debug* buffer for details}"
rm ${manout}
fi
}
define-command -hidden -params 4 doc-render-regex %{
eval -draft %{ try %{
exec \%s %arg{1} <ret>
exec -draft s %arg{2} <ret> d
exec "%arg{3}"
%sh{
ranges=$(echo "$kak_selections_desc" | sed -e "s/:/|$4:/g; s/\$/|$4/")
echo "update-option buffer doc_render_ranges"
echo "set -add buffer doc_render_ranges '$ranges'"
}
} }
}
def -params 1..2 \
define-command -params 1 -hidden doc-render %{
edit! -scratch *doc*
exec "!cat %arg{1}<ret>gg"
# Join paragraphs together
try %{ exec -draft \%S \n{2,}|(?<=\+)\n|^[^\n]+::\n <ret> <a-K>^-{2,}(\n|\z)<ret> S\n\z<ret> <a-k>\n<ret> <a-j> }
# Remove some line end markers
try %{ exec -draft \%s \h*(\+|:{2,})$ <ret> d }
# Setup the doc_render_ranges option
set buffer doc_render_ranges %val{timestamp}
doc-render-regex \B(?<!\\)\*[^\n]+?(?<!\\)\*\B \A|.\z 'H' default+b
doc-render-regex \B(?<!\\)`[^\n]+?(?<!\\)`\B \A|.\z 'H' mono
doc-render-regex ^=\h+[^\n]+ ^=\h+ '~' title
doc-render-regex ^={2,}\h+[^\n]+ ^={2,}\h+ '' header
doc-render-regex ^-{2,}\n.*?^-{2,}\n ^-{2,}\n '' block
doc-render-regex <lt><lt>.*?<gt><gt> <lt><lt>.*,|<gt><gt> 'H' link
# Remove escaping of * and `
try %{ exec -draft \%s \\((?=\*)|(?=`)) <ret> d }
set-option buffer readonly true
add-highlighter buffer ranges doc_render_ranges
add-highlighter buffer wrap -word -indent
}
def -params 1 \
-shell-candidates %{
find "${kak_runtime}/doc/" -type f -name "*.gz" | while read l; do
find "${kak_runtime}/doc/" -type f -name "*.asciidoc" | while read l; do
basename "${l%.*}"
done
} \
doc -docstring %{doc <topic> [<keyword>]: open a buffer containing documentation about a given topic
An optional keyword argument can be passed to the function, which will be automatically selected in the documentation} %{
%sh{
readonly PATH_DOC="${kak_runtime}/doc/${1}.gz"
readonly page="${kak_runtime}/doc/${1}.asciidoc"
shift
if [ -f "${PATH_DOC}" ]; then
printf %s\\n "eval -try-client %opt{docsclient} doc-open ${PATH_DOC} $@"
if [ -f "${page}" ]; then
printf %s\\n "eval -try-client %opt{docsclient} doc-render ${page}"
else
printf %s\\n "echo -markup '{Error}No such doc file: ${PATH_DOC}'"
printf %s\\n "echo -markup '{Error}No such doc file: ${page}'"
fi
}
}

View File

@ -16,8 +16,6 @@ endif
sources := $(sort $(wildcard *.cc))
objects := $(addprefix ., $(sources:.cc=$(suffix).o))
deps := $(addprefix ., $(sources:.cc=$(suffix).d))
docs := $(wildcard ../doc/pages/*.asciidoc)
mandocs := $(docs:.asciidoc=.gz)
PREFIX ?= /usr/local
DESTDIR ?= # root dir
@ -77,16 +75,6 @@ kak$(suffix) : $(objects)
a2x --no-xmllint -f manpage $<
gzip -n -9 -f $(basename $<)
# Generate the editor's documentation pages
# Since `a2x` won't generate man pages if some sections are missing (which we don't need),
# we generate the pages, patch them and then compress them
../doc/pages/%.gz: ../doc/pages/%.asciidoc
a2x --no-xmllint -f manpage $<
sed -i -r -e "s,^\.TH .+,.TH kakoune k \"\" \"\" \"$(basename $(notdir $<))\"," \
-e "/^\.SH \"NAME\"/{N;d;}" $(@:.gz=.k)
gzip -n -9 -f $(@:.gz=.k)
mv -f $(@:.gz=.k.gz) $@
check: test
test:
cd ../test && ./run
@ -95,7 +83,6 @@ TAGS: tags
tags:
ctags -R
man: ../doc/kak.1.gz
doc: $(mandocs)
clean:
rm -f .*.o .*.d
@ -114,10 +101,10 @@ installdirs:
$(docdir) \
$(mandir)
install: kak man doc installdirs
install: kak man installdirs
install -m 0755 kak $(bindir)
install -m 0644 ../share/kak/kakrc $(sharedir)
install -m 0644 ../doc/pages/*.gz $(sharedir)/doc
install -m 0644 ../doc/pages/*.asciidoc $(sharedir)/doc
install -m 0644 ../rc/base/* $(sharedir)/rc/base
install -m 0644 ../rc/core/* $(sharedir)/rc/core
install -m 0644 ../rc/extra/* $(sharedir)/rc/extra
@ -136,4 +123,4 @@ uninstall:
$(mandir)/kak.1.gz
.PHONY: check TAGS clean distclean installdirs install install-strip uninstall
.PHONY: tags test man doc kak
.PHONY: tags test man kak