Merge remote-tracking branch 'lenormf/manpage'

README.asciidoc

@@ -585,31 +585,41 @@ saved in the command history.
 Basic Commands
 ~~~~~~~~~~~~~~
 
- * `e[dit] <filename> [<line> [<column>]]`: open buffer on file, go to given
+Some commands take an esclamation mark (`!`), which can be used to force
+the execution of the command (i.e. to quit a modified buffer, the
+command `q!` has to be used).
+
+ * `cd <directory>`: change the current directory to the one passed
+ * `e[dit][!] <filename> [<line> [<column>]]`: 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.
  * `w[rite] [<filename>]`: write buffer to <filename> or use it's name if
-      filename is not given.
+     filename is not given.
  * `w[rite]a[ll]`: write all buffers that are associated to a file.
- * `q[uit]`: exit Kakoune, use quit! to force quitting even if there is some
+ * `q[uit][!]`: exit Kakoune, use quit! to force quitting even if there is some
-      unsaved buffers remaining.
+     unsaved buffers remaining.
- * `wq`: write current buffer and quit
+ * `kill`: terminate the current session, all the clients as well as the server
+ * `w[a]q[!]`: write the current buffer (or all buffers when `waq` is used) and quit
  * `b[uffer] <name>`: switch to buffer <name>
- * `d[el]b[uf] [<name>]`: delete the buffer <name>, use d[el]b[uf]! to force
+ * `b[uffer]n[ext]`: switch to the next buffer
-      deleting a modified buffer.
+ * `b[uffer]p[rev]`: switch to the previous buffer
+ * `d[el]b[uf][!] [<name>]`: delete the buffer <name>
  * `source <filename>`: execute commands in <filename>
  * `runtime <filename>`: execute commands in <filename>, <filename>
-      is relative to kak executable path.
+     is relative to kak executable path.
  * `colorscheme <name>`: load named colorscheme.
  * `nameclient <name>`: set current client name
  * `namebuf <name>`: set current buffer name
- * `echo <text>`: show <text> in status line
+ * `echo [options] <text>`: show <text> in status line, with the following options:
+   ** `-color` <face>: print the given text with <face>, most commonly `Error` or `Information`
+   ** `-markup`: expand the markup strings in <text>
+   ** `-debug`: print the given text to the `\*debug*` buffer
  * `nop`: does nothing, but as with every other commands, arguments may be
-      evaluated. So nop can be used for example to execute a shell command
+     evaluated. So nop can be used for example to execute a shell command
-      while being sure that it's output will not be interpreted by kak.
+     while being sure that it's output will not be interpreted by kak.
-      `:%sh{ echo echo tchou }` will echo tchou in Kakoune, whereas
+     `:%sh{ echo echo tchou }` will echo tchou in Kakoune, whereas
-      `:nop %sh{ echo echo tchou }` will not, but both will execute the
+     `:nop %sh{ echo echo tchou }` will not, but both will execute the
-      shell command.
+     shell command.
 
 Multiple commands
 ~~~~~~~~~~~~~~~~~
@@ -1375,24 +1385,28 @@ Kakoune state:
 
 Some helper commands can be used to define composite commands:
 
- * `:prompt <prompt> <register> <command>`: Prompt the user for a string, when
+ * `prompt <prompt> <register> <command>`: 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.
- * `:onkey <register> <command>`: Wait for next key from user, writes it into given
+ * `onkey <register> <command>`: Wait for next key from user, writes it into given
      <register> and execute commands.
- * `:menu <label1> <commands1> <label2> <commands2>...`: display a menu using
+ * `menu <label1> <commands1> <label2> <commands2>...`: display a menu using
      labels, the selected label's commands are executed.
      `menu` can take a -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).
- * `:info <text>`: display text in an information box, at can take a -anchor
+ * `info <text>`: display text in an information box, at can take a -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.
- * `:try <commands> catch <on_error_commands>`: prevent an error in <commands>
+ * `try <commands> catch <on_error_commands>`: 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.
- * `:reg <name> <content>`: set register <name> to <content>
+ * `reg <name> <content>`: set register <name> to <content>
+ * `select <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...`:
+     replace the current selections with the one described in the argument
+ * `debug {info,buffers,options,memory,shared-strings}`: print some debug
+     information in the `*debug*` buffer
 
 Note that these commands are available in interactive command mode, but are
 not that useful in this context.

doc/manpages/commands.asciidoc

@@ -7,7 +7,15 @@ commands - a
 
 Primitives
 ----------
-*e[dit]* <filename> [<line> [<column>]]::
+
+Some commands take an esclamation mark (*!*), which can be used to force
+the execution of the command (i.e. to quit a modified buffer, the
+command *q!* has to be used).
+
+*cd* <directory>::
+	change the current directory to the one passed
+
+*e[dit][!]* <filename> [<line> [<column>]]::
 	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
 
@@ -17,19 +25,27 @@ Primitives
 *w[rite]a[ll]*::
 	write all buffers that are associated to a file
 
-*q[uit]*::
+*q[uit][!]*::
 	exit Kakoune, use quit! to force quitting even if there is some
 	unsaved buffers remaining
 
-*wq*::
+*kill*::
-	write current buffer and quit
+	terminate the current session, all the clients as well as the server
+
+*w[a]q[!]*::
+	write the current buffer (or all buffers when *waq* is used) and quit
 
 *b[uffer]* <name>::
 	switch to buffer <name>
 
