[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: Check that all option names read from config are recognised

[Andrew Shark]

Git commit cafef6c2228c7f489ce18cc80da5008a796f0b97 by Andrew Shark.
Committed on 10/01/2024 at 09:26.
Pushed by ashark into branch 'docbook_historied_per_file'.

Check that all option names read from config are recognised

For every option name read from the config, we will check if it is in `@all_possible_options` array. And if not, raise an exception.

To differentiate between normal config options and non-standard config options (options with custom name defined by user), we will prepend non-standard options with underscore. So users can still use this convenience feature.

Other changes of this commit:
- Allow substituting references to global options when they have underscore in their name.
- Add ability to _use_ custom variable immediately after defining in global section
- Fix end word typo in `t/data/kde-projects/kdesrc-buildrc-with-deps`.
- Temporary show a help message for the recently renamed option "kdedir".

Original commit: f99141ca
https://invent.kde.org/sdk/kdesrc-build/-/commit/f99141cadf12bbb7221ddc88ea6ce3e208b492df

M  +19   -1    doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/cafef6c2228c7f489ce18cc80da5008a796f0b97

diff --git a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
index d5c7e1e7..adebe815 100644
--- a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
+++ b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
@@ -92,7 +92,7 @@ linkend="conf-use-modules">use-modules</link> for more information.
 <replaceable>option-value</replaceable>.</para>
 
 <para>One modification that &kdesrc-build; performs is that a sequence
-<userinput>${<replaceable>name-of-option</replaceable>}</userinput> is replaced
+"<userinput>${<replaceable>name-of-option</replaceable>}</userinput>" is replaced
 with the value of that option from the global configuration. This allows you
 to reference the value of existing options, including options already set by
 &kdesrc-build;.</para>
@@ -101,6 +101,24 @@ to reference the value of existing options, including options already set by
 To see an example of this in use, see
 <xref linkend="make-options-example"/>.</para>
 
+<para>You can also introduce your own non-standard global variables for referencing them further in the config.
+To do this, your option name should be prepended with underscore symbol. Example:
+<example id="custom-global-option-example">
+<title>Introducing your own global option for referencing later in config</title>
+<programlisting>
+global
+  _ver 6  # ← your custom variable (starting with underscore)
+  _kde ~/kde${_ver}  # ← custom variable can contain another defined variable
+  source-dir ${_kde}/src  # ← note that nested variable (_kde → _ver) is also resolved
+end global
+
+options kdepim
+  log-dir /custom/path/logs${_ver} # ← you can use custom variable just like a standard
+end options
+</programlisting>
+</example>
+</para>
+
 </sect3>
 
 <sect3 id="kdesrc-buildrc-options-groups">