6 files changed, 133 insertions, 31 deletions

diff --git a/docs/markdown/Adding-new-projects-to-wrapdb.md b/docs/markdown/Adding-new-projects-to-wrapdb.md
index 25fb61c..a266379 100644
--- a/docs/markdown/Adding-new-projects-to-wrapdb.md
+++ b/docs/markdown/Adding-new-projects-to-wrapdb.md
@@ -72,35 +72,104 @@ will be posted in a comment to this issue.
 NOTE: Requesting a branch is not necessary. WrapDB maintainer can create the branch and
 modify the PR accordingly if the project repository exists.
 
-### Add a new wrap
+### Creating the wrap contents
 
-First you need to fork the repository to your own page.
-Then you can create the first Wrap commit that usually looks something like this.
+Setting up the contents might seem a bit counterintuitive at
+first. Just remember that the outcome needs to have one (and only one)
+commit that has all the build definition files (i.e. `meson.build` and
+`meson_options.txt` files) and _nothing else_. It is good practice to
+have this commit in a branch whose name matches the release as
+described above.
+
+First you need to fork the repository to your own page using GitHub's
+fork button. Then you can clone the repo to your local machine.
+
+
+```
+git clone git@github.com:yourusername/libfoo.git foo-wrap
+```
+
+Create a new branch for your work:
+
+```
+git checkout -b 1.0.0
+```
+
+If you are adding new changes to an existing branch, leave out the
+`-b` argument.
+
+Now you need to copy the source code for the original project to this
+directory. If you already have it extracted somewhere, you'd do
+something like this:
+
+```
+cd /path/to/source/extract/dir
+cp -r * /path/to/foo-wrap
+```
+
+Now all the files should be in the wrap directory. Do _not_ add them
+to Git, though. Neither now or at any time during this process. The
+repo must contain only the newly created build files.
+
+New release branches require an `upstream.wrap` file, so create one if
+needed.
+
+```
+${EDITOR} upstream.wrap
+```
+
+The file format is simple, see any existing wrapdb repo for the
+content. The checksum is SHA-256 and can be calculated with the
+following command on most unix-like operating systems:
+
+```
+sha256sum path/to/libfoo-1.0.0.tar.gz
+```
+
+Under macOS the command is the following:
+
+```
+shasum -a 256 path/to/libfoo-1.0.0.tar.gz
+```
+
+Now you can create the build files and work on them until the project
+builds correctly.
+
+```
+${EDITOR} meson.build meson_options.txt
+```
+
+When you are satisfied with the results, add the build files to Git
+and push the result to GitHub.
 
 ```
-tar xzf libfoo-1.0.0.tar.gz
-git clone -b 1.0.0 git@github.com:yourusername/libfoo.git tmpdir
-mv tmpdir/.git libfoo-1.0.0
-rm -rf tmpdir
-cd libfoo-1.0.0
-git reset --hard
-emacs upstream.wrap meson.build
 <verify that your project builds and runs>
 git add upstream.wrap meson.build
 git commit -a -m 'Add wrap files for libfoo-1.0.0'
-git push origin 1.0.0
+git push -u origin 1.0.0
 ```
 
-Now you should create a pull request on GitHub. Remember to create it against the
-correct branch rather than master (`1.0.0` branch in this example). GitHub should do
-this automatically.
+Now you should create a pull request on GitHub. Try to create it
+against the correct branch rather than master (`1.0.0` branch in this
+example). GitHub should do this automatically.
 
 If the branch doesn't exist file a pull request against master.
 WrapDB maintainers can fix it before merging.
 
+If packaging review requires you to do changes, use the `--amend`
+argument to `commit` so that your branch will continue to have only
+one commit.
+
+```
+${EDITOR} meson.build
+git commit -a --amend
+git push --force
+```
+
 ## What is done by WrapDB maintainers
 
-[mesonwrap tools](Wrap-maintainer-tools.md) must be used for the tasks below.
+[mesonwrap tools](Wrap-maintainer-tools.md) must be used for the tasks
+below.
 
 ### Adding new project to the Wrap provider service
 
@@ -110,7 +179,7 @@ Each project gets its own repo. It is initialized like this:
 mesonwrap new_repo --homepage=$HOMEPAGE --directory=$NEW_LOCAL_PROJECT_DIR $PROJECT_NAME
 ```
 
-The command creates a new repository and uploads it to Github.
+The command creates a new repository and uploads it to GitHub.
 
 `--version` flag may be used to create a branch immediately.
 
diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md
index f0b50d8..76bf939 100644
--- a/docs/markdown/Custom-build-targets.md
+++ b/docs/markdown/Custom-build-targets.md
@@ -29,14 +29,15 @@ it does for source generation.
 
 See [Generating Sources](Generating-sources.md) for more information on this topic.
 
-## Details on compiler invocations
+## Details on command invocation
 
 Meson only permits you to specify one command to run. This is by
 design as writing shell pipelines into build definition files leads to
-code that is very hard to maintain. If your compilation requires
+code that is very hard to maintain. If your command requires
 multiple steps you need to write a wrapper script that does all the
-necessary work. When doing this you need to be mindful of the
-following issues:
+necessary work.
+
+When doing this you need to be mindful of the following issues:
 
 * do not assume that the command is invoked in any specific directory
 * a target called `target` file `outfile` defined in subdir `subdir`
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index c289397..d315b53 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -397,6 +397,10 @@ the following special string substitutions:
 The returned object also has methods that are documented in the
 [object methods section](#custom-target-object) below.
 
+**Note:** Assuming that `command:` is executed by a POSIX `sh` shell is not
+portable, notably to Windows. Instead, consider using a `native: true`
+[executable()](#executable), or a python script.
+
 ### declare_dependency()
 
 ``` meson
@@ -1804,17 +1808,23 @@ the following methods.
   or `xcode`.
 
 - `build_root()`: returns a string with the absolute path to the build
-  root directory. Note: this function will return the build root of
-  the parent project if called from a subproject, which is usually
-  not what you want. Try using `current_build_dir()`.
+  root directory. *(deprecated since 0.56.0)*: this function will return the
+  build root of the parent project if called from a subproject, which is usually
+  not what you want. Try using `current_build_dir()` or `project_build_root()`.
 
 - `source_root()`: returns a string with the absolute path to the
   source root directory. Note: you should use the `files()` function
   to refer to files in the root source directory instead of
-  constructing paths manually with `meson.source_root()`. This
-  function will return the source root of the parent project if called
-  from a subproject, which is usually not what you want. Try using
-  `current_source_dir()`.
+  constructing paths manually with `meson.source_root()`.
+  *(deprecated since 0.56.0)*: This function will return the source root of the
+  parent project if called from a subproject, which is usually not what you want.
+  Try using `current_source_dir()` or `project_source_root()`.
+
+- `project_build_root()` *(since 0.56.0)*: returns a string with the absolute path
+  to the build root directory of the current (sub)project.
+
+- `project_source_root()` *(since 0.56.0)*: returns a string with the absolute path
+  to the source root directory of the current (sub)project.
 
 - `current_build_dir()`: returns a string with the absolute path to the
   current build directory.
diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md
index bbe3dbb..64ec6db 100644
--- a/docs/markdown/Syntax.md
+++ b/docs/markdown/Syntax.md
@@ -366,8 +366,9 @@ The following methods are defined for all arrays:
 ## Dictionaries
 
 Dictionaries are delimited by curly braces. A dictionary can contain an
-arbitrary number of key value pairs. Keys are required to be strings, values can
-be objects of any type. Prior to *0.53.0* keys were required to be literal strings.
+arbitrary number of key: value pairs. Keys are required to be strings, but values can
+be objects of any type. Prior to *0.53.0* keys were required to be literal
+strings, i.e., you could not use a variable containing a string value as a key.
 
 ```meson
 my_dict = {'foo': 42, 'bar': 'baz'}
diff --git a/docs/markdown/Tutorial.md b/docs/markdown/Tutorial.md
index f108c0c..bf337ba 100644
--- a/docs/markdown/Tutorial.md
+++ b/docs/markdown/Tutorial.md
@@ -75,12 +75,23 @@ When Meson is run it prints the following output.
 
 Now we are ready to build our code.
 
+
+```console
+$ cd builddir
+$ ninja
 ```
+
+If your Meson version is newer than 0.55.0, you can use the new
+backend-agnostic build command:
+
+```console
 $ cd builddir
 $ meson compile
 ```
 
-Once that is done we can run the resulting binary.
+For the rest of this document we are going to use the latter form.
+
+Once the executable is built we can run it.
 
 ```console
 $ ./demo
@@ -135,7 +146,7 @@ need to recreate our build directory, run any sort of magical commands
 or the like. Instead we just type the exact same command as if we were
 rebuilding our code without any build system changes.
 
-```
+```console
 $ meson compile
 ```
 
diff --git a/docs/markdown/snippets/deprecate_source_build_root.md b/docs/markdown/snippets/deprecate_source_build_root.md
new file mode 100644
index 0000000..1cebef4
--- /dev/null
+++ b/docs/markdown/snippets/deprecate_source_build_root.md
@@ -0,0 +1,10 @@
+## `meson.build_root()` and `meson.source_root()` are deprecated
+
+Those function are common source of issue when used in a subproject because they
+point to the parent project root which is rarely what is expected and is a
+violation of subproject isolation.
+
+`meson.current_source_dir()` and `meson.current_build_dir()` should be used instead
+and have been available in all Meson versions. New functions `meson.project_source_root()`
+and `meson.project_build_root()` have been added in Meson 0.56.0 to get the root
+of the current (sub)project.