5 files changed, 53 insertions, 3 deletions
diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md
index 0751aed..fc8cdd2 100644
--- a/docs/markdown/Commands.md
+++ b/docs/markdown/Commands.md
@@ -295,5 +295,12 @@ These variables are set in environment in addition to those set using `meson.add
 - `PATH` includes every directory where there is an executable that would be
   installed into `bindir`. On windows it also includes every directory where there
   is a DLL needed to run those executables.
+- `LD_LIBRARY_PATH` includes every directory where there is a shared library that
+  would be installed into `libdir`. This allows to run system application using
+  custom build of some libraries. For example running system GEdit when building
+  GTK from git. On OSX the environment variable is `DYLD_LIBRARY_PATH` and
+  `PATH` on Windows.
+- `GI_TYPELIB_PATH` includes every directory where a GObject Introspection
+  typelib is built. This is automatically set when using `gnome.generate_gir()`.
 
 {{ devenv_arguments.inc }}
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 6e18e68..74f3324 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -2752,8 +2752,19 @@ tests and other functions. It has the following methods.
   joined by the separator, e.g.  `env.set('FOO', 'BAR'),` sets envvar
   `FOO` to value `BAR`. See `append()` above for how separators work.
 
-**Note:** All these methods overwrite the previously-defined value(s)
-if called twice with the same `varname`.
+*Since 0.58.0* `append()` and `prepend()` methods can be called multiple times
+on the same `varname`. Earlier Meson versions would warn and only the last
+operation took effect.
+
+```meson
+env = environment()
+
+# MY_PATH will be '0:1:2:3'
+env.set('MY_PATH', '1')
+env.append('MY_PATH', '2')
+env.append('MY_PATH', '3')
+env.prepend('MY_PATH', '0')
+```
 
 ### `external library` object
 
diff --git a/docs/markdown/snippets/devenv.md b/docs/markdown/snippets/devenv.md
index c3bac10..1160945 100644
--- a/docs/markdown/snippets/devenv.md
+++ b/docs/markdown/snippets/devenv.md
@@ -26,4 +26,10 @@ These variables are set in environment in addition to those set using `meson.add
 - `PATH` includes every directory where there is an executable that would be
   installed into `bindir`. On windows it also includes every directory where there
   is a DLL needed to run those executables.
-
+- `LD_LIBRARY_PATH` includes every directory where there is a shared library that
+  would be installed into `libdir`. This allows to run system application using
+  custom build of some libraries. For example running system GEdit when building
+  GTK from git. On OSX the environment variable is `DYLD_LIBRARY_PATH` and
+  `PATH` on Windows.
+- `GI_TYPELIB_PATH` includes every directory where a GObject Introspection
+  typelib is built. This is automatically set when using `gnome.generate_gir()`.
diff --git a/docs/markdown/snippets/environment.md b/docs/markdown/snippets/environment.md
new file mode 100644
index 0000000..1ed102d
--- /dev/null
+++ b/docs/markdown/snippets/environment.md
@@ -0,0 +1,16 @@
+## Multiple append() and prepend() in `environment()` object
+
+`append()` and `prepend()` methods can now be called multiple times
+on the same `varname`. Earlier Meson versions would warn and only the last
+opperation was taking effect.
+
+```meson
+env = environment()
+
+# MY_PATH will be '0:1:2:3'
+env.set('MY_PATH', '1')
+env.append('MY_PATH', '2')
+env.append('MY_PATH', '3')
+env.prepend('MY_PATH', '0')
+```
+
diff --git a/docs/markdown/snippets/nopipe.md b/docs/markdown/snippets/nopipe.md
new file mode 100644
index 0000000..431205b
--- /dev/null
+++ b/docs/markdown/snippets/nopipe.md
@@ -0,0 +1,10 @@
+## `-pipe` no longer used by default
+
+Meson used to add the `-pipe` command line argument to all compilers
+that supported it, but no longer does. If you need this, then you can
+add it manually. However note that you should not do this unless you
+have actually measured that it provides performance improvements. In
+our tests we could not find a case where adding `-pipe` made
+compilation faster and using `-pipe` [can cause sporadic build
+failures in certain
+cases](https://github.com/mesonbuild/meson/issues/8508).