Skip to content

Commit 33008f9

Browse files
lenormflenormf
committed
Add a doc command, as well as several themed documentation pages
1 parent 043f742 commit 33008f9

File tree

10 files changed

+1632
-0
lines changed

10 files changed

+1632
-0
lines changed

‎doc/manpages/commands

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

‎doc/manpages/execeval

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

‎doc/manpages/expansions

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
.TH KAKOUNE 1 "" "" "EXPANSIONS"
2+
3+
.SS Strings
4+
.TP
5+
.BR 'strings'
6+
uninterpreted strings, use a backslash (\\') to escape the separator
7+
.TP
8+
.BR "strings"
9+
expanded strings, % strings (c.f. next section) contained are expended, use a backslash (\\%) to escape the separator
10+
.TP
11+
.BR %{strings}
12+
these strings are very useful when entering commands the
13+
.IR { " and " }
14+
delimiters are configurable, you can use any non alphanumeric character
15+
e.g. %[string], %<string>, %(string), %~string~, %!string!
16+
if the character following '%' is one of '{[(<', then the closing one is the matching '}])>' and the delimiters are not escapable but are nestable
17+
e.g.
18+
.IR %{\ roger\ {};\ } " is a valid string
19+
20+
.SS Typed expansions
21+
.TP
22+
.BR sh
23+
shell expansion, similar to posix shell $(…) construct (c.f. next section)
24+
.TP
25+
.BR reg
26+
register expansion, will be replaced by the content of the given register
27+
.TP
28+
.BR opt
29+
option expansion, will be replaced with the value of the given option
30+
.TP
31+
.BR val
32+
value expansion, gives access to the environment variable available to the Shell expansion. The kak_ prefix is not used there
33+
.TP
34+
.BR arg
35+
argument expansion, gives access to the arguments of the current command, the content can be a number, or @ for all arguments
36+
37+
.SS Shell expansions
38+
The
39+
.IR %sh{…}
40+
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:
41+
42+
.TP
43+
.BR kak_selection
44+
content of the main selection
45+
.TP
46+
.BR kak_selections
47+
content of the selection separated by colons, colons in the selection contents are escapted with a backslash.
48+
.TP
49+
.BR kak_selection_desc
50+
range of the main selection, represented as anchor,cursor; anchor and cursor are in this format: line.column
51+
.TP
52+
.BR kak_selections_desc
53+
range of the selecations separated by colons
54+
.TP
55+
.BR kak_bufname
56+
name of the current buffer
57+
.TP
58+
.BR kak_buffile
59+
full path of the file or same as kak_bufname when there’s no associated file
60+
.TP
61+
.BR kak_buflist
62+
the current buffer list, each buffer seperated by a colon
63+
.TP
64+
.BR kak_timestamp
65+
timestamp of the current buffer, the timestamp is an integer value which is incremented each time the buffer is modified.
66+
.TP
67+
.BR kak_runtime
68+
directory containing the kak binary
69+
.TP
70+
.BR kak_opt_<name>
71+
value of option
72+
.IR <name>
73+
.TP
74+
.BR kak_reg_<r>
75+
value of register
76+
.IR <r>
77+
.TP
78+
.BR kak_socket
79+
filename of session socket (/tmp/kak-<session>)
80+
.TP
81+
.BR kak_session
82+
name of the current session
83+
.TP
84+
.BR kak_client
85+
name of current client
86+
.TP
87+
.BR kak_cursor_line
88+
line of the end of the main selection
89+
.TP
90+
.BR kak_cursor_column
91+
column of the end of the main selection (in byte)
92+
.TP
93+
.BR kak_cursor_char_column
94+
column of the end of the main selection (in character)
95+
.TP
96+
.BR kak_window_width
97+
width of the current kakoune window
98+
.TP
99+
.BR kak_window_height
100+
height of the current kakoune window
101+
.TP
102+
.BR kak_hook_param
103+
filtering text passed to the currently executing hook
104+
.TP
105+
.BR kak_client_env_<name>
106+
value of the
107+
.IR <name>
108+
variable in the client environment (e.g. $kak_client_env_SHELL is the SHELL variable)
109+
110+
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
111+
112+
.SS Markup strings
113+
In certain contexts, Kakoune can take a markup string, which is a string containing formatting informations.
114+
In these strings, the {facename} syntax will enable the face facename until another face gets activated, or the end of the string is reached.
115+
Literal '{' characters shall be written '\\{', and a literal backslash ('\\') that preceeds a '{' character shall be escaped as well ('\\\\')

0 commit comments

Comments
 (0)