4 files changed, 114 insertions, 1 deletions
diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md
index d724b75..143cdcb 100644
--- a/docs/markdown/Contributing.md
+++ b/docs/markdown/Contributing.md
@@ -200,7 +200,7 @@ following:
   to avoid wasted effort
 
 Meson uses Flake8 for style guide enforcement. The Flake8 options for
-the project are contained in setup.cfg.
+the project are contained in .flake8.
 
 To run Flake8 on your local clone of Meson:
 
diff --git a/docs/markdown/FAQ.md b/docs/markdown/FAQ.md
index e5b7a9c..06379ae 100644
--- a/docs/markdown/FAQ.md
+++ b/docs/markdown/FAQ.md
@@ -402,3 +402,90 @@ the form `foo.lib` when building with MSVC, you can set the
 kwarg to `''` and the [`name_suffix:`](https://mesonbuild.com/Reference-manual.html#library)
 kwarg to `'lib'`. To get the default behaviour for each, you can either not
 specify the kwarg, or pass `[]` (an empty array) to it.
+
+## Do I need to add my headers to the sources list like in Autotools?
+
+Autotools requires you to add private and public headers to the sources list so
+that it knows what files to include in the tarball generated by `make dist`.
+Meson's `dist` command simply gathers everything committed to your git/hg
+repository and adds it to the tarball, so adding headers to the sources list is
+pointless.
+
+Meson uses Ninja which uses compiler dependency information to automatically
+figure out dependencies between C sources and headers, so it will rebuild
+things correctly when a header changes.
+
+The only exception to this are generated headers, for which you must [declare
+dependencies correctly](#how-do-i-tell-meson-that-my-sources-use-generated-headers).
+
+If, for whatever reason, you do add non-generated headers to the sources list
+of a target, Meson will simply ignore them.
+
+## How do I tell Meson that my sources use generated headers?
+
+Let's say you use a [`custom_target()`](https://mesonbuild.com/Reference-manual.html#custom_target)
+to generate the headers, and then `#include` them in your C code. Here's how
+you ensure that Meson generates the headers before trying to compile any
+sources in the build target:
+
+```meson
+libfoo_gen_headers = custom_target('gen-headers', ..., output: 'foo-gen.h')
+libfoo_sources = files('foo-utils.c', 'foo-lib.c')
+# Add generated headers to the list of sources for the build target
+libfoo = library('foo', sources: libfoo_sources + libfoo_gen_headers)
+```
+
+Now let's say you have a new target that links to `libfoo`:
+
+```meson
+libbar_sources = files('bar-lib.c')
+libbar = library('bar', sources: libbar_sources, link_with: libfoo)
+```
+
+This adds a **link-time** dependency between the two targets, but note that the
+sources of the targets have **no compile-time** dependencies and can be built
+in any order; which improves parallelism and speeds up builds.
+
+If the sources in `libbar` *also* use `foo-gen.h`, that's a *compile-time*
+dependency, and you'll have to add `libfoo_gen_headers` to `sources:` for
+`libbar` too:
+
+```meson
+libbar_sources = files('bar-lib.c')
+libbar = library('bar', sources: libbar_sources + libfoo_gen_headers, link_with: libfoo)
+```
+
+Alternatively, if you have multiple libraries with sources that link to
+a library and also use its generated headers, this code is equivalent to above:
+
+```meson
+# Add generated headers to the list of sources for the build target
+libfoo = library('foo', sources: libfoo_sources + libfoo_gen_headers)
+
+# Declare a dependency that will add the generated headers to sources
+libfoo_dep = declare_dependency(link_with: libfoo, sources: libfoo_gen_headers)
+
+...
+
+libbar = library('bar', sources: libbar_sources, dependencies: libfoo_dep)
+```
+
+**Note:** You should only add *headers* to `sources:` while declaring
+a dependency. If your custom target outputs both sources and headers, you can
+use the subscript notation to get only the header(s):
+
+```meson
+libfoo_gen_sources = custom_target('gen-headers', ..., output: ['foo-gen.h', 'foo-gen.c'])
+libfoo_gen_headers = libfoo_gen_sources[0]
+
+# Add static and generated sources to the target
+libfoo = library('foo', sources: libfoo_sources + libfoo_gen_sources)
+
+# Declare a dependency that will add the generated *headers* to sources
+libfoo_dep = declare_dependency(link_with: libfoo, sources: libfoo_gen_headers)
+...
+libbar = library('bar', sources: libbar_sources, dependencies: libfoo_dep)
+```
+
+A good example of a generator that outputs both sources and headers is
+[`gnome.mkenums()`](https://mesonbuild.com/Gnome-module.html#gnomemkenums).
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 3793ce3..195c451 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -119,6 +119,20 @@ Note that all these options are also available while running the
 `meson test` script for running tests instead of `ninja test` or
 `msbuild RUN_TESTS.vcxproj`, etc depending on the backend.
 
+### alias_target
+
+``` meson
+runtarget alias_target(target_name, dep1, ...)
+```
+
+Since *0.52.0*
+
+This function creates a new top-level target. Like all top-level targets, this
+integrates with the selected backend. For instance, with Ninja you can
+run it as `ninja target_name`. This is a dummy target that does not execute any
+command, but ensures that all dependencies are built. Dependencies can be any
+build target (e.g. return value of executable(), custom_target(), etc)
+
 ### assert()
 
 ``` meson
diff --git a/docs/markdown/snippets/alias_target.md b/docs/markdown/snippets/alias_target.md
new file mode 100644
index 0000000..129730d
--- /dev/null
+++ b/docs/markdown/snippets/alias_target.md
@@ -0,0 +1,12 @@
+## alias_target
+
+``` meson
+runtarget alias_target(target_name, dep1, ...)
+```
+
+This function creates a new top-level target. Like all top-level targets, this
+integrates with the selected backend. For instance, with Ninja you can
+run it as `ninja target_name`. This is a dummy target that does not execute any
+command, but ensures that all dependencies are built. Dependencies can be any
+build target (e.g. return value of executable(), custom_target(), etc)
+