diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index 940b109f..84ba0493 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.
 
@@ -501,14 +502,16 @@ New commands can be defined using the *define-command* command:
         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 once at the beginning of each
-        completion session, candidates are cached and then used by Kakoune
-        internal fuzzy engine
+        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
+        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: