diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc
index 2a68bd72..96afb9a4 100644
--- a/doc/pages/options.asciidoc
+++ b/doc/pages/options.asciidoc
@@ -10,13 +10,16 @@ scripts.
 Options can be modified using the `set-option` command:
 
 ---------------------------------
-set-option <scope> <name> <value>
+set-option [-add] <scope> <name> <value>
 ---------------------------------
 
 <scope> can be *global*, *buffer*, *window* or *current* (See
-<<scopes#,`:doc scopes`>>). *current* relate to the narrowest scope in
+<<scopes#,`:doc scopes`>>). *current* relates to the narrowest scope in
 which the option is already set.
 
+If `-add` is specified, the new value is *added* to the current one
+instead of replacing it (the exact outcome depends on the type, see below).
+
 [[unset-option]]
 Options values can be unset in a specific scope with the `unset-option`
 command:
@@ -56,7 +59,8 @@ Some types are usable for user defined options while some other types
 are exclusively available to built-in options.
 
 *int*::
-    an integer number
+    an integer number.
+    `set -add` performs a math addition
 
 *bool*::
     a boolean value, yes/true or no/false
@@ -69,11 +73,12 @@ are exclusively available to built-in options.
     is not a valid regex
 
 *coord*::
-    a line, column pair (separated by comma)
+    a line, column pair (separated by a comma)
 
 *<type>-list*::
     a list, elements are separated by a colon (:) if an element needs
-    to contain a colon, it can be escaped with a backslash
+    to contain a colon, it can be escaped with a backslash.
+    `set -add` appends the new element to the list
 
 *range-specs*::
     a `:` separated list of a pair of a buffer range (`<begin
@@ -84,6 +89,7 @@ are exclusively available to built-in options.
     updated according to all the buffer modifications that happened
     since its timestamp.
     See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
+    `set -add` appends the new pair to the list
 
 *line-specs*::
     a `:` separated list of a line number and a corresponding flag
@@ -92,6 +98,7 @@ are exclusively available to built-in options.
     an option of this type, its lines gets updated according to all the
     buffer modifications that happened since its timestamp.
     See <<highlighters#specs-highlighters,`:doc highlighters specs-highlighters`>>)
+    `set -add` appends the new spec to the list
 
 *completions*::
     a `:` separated list of `<text>|<docstring>|<menu text>`
@@ -104,7 +111,13 @@ are exclusively available to built-in options.
 
 *flags(value1|value2|...)*::
     a set of flags, taking a combination of the given values joined by a
-    '|' character
+    '|' character.
+    `set -add` adds the new flag to the combination
+
+*<type>-to-<type>-map*::
+    a `:` separated list of `key=value` pairs.
+    `set -add` adds the new pair to the hashmap or replace an already
+    existing key.
 
 == Builtin options