-*d[el]b[uf]* [<name>]::
+*b[uffer]n[ext]*::
-	delete the buffer <name>, use d[el]b[uf]! to force deleting a
+	switch to the next buffer
-	modified buffer
+
+*b[uffer]p[rev]*::
+	switch to the previous buffer
+
+*d[el]b[uf][!]* [<name>]::
+	delete the buffer <name>
 
 *source* <filename>::
 	execute commands in <filename>
@@ -47,8 +63,17 @@ Primitives
 *namebuf* <name>::
 	set current buffer name
 
-*echo* <text>::
+*echo* [options] <text>::
-	show <text> in status line
+	show *text* in status line, with the following *options*:
+
+	*-color* <face>:::
+		print the given text with *face*, most commonly *Error* or *Information*
+
+	*-markup*:::
+		expand the markup strings in *text* (c.f. the 'expansions' documentation page)
+
+	*-debug*:::
+		print the given text to the *\*debug** buffer
 
 *nop*::
 	does nothing, but arguments will be evaluated (e.g. shell expansion)
@@ -56,6 +81,9 @@ Primitives
 *set* <scope> <name> <value>::
 	change the value of an option (c.f. the 'options' documentation page)
 
+*unset* <scope> <name>::
+	unset the value of an option (c.f. the 'options' documentation page)
+
 *alias* <scope> <name> <command>::
 	define a new alias, within the context of a scope
 
@@ -123,10 +151,17 @@ commands:
 	last one being a command to execute when the item is selected (but
 	not validated)
 
-*info* <text>::
+*info* [options] <text>::
-	display text in an information box, at can take an *-anchor* option,
+	display text in an information box with the following *options*:
-	which accepts left, right and cursor as value, in order to specify
+
-	where the info box should be anchored relative to the main selection
+	*-anchor* <line>.<column>:::
+		print the text at the given coordinates
+
+	*-placement* {above,below}:::
+		set the placement relative to the anchor
+
+	*-title* <text>:::
+		set the title of the message box
 
 *try* <commands> catch <on_error_commands>::
 	prevent an error in *commands* from aborting the whole commands
@@ -136,6 +171,12 @@ commands:
 *reg* <name> <content>::
 	set register *name* to *content*
 
+*select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...::
+	replace the current selections with the one described in the argument
+
+*debug* {info,buffers,options,memory,shared-strings}::
+	print some debug information in the *\*debug** buffer
+
 Note that those commands are also available in the interactive mode, but
 are not really useful in that context.
 
@@ -153,30 +194,30 @@ New commands can be defined using the *def* command:
 	*commands* is a string containing the commands to execute, and *flags*
 	can be any combination of the following parameters:
 
-*-params* <num>::
+*-params* <num>:::
 	the command accepts a *num* parameter, which can be either a number,
 	or of the form <min>..<max>, with both <min> and <max> omittable
 
-*-file-completion*::
+*-file-completion*:::
 	try file completion on any parameter passed to this command
 
-*-client-completion*::
+*-client-completion*:::
 	try client name completion on any parameter passed to this command
 
-*-buffer-completion*::
+*-buffer-completion*:::
 	try buffer name completion on any parameter passed to this command
 
-*-shell-completion*::
+*-shell-completion*:::
 	following string is a shell command which takes parameters as
 	positional params and output one completion candidate per line
 
-*-allow-override*::
+*-allow-override*:::
 	allow the new command to replace an exisiting one with the same name
 
-*-hidden*::
+*-hidden*:::
 	do not show the command in command name completions
 
-*-docstring*::
+*-docstring*:::
 	define the documentation string for the command
 
 Using shell expansion allows to define complex commands or to access Kakoune

doc/manpages/expansions.asciidoc

@@ -8,7 +8,7 @@ expansions - a
 Strings
 -------
 \'strings'::
-	uninterpreted strings, use a backslash (\\') to escape the separator
+	uninterpreted strings, use a backslash (\') to escape the separator
 "strings"::
 	expanded strings, % strings (c.f. next section) contained are expended,
 	use a backslash (\\%) to escape the separator

doc/manpages/highlighters.asciidoc

@@ -18,7 +18,7 @@ addhl <highlighter_name> <highlighter_parameters> ...
 and
 
 -----------------------
-*rmhl* <highlighter_id>
+rmhl <highlighter_id>
 -----------------------
 
 *highlighter_id* is a name generated by the highlighter specified with
@@ -32,7 +32,9 @@ General highlighters
 	highlight a regex, takes the regex as first parameter, followed by
 	any number of face parameters. For example:
 
-		addhl regex //(\hTODO:)?[^\n] 0:cyan 1:yellow,red
+-----------------------------------------------------
+    addhl regex //(\hTODO:)?[^\n] 0:cyan 1:yellow,red
+-----------------------------------------------------
 
 	will highlight C++ style comments in cyan, with an eventual 'TODO:'
 	in yellow on red background

doc/manpages/shortcuts.asciidoc

@@ -225,7 +225,7 @@ Changes
 *>*::
 	indent selected lines
 
-*<a->>*::
+*<a\->>*::
 	indent selected lines, including empty lines
 
 *<*::
@@ -284,7 +284,9 @@ Changes
 	rotate selections content, if specified, the count groups selections,
 	so the following command
 
-		3<a-'>
+----------
+    3<a-'>
+----------
 
 	rotate (1, 2, 3) and (3, 4, 6) independently