diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index 0d9c8fce..3deba503 100644
--- a/doc/pages/commands.asciidoc
+++ b/doc/pages/commands.asciidoc
@@ -485,15 +485,16 @@ New commands can be defined using the *define-command* command:
     *-shell-script-completion*:::
         following string is a shell command which takes parameters as
         positional params and outputs one completion candidate per line.
-        The provided shell command will run after each keypress
-
-        during the execution of the shell command, the following env vars are
+        The provided shell command will run after each keypress.
+        During the execution of the shell command, the following env vars are
         available:
 
-        - *kak_token_to_complete*::::
+        *$kak_token_to_complete*::::
             Index of the token being completed in the command line.
+            Note that unlike the Unix `argv` tradition,
+            0 is the first argument, not the command name itself.
 
-        - *kak_pos_in_token*::::
+        *$kak_pos_in_token*::::
             Position of the cursor inside the token being completed, in bytes
             from token start.
 
@@ -502,13 +503,14 @@ New commands can be defined using the *define-command* command:
         positional params and outputs one completion candidate per line.
         The provided shell command will run once at the beginning of each
         completion session, candidates are cached and then used by kakoune
-        internal fuzzy engine
-
-        during the execution of the shell command, the following env vars are
+        internal fuzzy engine.
+        During the execution of the shell command, the following env vars are
         available:
 
-            - *kak_token_to_complete*::::
-                Index of the token being completed in the command line.
+        *$kak_token_to_complete*::::
+            Index of the token being completed in the command line.
+            Note that unlike the Unix `argv` tradition,
+            0 is the first argument, not the command name itself.
 
 Using shell expansion allows defining complex commands or accessing
 Kakoune's state: