13 files changed, 343 insertions, 96 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index cb7b19e..815a662 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -16,18 +16,43 @@ 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'])
 ```
 
-This demonstrates the three basic option types and their usage. String
-option is just a free form string and a boolean option is,
-unsurprisingly, true or false. The combo option can have any value
-from the strings listed in argument `choices`. If `value` is not set,
-it defaults to empty string for strings, `true` for booleans or the
-first element in a combo. You can specify `description`, which is a
-free form piece of text describing the option. It defaults to option
-name.
+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.
 
-These options are accessed in Meson code with the `get_option` function.
+### 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.
+
+### Booleans
+
+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.
+
+### Arrays
+
+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
+
+
+## Using build options
 
 ```meson
 optval = get_option('opt_name')
@@ -42,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:
@@ -53,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:
+
+```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
+**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
diff --git a/docs/markdown/Conference-presentations.md b/docs/markdown/Conference-presentations.md
index 15e4396..abfc52f 100644
--- a/docs/markdown/Conference-presentations.md
+++ b/docs/markdown/Conference-presentations.md
@@ -8,7 +8,7 @@
 
 - GStreamer conference 2015, [Done in 6.0 seconds](https://gstconf.ubicast.tv/videos/done-in-60-seconds-a-new-build-system-for-gstreamer) (jpakkane)
 
-- LCA 2016, [Builds, dependencies and deployment in the modern multiplatform world](https://www.youtube.com/watch?v=CTJtKtQ8R5k&feature=youtu.be) (jpakkane)
+- LCA 2016, [Builds, dependencies and deployment in the modern multiplatform world](https://www.youtube.com/watch?v=CTJtKtQ8R5k) (jpakkane)
 
 - GUADEC 2016, [Making your GNOME app compile 2.4x faster](https://media.ccc.de/v/44-making_your_gnome_app_compile_24x_faster) (nirbheek)
 
diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md
index f68b1f5..c1ad317 100644
--- a/docs/markdown/Cross-compilation.md
+++ b/docs/markdown/Cross-compilation.md
@@ -257,3 +257,29 @@ then you can access that using the `meson` object like this:
 myvar = meson.get_cross_property('somekey')
 # myvar now has the value 'somevalue'
 ```
+
+## Cross file locations
+
+As of version 0.44.0 meson supports loading cross files from system locations
+on Linux and the BSDs. This will be $XDG_DATA_DIRS/meson/cross, or if
+XDG_DATA_DIRS is undefined, then /usr/local/share/meson/cross and
+/usr/share/meson/cross will be tried in that order, for system wide cross
+files. User local files can be put in $XDG_DATA_HOME/meson/cross, or
+~/.local/share/meson/cross if that is undefined.
+
+The order of locations tried is as follows:
+ - A file relative to the local dir
+ - The user local location
+ - The system wide locations in order
+
+Linux and BSD distributions are encouraged to ship cross files either with
+their cross compiler toolchain packages or as a standalone package, and put
+them in one of the system paths referenced above.
+
+These files can be loaded automatically without adding a path to the cross
+file. For example, if a ~/.local/share/meson/cross contains a file called x86-linux,
+then the following command would start a cross build using that cross files:
+
+```sh
+meson builddir/ --cross-file x86-linux
+```
diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md
index 8e780d6..bae3edc 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -178,32 +178,51 @@ the list of sources for the target. The `modules` keyword of
 `dependency` works just like it does with Boost. It tells which
 subparts of Qt the program uses.
 
-## Pcap
+## Dependencies using config tools
 
-The pcap library does not ship with pkg-config at the time or writing
-but instead it has its own `pcap-config` util. Meson will use it
-automatically:
+CUPS, LLVM, PCAP, WxWidgets, libwmf, and GnuStep either do not provide
+pkg-config modules or additionally can be detected via a config tool
+(cups-config, llvm-config, etc). Meson has native support for these tools, and
+then can be found like other dependencies:
 
 ```meson
 pcap_dep = dependency('pcap', version : '>=1.0')
+cups_dep = dependency('cups', version : '>=1.4')
+llvm_dep = dependency('llvm', version : '>=4.0')
 ```
 
-## CUPS
-
-The cups library does not ship with pkg-config at the time or writing
-but instead it has its own `cups-config` util. Meson will use it
-automatically:
+Some of these tools (like wmf and cups) provide both pkg-config and config
+tools support. You can force one or another via the method keyword:
 
 ```meson
-cups_dep = dependency('cups', version : '>=1.4')
+wmf_dep = dependency('wmf', method : 'config-tool')
 ```
 
-## LibWMF
+## LLVM
+
+Meson has native support for LLVM going back to version LLVM version 3.5. 
+It supports a few additional features compared to other config-tool based
+dependencies.
+
+As of 0.44.0 Meson supports the `static` keyword argument for LLVM. Before this
+LLVM >= 3.9 would always dynamically link, while older versions would
+statically link, due to a quirk in `llvm-config`.
+
+### Modules, a.k.a. Components
 
-The libwmf library does not ship with pkg-config at the time or writing
-but instead it has its own `libwmf-config` util. Meson will use it
-automatically:
+Meson wraps LLVM's concept of components in it's own modules concept.
+When you need specific components you add them as modules as meson will do the
+right thing:
 
 ```meson
-libwmf_dep = dependency('libwmf', version : '>=0.2.8')
+llvm_dep = dependency('llvm', version : '>= 4.0', modules : ['amdgpu'])
+```
+
+As of 0.44.0 it can also take optional modules (these will affect the arguments
+generated for a static link):
+
+```meson
+llvm_dep = dependency(
+  'llvm', version : '>= 4.0', modules : ['amdgpu'], optional_modules : ['inteljitevents'],
+)
 ```
diff --git a/docs/markdown/Qt5-module.md b/docs/markdown/Qt5-module.md
index aea2ae1..b5393a8 100644
--- a/docs/markdown/Qt5-module.md
+++ b/docs/markdown/Qt5-module.md
@@ -1,7 +1,7 @@
 # Qt5 module
 
 The Qt5 module provides tools to automatically deal with the various
-tools and steps required for Qt. The module has one method.
+tools and steps required for Qt. The module has two methods.
 
 ## preprocess
 
@@ -12,6 +12,14 @@ This method takes the following keyword arguments:
 
 It returns an opaque object that should be passed to a main build target.
 
+## compile_translations (since v0.44.0)
+
+This method generates the necessary targets to build translation files with lrelease, it takes the following keyword arguments:
+ - `ts_files`, the list of input translation files produced by Qt's lupdate tool.
+ - `install` when true, this target is installed during the install step (optional).
+ - `install_dir` directory to install to (optional).
+ - `build_by_default` when set to true, to have this target be built by default, that is, when invoking plain ninja; the default value is false (optional).
+
 A simple example would look like this:
 
 ```meson
@@ -21,6 +29,7 @@ inc = include_directories('includes')
 moc_files = qt5.preprocess(moc_headers : 'myclass.h',
                            moc_extra_arguments: ['-DMAKES_MY_MOC_HEADER_COMPILE'],
                            include_directories: inc)
+translations = qt5.compile_translations(ts_files : 'myTranslation_fr.ts', build_by_default : true)
 executable('myprog', 'main.cpp', 'myclass.cpp', moc_files,
            include_directories: inc,
            dependencies : qt5_dep)
@@ -28,5 +37,4 @@ executable('myprog', 'main.cpp', 'myclass.cpp', moc_files,
 
 
 The 'modules' argument is used to include Qt modules in the project.
-See the Qt documentation for the [list of
-modules](http://doc.qt.io/qt-5/qtmodules.html).
+See the Qt documentation for the [list of modules](http://doc.qt.io/qt-5/qtmodules.html).
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 2aa9665..e6aa9d3 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -430,7 +430,7 @@ be passed to [shared and static libraries](#library).
   `project`'s `default_options` overriding the values of these options
   for this target only, since 0.40.0
 - `d_import_dirs` list of directories to look in for string imports used
-  in the D programmling language
+  in the D programming language
 - `d_unittest`, when set to true, the D modules are compiled in debug mode
 - `d_module_versions` list of module versions set when compiling D sources
 
@@ -855,6 +855,8 @@ This function prints its argument to stdout.
 
 This function prints its argument to stdout prefixed with WARNING:.
 
+*Added 0.44.0*
+
 ### project()
 
 ``` meson
@@ -1019,7 +1021,7 @@ has one argument the others don't have:
 ### subdir()
 
 ``` meson
-    void subdir(dir_name)
+    void subdir(dir_name, ...)
 ```
 
 Enters the specified subdirectory and executes the `meson.build` file
@@ -1032,6 +1034,12 @@ current build file and in all subsequent build files executed with
 Note that this means that each `meson.build` file in a source tree can
 and must only be executed once.
 
+This function has one keyword argument.
+
+ - `if_found` takes one or several dependency objects and will only
+   recurse in the subdir if they all return `true` when queried with
+   `.found()`
+
 ### subproject()
 
 ``` meson
@@ -1608,6 +1616,10 @@ an external dependency with the following methods:
    pkg-config variable specified, or, if invoked on a non pkg-config
    dependency, error out
 
+ - `get_configtool_variable(varname)` (*Added 0.44.0*) will get the 
+   command line argument from the config tool (with `--` prepended), or,
+   if invoked on a non config-tool dependency, error out.
+
  - `type_name()` which returns a string describing the type of the
    dependency, the most common values are `internal` for deps created
    with `declare_dependencies` and `pkgconfig` for system dependencies
diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md
index 0e8da43..23d5e97 100644
--- a/docs/markdown/Running-Meson.md
+++ b/docs/markdown/Running-Meson.md
@@ -1,17 +1,26 @@
 ---
-short-description: Building a project with meson
+short-description: Building a project with Meson
 ...
 
-# Running meson
+# Running Meson
 
-There are two different ways of invoking Meson. First, you can run it directly from the source tree with the command `/path/to/source/meson.py`. Meson may also be installed in which case the command is simply `meson`. In this manual we only use the latter format for simplicity.
+There are two different ways of invoking Meson. First, you can run it
+directly from the source tree with the command
+`/path/to/source/meson.py`. Meson may also be installed in which case
+the command is simply `meson`. In this manual we only use the latter
+format for simplicity.
 
-At the time of writing only a command line version of Meson is available. This means that Meson must be invoked using the terminal. If you wish to use the MSVC compiler, you need to run Meson under "Visual Studio command prompt".
+At the time of writing only a command line version of Meson is
+available. This means that Meson must be invoked using the
+terminal. If you wish to use the MSVC compiler, you need to run Meson
+under "Visual Studio command prompt".
 
 Configuring the source
 ==
 
-Let us assume that we have a source tree that has a Meson build system. This means that at the topmost directory has a file called `meson.build`. We run the following commands to get the build started.
+Let us assume that we have a source tree that has a Meson build
+system. This means that at the topmost directory has a file called
+`meson.build`. We run the following commands to get the build started.
 
 
     cd /path/to/source/root
@@ -19,13 +28,22 @@ Let us assume that we have a source tree that has a Meson build system. This mea
     cd builddir
     meson ..
 
-First we create a directory to hold all files generated during the build. Then we go into it and invoke Meson, giving it the location of the source root.
+First we create a directory to hold all files generated during the
+build. Then we go into it and invoke Meson, giving it the location of
+the source root.
 
-Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, but you may omit either `srcdir` or `builddir`. Meson will deduce the `srcdir` by the location of `meson.build`. The other one will be your `pwd`.
+Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`,
+but you may omit either `srcdir` or `builddir`. Meson will deduce the
+`srcdir` by the location of `meson.build`. The other one will be your
+`pwd`.
 
-Meson then loads the build configuration file and writes the corresponding build backend in the build directory. By default Meson generates a *debug build*, which turns on basic warnings and debug information and disables compiler optimizations.
+Meson then loads the build configuration file and writes the
+corresponding build backend in the build directory. By default Meson
+generates a *debug build*, which turns on basic warnings and debug
+information and disables compiler optimizations.
 
-You can specify a different type of build with the `--buildtype` command line argument. It can have one of the following values.
+You can specify a different type of build with the `--buildtype`
+command line argument. It can have one of the following values.
 
 | value            | meaning                                                                                                                                                    |
 | ------           | --------                                                                                                                                                   |
@@ -34,42 +52,78 @@ You can specify a different type of build with the `--buildtype` command line ar
 | `debugoptimized` | debug info is generated and the code is optimized (on most compilers this means `-g -O2`)                                                                  |
 | `release`        | full optimization, no debug info                                                                                                                           |
 
-The build directory is mandatory. The reason for this is that it simplifies the build process immensely. Meson will not under any circumstances write files inside the source directory (if it does, it is a bug and should be fixed). This means that the user does not need to add a bunch of files to their revision control's ignore list. It also means that you can create arbitrarily many build directories for any given source tree. If we wanted to test building the source code with the Clang compiler instead of the system default, we could just type the following commands.
+The build directory is mandatory. The reason for this is that it
+simplifies the build process immensely. Meson will not under any
+circumstances write files inside the source directory (if it does, it
+is a bug and should be fixed). This means that the user does not need
+to add a bunch of files to their revision control's ignore list. It
+also means that you can create arbitrarily many build directories for
+any given source tree. If we wanted to test building the source code
+with the Clang compiler instead of the system default, we could just
+type the following commands.
 
     cd /path/to/source/root
     mkdir buildclang
     cd buildclang
     CC=clang CXX=clang++ meson ..
 
-This separation is even more powerful if your code has multiple configuration options (such as multiple data backends). You can create a separate subdirectory for each of them. You can also have build directories for optimized builds, code coverage, static analysis and so on. They are all neatly separated and use the same source tree. Changing between different configurations is just a question of changing to the corresponding directory.
+This separation is even more powerful if your code has multiple
+configuration options (such as multiple data backends). You can create
+a separate subdirectory for each of them. You can also have build
+directories for optimized builds, code coverage, static analysis and
+so on. They are all neatly separated and use the same source
+tree. Changing between different configurations is just a question of
+changing to the corresponding directory.
 
-Unless otherwise mentioned, all following command line invocations are meant to be run in the build directory.
+Unless otherwise mentioned, all following command line invocations are
+meant to be run in the build directory.
 
-By default Meson will use the Ninja backend to build your project. If you wish to use any of the other backends, you need to pass the corresponding argument during configuration time. As an example, here is how you would use Meson to generate a Visual studio solution.
+By default Meson will use the Ninja backend to build your project. If
+you wish to use any of the other backends, you need to pass the
+corresponding argument during configuration time. As an example, here
+is how you would use Meson to generate a Visual studio solution.
 
     meson <source dir> <build dir> --backend=vs2010
 
-You can then open the generated solution with Visual Studio and compile it in the usual way. A list of backends can be obtained with `meson --help`.
+You can then open the generated solution with Visual Studio and
+compile it in the usual way. A list of backends can be obtained with
+`meson --help`.
 
 Building the source
 ==
 
