Skip to content

Commit 77beeaf

Browse files
lenormflenormf
committed
Rewrote the documentation pages in asciidoc format
1 parent 6951f3f commit 77beeaf

File tree

9 files changed

+1372
-1508
lines changed

9 files changed

+1372
-1508
lines changed

‎doc/manpages/commands

+147-178
Original file line numberDiff line numberDiff line change
@@ -1,185 +1,154 @@
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
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+
-------
9393
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
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*
128112

129113
Note that those commands are also available in the interactive mode, but are not really useful in that context.
130114

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
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
179149

180150
Using shell expansion allows to define complex commands or to access Kakoune state:
181151

182-
.RS 3
183-
.TP
184-
.BR def " print_selection %{ echo %sh{ ${kak_selection} } }"
185-
.RE
152+
--------------------------------------------------------
153+
def " print_selection %{ echo %sh{ ${kak_selection} } }"
154+
--------------------------------------------------------

0 commit comments

Comments
 (0)