Skip to content

Commit b59714b

Browse files
mawwwmawww
committed
Merge remote-tracking branch 'lenormf/manpage'
2 parents dc3c7d5 + 985b7a1 commit b59714b

12 files changed

+1632
-1
lines changed

‎doc/kakoune.1.txt

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
kakoune(1)
2+
==========
3+
4+
NAME
5+
----
6+
kakoune - a vim inspired, selection oriented code editor
7+
8+
SYNOPSIS
9+
--------
10+
*kak* [-q] [-u] [-n] [-l] [-e command] [-f command] [-p session_id] [-c session_id|[[-d] -s session_id] file ...
11+
12+
DESCRIPTION
13+
-----------
14+
Kakoune is a code editor heavily inspired by Vim, as such most of its commands are similar to Vi's ones, and it
15+
shares Vi's "keystrokes as a text editing language" model.
16+
17+
Kakoune can operate in two modes, normal and insertion. In insertion mode, keys are directly inserted into the
18+
current buffer. In normal mode, keys are used to manipulate the current selection and to enter insertion mode.
19+
20+
Kakoune has a strong focus on interactivity, most commands provide immediate and incremental results, while still
21+
being competitive (as in keystroke count) with Vim.
22+
23+
Kakoune works on selections, which are oriented, inclusive range of characters, selections have an anchor and
24+
a cursor character. Most commands move both of them, except when extending selection where the anchor character
25+
stays fixed and the cursor one moves around.
26+
27+
OPTIONS
28+
-------
29+
-q::
30+
in filter mode, be quiet about errors applying keys
31+
32+
-u::
33+
use a dummy user interface, for testing purposes
34+
35+
-n::
36+
do not source kakrc files on startup
37+
38+
-l::
39+
list existing sessions
40+
41+
-d::
42+
run as a headless session (requires -s)
43+
44+
-e <command>::
45+
execute argument on initialisation
46+
47+
-f <command>::
48+
act as a filter, executing given keys on given files
49+
50+
-p <session_id>::
51+
just send stdin as commands to the given session
52+
53+
-c <session_id>::
54+
connect to given session
55+
56+
-s <session_id>::
57+
set session name
58+
59+
file::
60+
one or more files to edit
61+
62+
At startup, if -n is not specified, Kakoune will try to source the file '../share/kak/kakrc' relative to the
63+
kak binary. This kak file will then try to recursively source any files in *$XDG_CONFIG_HOME*'/kak/autoload'
64+
(with *$XDG_CONFIG_HOME* defaulting to *$HOME*'/.config', and falling back to '../share/kak/autoload' if that
65+
autoload directory does not exist), and finally *$XDG_CONFIG_HOME*'/kak/kakrc'.
66+
67+
That leads to the following behaviour: by default, with no user autoload directory, the system wide autoload
68+
directory is used, once the user wants control on autoloading, they can create an autoload directory and eventually
69+
symlink individual scripts, or the whole system wide autoload directory. They can as well add any new scripts not
70+
provided with Kakoune.
71+
72+
EXAMPLES
73+
--------
74+
kak /path/to/file::
75+
Edit a file
76+
77+
kak ./file1.txt /path/to/file2.c::
78+
Edit multiple files (multiple buffers will be created)
79+
80+
kak -f "ggO// kak: tabstop=8<esc>" *.c::
81+
Insert a modeline that sets the tabstop variable at the beginning of several source code files
82+
83+
kak -e "man dup2"::
84+
Use Kakoune as a man pager
85+
86+
FILES
87+
-----
88+
If not started with the -n switch, Kakoune will source the '../share/kak/kakrc' file relative to the kak binary,
89+
which will source additional files:
90+
91+
* if the *$XDG_CONFIG_HOME*'/kak/autoload' directory exists, load every '*.kak' files in it, and load
92+
recursively any subdirectory
93+
* if it does not exists, fall back to the system wide autoload directory in '../share/kak/autoload'
94+
95+
After that, if it exists, source the *$XDG_CONFIG_HOME*'/kak/kakrc' file which should be used for user
96+
configuration. In order to continue autoloading site-wide files with a local autoload directory, just add a symbolic
97+
link to '../share/kak/autoload' into your local autoload directory.

‎doc/manpages/commands

+154
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
KAKOUNE(1)
2+
==========
3+
4+
NAME
5+
----
6+
commands - a
7+
8+
Primitives
9+
----------
10+
*e[dit]* <filename> [<line> [<column>]]::
11+
open buffer on file, go to given line and column. If file is already opened, just switch to this file. Use edit! to force reloading
12+
13+
*w[rite]* [<filename>]::
14+
write buffer to <filename> or use it's name if filename is not given
15+
16+
*w[rite]a[ll]*::
17+
write all buffers that are associated to a file
18+
19+
*q[uit]*::
20+
exit Kakoune, use quit! to force quitting even if there is some unsaved buffers remaining
21+
22+
*wq*::
23+
write current buffer and quit
24+
25+
*b[uffer]* <name>::
26+
switch to buffer <name>
27+
28+
*d[el]b[uf]* [<name>]::
29+
delete the buffer <name>, use d[el]b[uf]! to force deleting a modified buffer
30+
31+
*source* <filename>::
32+
execute commands in <filename>
33+
34+
*runtime* <filename>::
35+
execute commands in <filename>, <filename> is relative to kak executable path
36+
37+
*colorscheme* <name>::
38+
load named colorscheme
39+
40+
*nameclient* <name>::
41+
set current client name
42+
43+
*namebuf* <name>::
44+
set current buffer name
45+
46+
*echo* <text>::
47+
show <text> in status line
48+
49+
*nop*::
50+
does nothing, but arguments will be evaluated (e.g. shell expansion)
51+
52+
*set* <scope> <name> <value>::
53+
change the value of an option (c.f. the 'options' documentation page)
54+
55+
*alias* <scope> <name> <command>::
56+
define a new alias, within the context of a scope
57+
58+
*unalias* <scope> <name> [<command>]::
59+
remove an alias if its current value is the same as the one passed as an optional parameter, remove it unconditionally otherwise
60+
61+
*decl* [-hidden] <type> <name> [<value>]::
62+
declare a new option, the -hidden hides the option in completion suggestions (c.f. the 'options' documentation page)
63+
64+
*face* <name> <facespec>::
65+
define a face (c.f. the 'faces' documentation page)
66+
67+
*exec* [<flags>] <key> ...::
68+
execute a series of keys, as if they were hit (c.f. the 'execeval' documentation page)
69+
70+
*eval* [<flags>] <command> ...::
71+
execute commands, as if they were entered in the command prompt (c.f. the 'execeval' documentation page)
72+
73+
*def* [<flags>] <name> <command>::
74+
define a new command (c.f. the 'Declaring new commands' section below)
75+
76+
*map* <scope> <mode> <key> <keys>::
77+
bind a combination of keys to another one (c.f. the 'commands' documentation page)
78+
79+
*hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
80+
execute a command whenever an event is triggered (c.f. the 'hooks' documentation page)
81+
82+
*rmhooks* <scope> <group>::
83+
remove every hooks in *scope* that are part of the given *group* (c.f. the 'hooks' documentation page)
84+
85+
*addhl* [<flags>] <highlighter_name> <highlighter_parameters> ...::
86+
add a highlighter to the current window (c.f. the 'highlighters' documentation page)
87+
88+
*rmhl* <highlighter_id>::
89+
remove the highlighter whose id is *highlighter_id* (c.f. the 'highlighters' documentation page)
90+
91+
Helpers
92+
-------
93+
Kakoune provides some helper commands that can be used to define composite commands:
94+
95+
*prompt* <prompt> <register> <command>::
96+
prompt the user for a string, when the user validates, store the result in given *register* and run *commmand*. the *-init <str>* switch allows setting initial content
97+
98+
*onkey* <register> <command>::
99+
wait for next key from user, writes it into given <register> and execute commands
100+
101+
*menu* <label1> <commands1> <label2> <commands2> ...::
102+
display a menu using labels, the selected label’s commands are executed. menu can take an *-auto-single* argument, to automatically run commands when only one choice is provided, and a *-select-cmds* argument, in which case menu takes three argument per item, the last one being a command to execute when the item is selected (but not validated)
103+
104+
*info* <text>::
105+
display text in an information box, at can take an *-anchor* option, which accepts left, right and cursor as value, in order to specify where the info box should be anchored relative to the main selection
106+
107+
*try* <commands> catch <on_error_commands>::
108+
prevent an error in *commands* from aborting the whole commands execution, execute *on_error_commands* instead. If nothing is to be done on error, the catch part can be ommitted
109+
110+
*reg* <name> <content>::
111+
set register *name* to *content*
112+
113+
Note that those commands are also available in the interactive mode, but are not really useful in that context.
114+
115+
Multiple commands
116+
-----------------
117+
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
118+
119+
Declaring new commands
120+
----------------------
121+
New commands can be defined using the *def* command:
122+
123+
*def* [flags] <command_name> <commands>::
124+
*commands* is a string containing the commands to execute, and *flags* can be any combination of the following parameters:
125+
126+
*-params* <num>::
127+
the command accepts a *num* parameter, which can be either a number, or of the form <min>..<max>, with both <min> and <max> omittable
128+
129+
*-file-completion*::
130+
try file completion on any parameter passed to this command
131+
132+
*-client-completion*::
133+
try client name completion on any parameter passed to this command
134+
135+
*-buffer-completion*::
136+
try buffer name completion on any parameter passed to this command
137+
138+
*-shell-completion*::
139+
following string is a shell command which takes parameters as positional params and output one completion candidate per line
140+
141+
*-allow-override*::
142+
allow the new command to replace an exisiting one with the same name
143+
144+
*-hidden*::
145+
do not show the command in command name completions
146+
147+
*-docstring*::
148+
define the documentation string for the command
149+
150+
Using shell expansion allows to define complex commands or to access Kakoune state:
151+
152+
--------------------------------------------------------
153+
def " print_selection %{ echo %sh{ ${kak_selection} } }"
154+
--------------------------------------------------------

‎doc/manpages/execeval

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
KAKOUNE(1)
2+
==========
3+
4+
NAME
5+
----
6+
execeval - a
7+
8+
Description
9+
-----------
10+
The *exec* and *eval* commands can be used to run Kakoune commands, and should be used as follows:
11+
12+
----------------------------
13+
exec [<flags>] <key> ...
14+
eval [<flags>] <command> ...
15+
----------------------------
16+
17+
*exec* runs keys as if they were pressed, whereas *eval* executes its given paremeters as if they were entered in
18+
the command prompt. By default, their execution happens within the context of the current client, and stops when
19+
the last key/command is reached, or an error is raised.
20+
21+
Optional flags
22+
--------------
23+
*-client* <name>::
24+
execute in the context of the client named *name*
25+
26+
*-try-client* <name>::
27+
execute in the context of the client named *name* if such client exists, or else in the current context
28+
29+
*-draft*::
30+
execute in a copy of the context of the selected client modifications to the selections or input state
31+
will not affect the client. This permits to make some modification to the buffer without modifying the
32+
user’s selection
33+
34+
*-itersel* (requires -draft)::
35+
execute once per selection, in a context with only the considered selection. This permits to avoid cases
36+
where the selections may get merged
37+
38+
*-buffer* <names>::
39+
execute in the context of each buffers in the comma separated list *names*, as a name can be used to
40+
iterate on all buffers
41+
42+
*-no-hooks*::
43+
disable hook execution while executing the keys/commands
44+
45+
*-with-maps*::
46+
use user key mapping in instead of built in keys (*exec* only)
47+
48+
*-save-regs* <regs>::
49+
regs is a string of registers to be restored after execution

0 commit comments

Comments
 (0)