Merged array option branch.

1 files changed, 42 insertions, 15 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index f05eb7b..815a662 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -16,32 +16,38 @@ Here is a simple option file.
 option('someoption', type : 'string', value : 'optval', description : 'An option')
 option('other_one', type : 'boolean', value : false)
 option('combo_opt', type : 'combo', choices : ['one', 'two', 'three'], value : 'three')
+option('free_array_opt', type : 'array', value : ['one', 'two'])
 option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one', 'two'])
 ```
 
-All types allow a `description` value to be set describing the option, if no
-option is set then the name of the option will be used instead.
+All types allow a `description` value to be set describing the option,
+if no option is set then the name of the option will be used instead.
 
 ### Strings
 
-The string type is a free form string. If the default value is not set then an
-empty string will be used as the default.
+The string type is a free form string. If the default value is not set
+then an empty string will be used as the default.
 
 ### Booleans
 
-Booleans may have values of either `true` or `false`. If not default value is
-supplied then `true` will be used as the default.
+Booleans may have values of either `true` or `false`. If not default
+value is supplied then `true` will be used as the default.
 
 ### Combos
 
-A combo allows any one of the values in the `choices` parameter to be selected.
-If no default value is set then the first value will be the default.
+A combo allows any one of the values in the `choices` parameter to be
+selected.  If no default value is set then the first value will be the
+default.
 
 ### Arrays
 
-Arrays allow one or more of the values in the `choices` parameter to be selected.
-If the `value` parameter is unset then the values of `choices` will be used as
-the default.
+Arrays represent an array of strings. By default the array can contain
+arbitrary strings. To limit the possible values that can used set the
+`choices` parameter. Meson will then only allow the value array to
+contain strings that are in the given list. The array may be
+empty. The `value` parameter specifies the default value of the option
+and if it is unset then the values of `choices` will be used as the
+default.
 
 This type is new in version 0.44.0
 
@@ -61,9 +67,9 @@ prefix = get_option('prefix')
 ```
 
 It should be noted that you can not set option values in your Meson
-scripts. They have to be set externally with the `meson configure` command
-line tool. Running `meson configure` without arguments in a build dir shows
-you all options you can set.
+scripts. They have to be set externally with the `meson configure`
+command line tool. Running `meson configure` without arguments in a
+build dir shows you all options you can set.
 
 To change their values use the `-D`
 option:
@@ -72,5 +78,26 @@ option:
 $ meson configure -Doption=newvalue
 ```
 
+Setting the value of arrays is a bit special. If you only pass a
+single string, then it is considered to have all values separated by
+commas. Thus invoking the following command:
 
-**NOTE:** If you cannot call `meson configure` you likely have a old version of Meson. In that case you can call `mesonconf` instead, but that is deprecated in newer versions
+```console
+$ meson configure -Darray_opt=foo,bar
+```
+
+would set the value to an array of two elements, `foo` and `bar`.
+
+If you need to have commas in your string values, then you need to
+pass the value with proper shell quoting like this:
+
+```console
+$ meson configure "-Doption=['a,b', 'c,d']"
+```
+
+The inner values must always be single quotes and the outer ones
+double quotes.
+
+**NOTE:** If you cannot call `meson configure` you likely have a old
+  version of Meson. In that case you can call `mesonconf` instead, but
+  that is deprecated in newer versions