-If you are not using an IDE, Meson uses the [Ninja build system](https://ninja-build.org/) to actually build the code. To start the build, simply type the following command.
+If you are not using an IDE, Meson uses the [Ninja build
+system](https://ninja-build.org/) to actually build the code. To start
+the build, simply type the following command.
 
     ninja
 
-The main usability difference between Ninja and Make is that Ninja will automatically detect the number of CPUs in your computer and parallelize itself accordingly. You can override the amount of parallel processes used with the command line argument `-j <num processes>`.
-
-It should be noted that after the initial configure step `ninja` is the only command you ever need to type to compile. No matter how you alter your source tree (short of moving it to a completely new location), Meson will detect the changes and regenerate itself accordingly. This is especially handy if you have multiple build directories. Often one of them is used for development (the "debug" build) and others only every now and then (such as a "static analysis" build). Any configuration can be built just by `cd`'ing to the corresponding directory and running Ninja.
+The main usability difference between Ninja and Make is that Ninja
+will automatically detect the number of CPUs in your computer and
+parallelize itself accordingly. You can override the amount of
+parallel processes used with the command line argument `-j <num
+processes>`.
+
+It should be noted that after the initial configure step `ninja` is
+the only command you ever need to type to compile. No matter how you
+alter your source tree (short of moving it to a completely new
+location), Meson will detect the changes and regenerate itself
+accordingly. This is especially handy if you have multiple build
+directories. Often one of them is used for development (the "debug"
+build) and others only every now and then (such as a "static analysis"
+build). Any configuration can be built just by `cd`'ing to the
+corresponding directory and running Ninja.
 
 Running tests
 ==
 
-Meson provides native support for running tests. The command to do that is simple.
+Meson provides native support for running tests. The command to do
+that is simple.
 
     ninja test
 
-Meson does not force the use of any particular testing framework. You are free to use GTest, Boost Test, Check or even custom executables.
+Meson does not force the use of any particular testing framework. You
+are free to use GTest, Boost Test, Check or even custom executables.
 
 Installing
 ==
@@ -78,13 +132,17 @@ Installing the built software is just as simple.
 
     ninja install
 
-By default Meson installs to `/usr/local`. This can be changed by passing the command line argument `--prefix /your/prefix` to Meson during configure time. Meson also supports the `DESTDIR` variable used in e.g. building packages. It is used like this:
+By default Meson installs to `/usr/local`. This can be changed by
+passing the command line argument `--prefix /your/prefix` to Meson
+during configure time. Meson also supports the `DESTDIR` variable used
+in e.g. building packages. It is used like this:
 
     DESTDIR=/path/to/staging ninja install
 
 Command line help
 ==
 
-Meson has a standard command line help feature. It can be accessed with the following command.
+Meson has a standard command line help feature. It can be accessed
+with the following command.
 
     meson --help
diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md
index 923b6a3..14f01d4 100644
--- a/docs/markdown/Subprojects.md
+++ b/docs/markdown/Subprojects.md
@@ -4,69 +4,76 @@ short-description: Using meson projects as subprojects within other meson projec
 
 # Subprojects
 
-Some platforms do not provide a native packaging system. In these cases it is common to bundle all third party libraries in your source tree. This is usually frowned upon because it makes it hard to add these kinds of projects into e.g. those Linux distributions that forbid bundled libraries.
-
-Meson tries to solve this problem by making it extremely easy to provide both at the same time. The way this is done is that Meson allows you to take any other Meson project and make it a part of your build without (in the best case) any changes to its Meson setup. It becomes a transparent part of the project. The basic idiom goes something like this.
+Some platforms do not provide a native packaging system. In these
+cases it is common to bundle all third party libraries in your source
+tree. This is usually frowned upon because it makes it hard to add
+these kinds of projects into e.g. those Linux distributions that
+forbid bundled libraries.
+
+Meson tries to solve this problem by making it extremely easy to
+provide both at the same time. The way this is done is that Meson
+allows you to take any other Meson project and make it a part of your
+build without (in the best case) any changes to its Meson setup. It
+becomes a transparent part of the project. The basic idiom goes
+something like this.
 
 ```meson
-dep = dependency('foo', required : false)
-if dep.found()
-  # set up project using external dependency
-else
-  subproject('foo')
-  # set up rest of project as if foo was provided by this project
-endif
+dep = dependency('foo', fallback : [subproject_name, variable_name]
 ```
 
-All Meson features of the subproject, such as project options keep working and can be set in the master project. There are a few limitations, the most important being that global compiler arguments must be set in the main project before calling subproject. Subprojects must not set global arguments because there is no way to do that reliably over multiple subprojects. To check whether you are running as a subproject, use the `is_subproject` function.
-
-As an example, suppose we have a simple project that provides a shared library.
+As an example, suppose we have a simple project that provides a shared
+library. It would be set up like this.
 
 ```meson
 project('simple', 'c')
 i = include_directories('include')
 l = shared_library('simple', 'simple.c', include_directories : i, install : true)
+simple_dep = declare_dependency(include_directories : i,
+  link_with : l)
 ```
 
-Then we could use that from a master project. First we generate a subdirectory called `subprojects` in the root of the master directory. Then we create a subdirectory called `simple` and put the subproject in that directory. Now the subproject can be used like this.
+Then we could use that from a master project. First we generate a
+subdirectory called `subprojects` in the root of the master
+directory. Then we create a subdirectory called `simple` and put the
+subproject in that directory. Now the subproject can be used like
+this.
 
 ```meson
 project('master', 'c')
-dep = dependency('simple', required : false)
-if dep.found()
-  i = []
-  l = []
-else
-  sp = subproject('simple') # This is a name of a subdirectory in subprojects.
-  i = sp.get_variable('i')
-  l = sp.get_variable('l')
-endif
-exe = executable('prog', 'prog.c', include_directories : i, link_with : l,
+dep = dependency('simple', fallback : ['simple', 'simple_dep']
+exe = executable('prog', 'prog.c',
                  dependencies : dep, install : true)
 ```
 
-With this setup the system dependency is used when it is available, otherwise we fall back on the bundled version.
-
-It should be noted that this only works for subprojects that are built with Meson. It can not be used with any other build system. The reason is the simple fact that there is no possible way to do this reliably with mixed build systems.
-
-Subprojects can use other subprojects, but all subprojects must reside in the top level `subprojects` directory. Recursive use of subprojects is not allowed, though, so you can't have subproject `a` that uses subproject `b` and have `b` also use `a`.
-
-## Subprojects and dependencies
-
-A common use case is to use subprojects to provide dependencies on platforms that do not provide them out of the box. This is especially common on Windows. Meson makes this easy while at the same time using system dependencies if are available. The way to do this is to set up a subproject that builds the dependency and has an internal dependency declared like this:
+With this setup the system dependency is used when it is available,
+otherwise we fall back on the bundled version. If you wish to always
+use the embedded version, then you would declare it like this:
 
 ```meson
-proj_dep = declare_dependency(...)
+simple_sp = subproject('simple')
+dep = simple_sp.get_variable('simple_dep')
 ```
 
-Then you can use the subproject in the master project like this:
+All Meson features of the subproject, such as project options keep
+working and can be set in the master project. There are a few
+limitations, the most important being that global compiler arguments
+must be set in the main project before calling subproject. Subprojects
+must not set global arguments because there is no way to do that
+reliably over multiple subprojects. To check whether you are running
+as a subproject, use the `is_subproject` function.
 
-```meson
-sp_dep = dependency('subproj_pkgconfig_name', fallback : ['subproj_name', 'proj_dep'])
-```
+It should be noted that this only works for subprojects that are built
+with Meson. It can not be used with any other build system. The reason
+is the simple fact that there is no possible way to do this reliably
+with mixed build systems.
 
-This uses the system dependency when available and the self built version if not. If you want to always use the subproject, that is also possible, just use `subproject` and `get_variable` as discussed above to get the dependency object.
+Subprojects can use other subprojects, but all subprojects must reside
+in the top level `subprojects` directory. Recursive use of subprojects
+is not allowed, though, so you can't have subproject `a` that uses
+subproject `b` and have `b` also use `a`.
 
 # Obtaining subprojects
 
-Meson ships with a dependency system to automatically obtain dependency subprojects. It is documented in the [Wrap dependency system manual](Wrap-dependency-system-manual.md).
+Meson ships with a dependency system to automatically obtain
+dependency subprojects. It is documented in the [Wrap dependency
+system manual](Wrap-dependency-system-manual.md).
diff --git a/docs/markdown/snippets/builtin-python.md b/docs/markdown/snippets/builtin-python.md
new file mode 100644
index 0000000..01bb6e0
--- /dev/null
+++ b/docs/markdown/snippets/builtin-python.md
@@ -0,0 +1,9 @@
+# Embedded Python in Windows MSI packages
+
+Meson now ships an internal version of Python in the MSI installer packages.
+This means that it can run Python scripts that are part of your build
+transparently. That is, if you do the following:
+
+    myprog = find_program('myscript.py')
+
+Then Meson will run the script with its internal Python version if necessary.
diff --git a/docs/markdown/snippets/config-tool-variable-method.md b/docs/markdown/snippets/config-tool-variable-method.md
new file mode 100644
index 0000000..7725982
--- /dev/null
+++ b/docs/markdown/snippets/config-tool-variable-method.md
@@ -0,0 +1,11 @@
+# Config-Tool based dependencies gained a method to get arbitrary options
+
+A number of dependencies (CUPS, LLVM, pcap, WxWidgets, GnuStep) use a config
+tool instead of pkg-config. As of this version they now have a
+`get_configtool_variable` method, which is analogous to the
+`get_pkgconfig_variable` for pkg config.
+
+```meson
+dep_llvm = dependency('LLVM')
+llvm_inc_dir = dep_llvm.get_configtool_variable('includedir')
+```
diff --git a/docs/markdown/snippets/if-found.md b/docs/markdown/snippets/if-found.md
new file mode 100644
index 0000000..a8d4932
--- /dev/null
+++ b/docs/markdown/snippets/if-found.md
@@ -0,0 +1,13 @@
+# Added `if_found` to subdir
+
+Added a new keyword argument to the `subdir` command. It is given a
+list of dependency objects and the function will only recurse in the
+subdirectory if they are all found. Typical usage goes like this.
+
+    d1 = dependency('foo') # This is found
+    d2 = dependency('bar') # This is not found
+
+    subdir('somedir', if_found : [d1, d2])
+
+In this case the subdirectory would not be entered since `d2` could
+not be found.
diff --git a/docs/markdown/snippets/option-array-type.md b/docs/markdown/snippets/option-array-type.md
new file mode 100644
index 0000000..9eb1312
--- /dev/null
+++ b/docs/markdown/snippets/option-array-type.md
@@ -0,0 +1,18 @@
+# An array type for user options
+
+Previously to have an option that took more than one value a string value would
+have to be created and split, but validating this was difficult. A new array type
+has been added to the meson_options.txt for this case. It works like a 'combo', but
+allows more than one option to be passed. The values can optionally be validated
+against a list of valid values. When used on the command line (with -D), values
+are passed as a comma separated list.
+
+```meson
+option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one'])
+```
+
+These can be overwritten on the command line,
+
+```meson
+meson _build -Darray_opt=two,three
+```
diff --git a/docs/markdown/snippets/system-wide-cross-files.md b/docs/markdown/snippets/system-wide-cross-files.md
new file mode 100644
index 0000000..66c454f
--- /dev/null
+++ b/docs/markdown/snippets/system-wide-cross-files.md
@@ -0,0 +1,20 @@
+## System wide and user local cross files
+
+Meson has gained the ability to load cross files from predefined locations
+without passing a full path on Linux and the BSD OSes. User local files will be
+loaded from `$XDG_DATA_HOME/meson/cross`, or if XDG_DATA_HOME is undefined,
+`~/.local/share/meson/cross` will be used.
+
+For system wide paths the values of `$XDG_DATA_DIRS` + `/meson/cross` will be used,
+if XDG_DATA_DIRS is undefined then `/usr/local/share/meson/cross:/usr/share/meson/cross`
+will be used instead.
+
+A file relative to the current working directory will be tried first, then the
+user specific path will be tried before the system wide paths.
+
+Assuming that a file x86-linux is located in one of those places a cross build
+can be started with:
+
+```sh
+meson builddir/ --cross-file x86-linux
+```