6 files changed, 71 insertions, 28 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index f70dda5..9ccdf83 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -107,6 +107,13 @@ $ meson configure "-Doption=['a,b', 'c,d']"
 The inner values must always be single quotes and the outer ones
 double quotes.
 
+To change values in subprojects prepend the name of the subproject and
+a colon:
+
+```console
+$ meson configure -Dsubproject:option=newvalue
+```
+
 **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/Dependencies.md b/docs/markdown/Dependencies.md
index 6653cc1..74a918a 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -252,3 +252,15 @@ llvm_dep = dependency(
   'llvm', version : '>= 4.0', modules : ['amdgpu'], optional_modules : ['inteljitevents'],
 )
 ```
+
+## Python3
+
+Python3 is handled specially by meson:
+1. Meson tries to use `pkg-config`.
+1. If `pkg-config` fails meson uses fallback:
+    - On Windows fallback is current `python3` interpreter.
+    - On OSX fallback is framework dependency from `/Library/Frameworks`.
+
+Note that `python3` found by this dependency might differ from the one used in
+`python3` module because modules uses current interpreter but dependency tries
+`pkg-config` first.
diff --git a/docs/markdown/Icestorm-module.md b/docs/markdown/Icestorm-module.md
index 896311f..6aa8481 100644
--- a/docs/markdown/Icestorm-module.md
+++ b/docs/markdown/Icestorm-module.md
@@ -1,4 +1,4 @@
-# Unstable SIMD module
+# Unstable IceStorm module
 
 This module provides is available since version 0.45.0.
 
diff --git a/docs/markdown/Localisation.md b/docs/markdown/Localisation.md
index 34cad8d..517b642 100644
--- a/docs/markdown/Localisation.md
+++ b/docs/markdown/Localisation.md
@@ -4,37 +4,57 @@ short-description: Localization with GNU Gettext
 
 # Localisation
 
-Localising your application with GNU gettext takes a little effort but is quite straightforward. This documentation assumes that you have a `po` subdirectory at your project root directory that contains all the localisation info.
+Localising your application with GNU gettext takes a little effort but is quite straightforward. We'll create a `po` subdirectory at your project root directory for all the localisation info.
 
-The first thing you need is a file called `POTFILES`. It lists all the source files that gettext should scan in order to find strings to translate. The syntax of the file is one line per source file and the line must contain the relative path from source root. A sample POTFILES might look like this.
+## Generating .pot and .po files
+In your main meson.build file include the `po` subdirectory in the build proces.
+
+    subdir('po')
+
+In this `po` subdirectory we need:
+- `LINGUAS`: Space separated list of languages
+- `POTFILES`: List of source files to scan for translatable strings.
+- `meson.build`: Localization specific meson file
+
+### LINGUAS
+File with space separated list of languages. A sample LINGUAS might look like this.
+
+    aa ab ae af
+
+### POTFILES
+File that lists all the source files that gettext should scan in order to find strings to translate. The syntax of the file is one line per source file and the line must contain the relative path from source root. A sample POTFILES might look like this.
 
     src/file1.c
     src/file2.c
     src/subdir/file3.c
     include/mything/somefile.h
 
-We also need to define an array of strings containing all the locales we want to generate. This is done in the Meson file in the `po` subdirectory. Assuming we want to generate Finnish and German localisations, the definition would look like this.
-
+### meson.build
+Localization specific meson file. It imports and uses the `i18n` module. If not defined before it needs to define the `GETTEXT_PACKAGE` global.
 ```meson
-langs = ['fi', 'de']
+i18n = import('i18n')
+# define GETTEXT_PACKAGE
+add_project_arguments('-DGETTEXT_PACKAGE="intltest"', language:'c')
+i18n.gettext(meson.project_name(),
+    args: '--directory=' + meson.source_root()
+)
 ```
+The first command imports the `i18n` module that provides gettext features. The fourth line does the actual invocation. The first argument is the gettext package name. This causes two things to happen. The first is that Meson will generate binary mo files and put them to their proper locations when doing an install. The second is that it creates a build rule to regenerate the main pot file. If you are using the Ninja backend, this is how you would invoke the rebuild.
 
-Then we need to generate the main pot file. Usually this is generated manually or exists already. If not, see later on how to generate it using Meson. The potfile can have any name but is usually the name of the gettext package. Let's say the project is called *intltest*. In this case the corresponding pot file would be called `intltest.pot`.
+### generate .pot file
 
-For each language listed in the array above we need a corresponding `.po` file. This has to be generated manually, see the gettext manual for details. Once we have all this, we can define the localisation to Meson with these lines.
+Then we need to generate the main pot file. The potfile can have any name but is usually the name of the gettext package. Let's say the project is called *intltest*. In this case the corresponding pot file would be called `intltest.pot`.
 
-```meson
-i18n = import('i18n')
-langs = ['fi', 'de']
-i18n.gettext('intltest', languages : langs)
-```
-
-The first command imports the `i18n` module that provides gettext features. The third line does the actual invocation. The first argument is the gettext package name. This causes two things to happen. The first is that Meson will generate binary mo files and put them to their proper locations when doing an install. The second is that it creates a build rule to regenerate the main pot file. If you are using the Ninja backend, this is how you would invoke the rebuild.
+Run the following command from your build folder to generate the pot file. It is recommended to inspect it manually afterwards and fill in e.g. proper copyright and contact information.
 
 ```console
 $ ninja intltest-pot
 ```
 
-If the pot file does not yet exist, it will be created. It is recommended to inspect it manually afterwards and fill in e.g. proper copyright and contact information.
+### generate .po files
 
-Meson does not currently have built in commands for generating po files from the pot file. This is because translations are usually done by people who are not developers and thus have their own workflows.
+For each language listed in the array above we need a corresponding `.po` file. Those can be generated by running the following command from your build folder.
+
+```console
+$ ninja intltest-update-po
+```
diff --git a/docs/markdown/Python-3-module.md b/docs/markdown/Python-3-module.md
index dc6f571..7dda672 100644
--- a/docs/markdown/Python-3-module.md
+++ b/docs/markdown/Python-3-module.md
@@ -18,6 +18,10 @@ conventions of the target platform. All positional and keyword
 arguments are the same as for
 [shared_module](Reference-manual.md#shared_module).
 
+`extension_module` does not add any dependencies to the library so user may
+need to add `dependencies : dependency('python3')`, see
+[Python3 dependency](Dependencies.md#Python3).
+
 *Added 0.38.0*
 
 ## language_version
diff --git a/docs/markdown/Using-wraptool.md b/docs/markdown/Using-wraptool.md
index 08b1bfa..f6023e8 100644
--- a/docs/markdown/Using-wraptool.md
+++ b/docs/markdown/Using-wraptool.md
@@ -1,9 +1,9 @@
 # Using wraptool
 
-Wraptool is a helper tool that allows you to manage your source
-dependencies using the WrapDB database. It gives you all things you
-would expect, such as installing and updating dependencies. The wrap
-tool works on all platforms, the only limitation is that the wrap
+Wraptool is a subcommand of Meson that allows you to manage your
+source dependencies using the WrapDB database. It gives you all things
+you would expect, such as installing and updating dependencies. The
+wrap tool works on all platforms, the only limitation is that the wrap
 definition works on your target platform. If you find some Wraps that
 don't work, please file bugs or, even better, patches.
 
@@ -16,7 +16,7 @@ are commands to type.
 The simplest operation to do is to query the list of packages
 available. To list them all issue the following command:
 
-    $ wraptool list
+    $ meson wrap list
     box2d
     enet
     gtest
@@ -33,13 +33,13 @@ available. To list them all issue the following command:
 Usually you want to search for a specific package. This can be done
 with the `search` command:
 
-    $ wraptool search jpeg
+    $ meson wrap search jpeg
     libjpeg
 
 To determine which versions of libjpeg are available to install, issue
 the `info` command:
 
-    $ wraptool info libjpeg
+    $ meson wrap info libjpeg
     Available versions of libjpeg:
       9a 2
 
@@ -54,7 +54,7 @@ Installing dependencies is just as straightforward. First just create
 the `subprojects` directory at the top of your source tree and issue
 the install command.
 
-    $ wraptool install libjpeg
+    $ meson wrap install libjpeg
     Installed libjpeg branch 9a revision 2
 
 Now you can issue a `subproject('libjpeg')` in your `meson.build` file
@@ -62,7 +62,7 @@ to use it.
 
 To check if your projects are up to date you can issue the `status` command.
 
-    $ wraptool status
+    $ meson wrap status
     Subproject status
      libjpeg up to date. Branch 9a, revision 2.
      zlib not up to date. Have 1.2.8 2, but 1.2.8 4 is available.
@@ -70,12 +70,12 @@ To check if your projects are up to date you can issue the `status` command.
 In this case `zlib` has a newer release available. Updating it is
 straightforward:
 
-    $ wraptool update zlib
+    $ meson wrap update zlib
     Updated zlib to branch 1.2.8 revision 4
 
 Wraptool can do other things besides these. Documentation for these
 can be found in the command line help, which can be accessed by
-`wraptool --help`.
+`meson wrap --help`.
 
 ## Promoting dependencies