mirror of
https://github.com/mawww/kakoune.git
synced 2024-12-23 19:46:33 +03:00
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
parent
90865b65cd
commit
4fabba3d12
@ -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>::
|
||||
|
||||
@ -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*
|
||||
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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 +
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
}
|
||||
}
|
||||
|
||||
19
src/Makefile
19
src/Makefile
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user