Docs: group commands in common sections

doc/pages/commands.asciidoc

@@ -1,21 +1,21 @@
 = Commands
 
-== 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
 command *q!* has to be used). Aliases are mentionned below each commands.
 
-*change-directory* [<directory>]::
-    *alias* cd +
-    change the current directory to *directory*, or the home directory if
-    unspecified
-
 *doc* <topic>::
     *alias* help +
     display documentation about a topic. The completion list displays the
     available topics
 
+== Files and Buffers
+
+*change-directory* [<directory>]::
+    *alias* cd +
+    change the current directory to *directory*, or the home directory if
+    unspecified
+
 *edit[!]* <filename> [<line> [<column>]]::
     *alias* e +
     open buffer on file, go to given line and column. If file is already
@@ -43,9 +43,6 @@ command *q!* has to be used). Aliases are mentionned below each commands.
     write all buffers and quit. If specified, the client exit status
     will be set to <exit status>
 
-*kill[!]*::
-    terminate the current session, all the clients as well as the server
-
 *buffer* <name>::
     *alias* b +
     switch to buffer <name>
@@ -62,37 +59,25 @@ command *q!* has to be used). Aliases are mentionned below each commands.
     *alias* db +
     delete the buffer <name>
 
+*rename-buffer* <name>::
+    set current buffer name
+
 *source* <filename>::
     execute commands in <filename>
 
-*colorscheme* <name>::
+== Clients and Sessions
-    load named colorscheme
 
 *rename-client* <name>::
     *alias* nc +
     set current client name
 
-*rename-buffer* <name>::
-    set current buffer name
-
 *rename-session* <name>::
     set current session name
 
-*echo* [options] <text>::
+*kill[!]*::
-    show *text* in status line, with the following *options*:
+    terminate the current session, all the clients as well as the server
 
-    *-markup*:::
+== Options
-        expand the markup strings in *text* (See
-        <<expansions#markup-strings,`:doc expansions markup-strings`>>)
-
-    *-debug*:::
-        print the given text to the *\*debug** buffer
-
-*nop*::
-    does nothing, but arguments will be evaluated (e.g. shell expansion)
-
-*fail* <text>::
-    raise an error, uses <text> as its description
 
 *declare-option* [-hidden] <type> <name> [<value>]::
     *alias* decl +
@@ -116,6 +101,12 @@ command *q!* has to be used). Aliases are mentionned below each commands.
     update the value of an option if its type supports that operation
     (See <<options#update-option,`:doc options update-option`>>)
 
+== Commands and Keys
+
+*define-command* [<flags>] <name> <command>::
+    *alias* def +
+    define a new command (See <<declaring-new-commands,Declaring new commands>>)
+
 *alias* <scope> <name> <command>::
     define a new alias, within the context of a scope
 
@@ -123,22 +114,14 @@ command *q!* has to be used). Aliases are mentionned below each commands.
     remove an alias if its current value is the same as the one passed
     as an optional parameter, remove it unconditionally otherwise
 
-*set-face* <name> <facespec>::
-    *alias* face +
-    define a face (See <<faces#,`:doc faces`>>)
-
-*execute-keys* [<flags>] <key> ...::
-    *alias* exec +
-    execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
-
 *evaluate-commands* [<flags>] <command> ...::
     *alias* eval +
     evaluate commands, as if they were entered in the command prompt
     (See <<execeval#,`:doc execeval`>>)
 
-*define-command* [<flags>] <name> <command>::
+*execute-keys* [<flags>] <key> ...::
-    *alias* def +
+    *alias* exec +
-    define a new command (See <<declaring-new-commands,Declaring new commands>>)
+    execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
 
 *map* <scope> <mode> <key> <keys>::
     bind a list of keys to a combination (See <<mapping#,`:doc mapping`>>)
@@ -146,6 +129,8 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 *unmap* <scope> <mode> <key> [<expected>]::
     unbind a key combination (See <<mapping#,`:doc mapping`>>)
 
+== Hooks
+
 *hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
     execute a command whenever an event is triggered
     (See <<hooks#,`:doc hooks`>>)
@@ -155,6 +140,25 @@ command *q!* has to be used). Aliases are mentionned below each commands.
     remove every hooks in *scope* that are part of the given *group*
     (See <<hooks#,`:doc hooks`>>)
 
+== Display
+
+*echo* [options] <text>::
+    show *text* in status line, with the following *options*:
+
+    *-markup*:::
+        expand the markup strings in *text* (See
+        <<expansions#markup-strings,`:doc expansions markup-strings`>>)
+
+    *-debug*:::
+        print the given text to the *\*debug** buffer
+
+*set-face* <name> <facespec>::
+    *alias* face +
+    define a face (See <<faces#,`:doc faces`>>)
+
+*colorscheme* <name>::
+    load named colorscheme
+
 *add-highlighter* [<flags>] <highlighter_name> <highlighter_parameters> ...::
     *alias* addhl +
     add a highlighter to the current window
@@ -168,7 +172,8 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 == Helpers
 
 Kakoune provides some helper commands that can be used to define composite
-commands:
+commands in scripts. They are also available in the interactive mode,
+but not really useful in that context.
 
 *prompt* <prompt> <command>::
     prompt the user for a string, when the user validates, executes the
@@ -179,9 +184,9 @@ commands:
     *-password* switch hides the entered text and clears the register
     after command execution.
 
-        The *-on-change* and *-on-abort* switches, followed by a command
+    The *-on-change* and *-on-abort* switches, followed by a command
-        will have this command executed whenever the prompt content changes
+    will have this command executed whenever the prompt content changes
-        or the prompt is aborted, respectively.
+    or the prompt is aborted, respectively.
 
 *on-key* <command>::
     wait for next key from user, then execute <command>, the key is
@@ -213,9 +218,15 @@ commands:
     execution, execute *on_error_commands* instead. If nothing is to be
     done on error, the catch part can be omitted
 
+*nop*::
+    does nothing, but arguments will be evaluated (e.g. shell expansion)
+
+*fail* <text>::
+    raise an error, uses <text> as its description
+
 *set-register* <name> <content>::
     *alias* reg +
-    set register *name* to *content*
+    set register *name* to *content* (See <<registers#,`:doc registers`>>)
 
 *select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...::
     replace the current selections with the one described in the argument
@@ -223,9 +234,6 @@ commands:
 *debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}::
     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.
-
 == Multiple commands
 
 Commands (c.f. previous sections) can be chained, by being separated either