Document the priority option in shell-script-candidates/completions

doc/pages/commands.asciidoc

@@ -482,6 +482,7 @@ New commands can be defined using the *define-command* command:
         define the documentation string for the command
 
     *-menu*:::
+    *-priority*:::
     *-file-completion*:::
     *-client-completion*:::
     *-buffer-completion*:::
@@ -517,6 +518,9 @@ Command completion can be configured with the *complete-command* command:
         permitted parameters. Kakoune will autoselect the best completion
         candidate on command validation.
 
+    *-priority*:::
+        see `shell-script-candidates`.
+
     *completion_type* can be:
 
     *file*:::
@@ -557,6 +561,13 @@ Command completion can be configured with the *complete-command* command:
         completion session, candidates are cached and then used by kakoune
         internal fuzzy engine.
 
+        If the `-priority` switch is specified, shell script output lines
+        must match `<candidate>|<priority>`. In this case, any `|` or `\`
+        characters that occur within the `<candidate>` field, should be
+        escaped as `\|` or `\\`. The priority field is a positive integer
+        to sort completions (lower is better), same as in the `completions`
+        type in <<options#types,`:doc options types`>>.
+
         During the execution of the shell script, the following env vars are
         available:
 

doc/pages/options.asciidoc

@@ -142,7 +142,7 @@ are exclusively available to built-in options.
     escaped as `\|` or `\\`.
 
 *completions*::
-    a list of `<text>|<select cmd>|<menu text>` candidates,
+    a list of `<text>|<select cmd>|<menu text>[|<priority>]` candidates,
     except for the first element which follows the
     `<line>.<column>[+<length>]@<timestamp>` format to define where the
     completion apply in the buffer.
@@ -152,8 +152,11 @@ are exclusively available to built-in options.
 
     Options of this type are are meant to be added to the `completers`
     option to provide insert mode completion. Candidates are shown if the
-    text typed by the user (between `<line>.<column>` and the cursor) is a
-    subsequence of `<text>`.
+    query typed by the user (the text between `<line>.<column>` and the
+    cursor) is a subsequence of `<text>`. Candidates are sorted by how well
+    they match the query - by length of matching subsequences and number
+    of matched word boundaries (higher is better) as well as the optional
+    `<priority>` field, which is a positive integer (lower is better).
 
     For each remaining candidate, the completion menu displays
     `<text>`, followed by `<menu text>`, which is a Markup string (see