diff --git a/doc/pages/changelog.asciidoc b/doc/pages/changelog.asciidoc
index 156e6472..182b962e 100644
--- a/doc/pages/changelog.asciidoc
+++ b/doc/pages/changelog.asciidoc
@@ -31,6 +31,9 @@ released versions.
 * Added a new hook `ModuleLoad` which is run when a module is loaded,
   allowing for module specific configuration.
 
+* Shell quoting of lists is not automatic anymore, `$kak_quoted_...`
+  makes it opt-in, and works for all option types.
+
 == Kakoune 2019.01.20
 
 * `auto_complete` has been renamed to `autocomplete` for more
diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc
index 9f3f5f95..63980b8e 100644
--- a/doc/pages/expansions.asciidoc
+++ b/doc/pages/expansions.asciidoc
@@ -128,24 +128,23 @@ Here's how expansion patterns map to variable names:
 *%val{x}*::
     becomes `$kak_x`
 
-When turned into environment variables, list-type options, `$kak_reg_x`, and
-"quoted list" values will be shell-quoted so the shell doesn't get confused
-about how many items the list contains. You will need to apply `eval` to get
-back the original values. For example, if you want to process the contents
-of each selection, you can do something like:
+Values can be quoted with a shell compatible quoting by using `$kak_quoted_`
+as a prefix, this is mostly useful for list-type options and registers, as
+it allows to correctly work with lists where elements might contains
+whitespaces:
 
 ----
-eval set -- "$kak_selections"
+eval set -- "$kak_quoted_selections"
 while [ $# -gt 0 ]; do
     # ... do a thing with $1 ...
     shift
 done
 ----
 
-The `eval` command will take the expanded `$kak_selections` and unquote them,
-then execute the resulting `set` command, which sets the shell's argument
-variables to the items from `$kak_selections`. The `while` loop with `shift`
-iterates through the arguments one by one.
+The `eval` command will take the expanded `$kak_quoted_selections`
+and unquote them, then execute the resulting `set` command, which sets
+the shell's argument variables to the items from `$kak_selections`. The
+`while` loop with `shift` iterates through the arguments one by one.
 
 Only variables actually mentioned in the body of the shell expansion will
 be exported into the shell's environment. For example: