[skip ci] docs: Bring up to date on options per machine

I tried to fix the docs when the stuff was added, but it turns out I
missed things, as noted in
https://github.com/mesonbuild/meson/issues/7284#issuecomment-641641177

2 files changed, 64 insertions, 14 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index aa7d500..0fa127a 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -55,16 +55,9 @@ particularly the paths section may be necessary.
 
 ### Core options
 
-Options that are labeled "per machine" in the table are set per machine.
-Prefixing the option with `build.` just affects the build machine configuration,
-while unprefixed just affects the host machine configuration, respectively.
-Using the option as-is with no prefix affects all machines. For example:
-
- - `build.pkg_config_path` controls the paths pkg-config will search for just
-   `native: true` dependencies (build machine).
-
- - `pkg_config_path` controls the paths pkg-config will search for just
-   `native: false` dependencies (host machine).
+Options that are labeled "per machine" in the table are set per machine. See
+the [specifying options per machine](#Specifying-options-per-machine) section
+for details.
 
 | Option                               | Default value | Description                                                    | Is per machine |
 | ------                               | ------------- | -----------                                                    | -------------- |
@@ -186,9 +179,9 @@ The default values of `c_winlibs` and `cpp_winlibs` are in compiler-specific
 argument forms, but the libraries are: kernel32, user32, gdi32, winspool,
 shell32, ole32, oleaut32, uuid, comdlg32, advapi32.
 
-c_args, cpp_args, c_link_args, and cpp_link_args only affect native builds,
-when cross compiling they will not be applied to binaries or libraries
-targeting the host system, only those being run on the build system.
+All these `<lang>_*` options are specified per machine. See below in the
+[specifying options per machine](#Specifying-options-per-machine) section on
+how to do this in cross builds.
 
 When using MSVC, `cpp_eh=none` will result in no exception flags being passed,
 while the `cpp_eh=[value]` will result in `/EH[value]`.
@@ -199,3 +192,25 @@ gcc-style compilers, nothing is passed (allowing exceptions to work), while
 Since *0.54.0* The `<lang>_thread_count` option can be used to control the
 value passed to `-s PTHREAD_POOL_SIZE` when using emcc. No other c/c++
 compiler supports this option.
+
+## Specifying options per machine
+
+Since *0.51.0*, some options are specified per machine rather than globally for
+all machine configurations. Prefixing the option with `build.` just affects the
+build machine configuration, while unprefixed just affects the host machine
+configuration, respectively. For example:
+
+ - `build.pkg_config_path` controls the paths pkg-config will search for just
+   `native: true` dependencies (build machine).
+
+ - `pkg_config_path` controls the paths pkg-config will search for just
+   `native: false` dependencies (host machine).
+
+This is useful for cross builds. In the native builds, build = host, and the
+unprefixed option alone will suffice.
+
+Prior to *0.51.0*, these options just effected native builds when specified on
+the command line, as there was no `build.` prefix. Similarly named fields in
+the `[properties]` section of the cross file would effect cross compilers, but
+the code paths were fairly different allowing differences in behavior to crop
+out.
diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md
index 60a9720..81ce921 100644
--- a/docs/markdown/Reference-tables.md
+++ b/docs/markdown/Reference-tables.md
@@ -155,6 +155,10 @@ These are the parameter names for passing language specific arguments to your bu
 | Rust          | rust_args     | rust_link_args    |
 | Vala          | vala_args     | vala_link_args    |
 
+All these `<lang>_*` options are specified per machine. See in [specifying
+options per machine](Builtin-options.md#Specifying-options-per-machine) for on
+how to do this in cross builds.
+
 ## Compiler and linker flag environment variables
 
 These environment variables will be used to modify the compiler and
@@ -177,6 +181,10 @@ instead.
 | RUSTFLAGS | Flags for the Rust compiler              |
 | LDFLAGS   | The linker flags, used for all languages |
 
+N.B. these settings are specified per machine, and so the environment varibles
+actually come in pairs. See the [environment variables per
+machine](#Environment-variables-per-machine) section for details.
+
 ## Function Attributes
 
 These are the parameters names that are supported using
@@ -267,6 +275,10 @@ These are the values that can be passed to `dependency` function's
 
 ## Compiler and Linker selection variables
 
+N.B. these settings are specified per machine, and so the environment varibles
+actually come in pairs. See the [environment variables per
+machine](#Environment-variables-per-machine) section for details.
+
 | Language      | Compiler | Linker    | Note                                        |
 |---------------|----------|-----------|---------------------------------------------|
 | C             | CC       | CC_LD     |                                             |
@@ -280,5 +292,28 @@ These are the values that can be passed to `dependency` function's
 | C#            | CSC      | CSC       | The linker is the compiler                  |
 
 *The old environment variales are still supported, but are deprecated and will
-be removed in a future version of meson.
+be removed in a future version of meson.*
+
+## Environment variables per machine
+
+Since *0.54.0*, Following Autotool and other legacy build systems, environment
+variables that affect machine-specific settings come in pairs: for every bare
+environment variable `FOO`, there is a suffixed `FOO_FOR_BUILD`, where `FOO`
+just affects the host machine configuration, while `FOO_FOR_BUILD` just affects
+the build machine configuration. For example:
+
+ - `PKG_CONFIG_PATH_FOR_BUILD` controls the paths pkg-config will search for
+   just `native: true` dependencies (build machine).
+
+ - `PKG_CONFIG_PATH` controls the paths pkg-config will search for just
+   `native: false` dependencies (host machine).
+
+This mirrors the `build.` prefix used for (built-in) meson options, which has
+the same meaning.
+
+This is useful for cross builds. In the native builds, build = host, and the
+unsuffixed environment variables alone will suffice.
 
+Prior to *0.54.0*, there was no `_FOR_BUILD`-suffixed variables, and most
+environment variables only effected native machine configurations, though this
+wasn't consistent (e.g. `PKG_CONFIG_PATH` still affected cross builds).