[sdk/kdesrc-build/docbook_historied_per_file] doc: Improve first-run behavior with build metadata.

[Michael Pyne]

Git commit fab78b389048faff2db425e3e942da01403c74c0 by Michael Pyne.
Committed on 16/07/2014 at 05:00.
Pushed by ashark into branch 'docbook_historied_per_file'.

Improve first-run behavior with build metadata.

This commit makes the kde-build-metadata module a requirement instead of
an option, since the vast majority of runs will require this module now.

Additionally the --metadata-only option is added and documented to allow
for downloading the kde-build-metadata module alone (and make the
--pretend option work afterwards), and kdesrc-build recommends using it
if you run with --pretend and without metadata.

This should hopefully make the first-run use case easier for users.

BUG:337446
FIXED-IN:1.16

Original commit: 6911da5c
https://invent.kde.org/sdk/kdesrc-build/-/commit/6911da5c8713c3e33e8e43c6707a2c871bf79375

M  +24   -3    doc/cmdline/supported-cmdline-params.docbook
M  +5    -1    doc/features/features-overview.docbook

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

diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index 3e85994f..445e52b0 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -82,10 +82,19 @@ performing any actions to update or build, will instead output what the
 script would have done (e.g. what commands to run, general steps being taken,
 etc.).</para>
 
-<para>Note: Simple read-only commands (such as reading file information) may
+<note><para>Simple read-only commands (such as reading file information) may
 still be run to make the output more relevant (such as correctly simulating
 whether source code would be checked out or updated).
-</para></listitem>
+</para></note>
+
+<important><para>This option requires that some needed metadata is available,
+which is normally automatically downloaded, but downloads are disabled in
+pretend mode. If you've never run &kdesrc-build; (and therefore, don't have
+this metadata), you should run <command>kdesrc-build
+<option>--metadata-only</option></command> to download the required metadata
+first.
+</para></important>
+</listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-quiet">
@@ -132,6 +141,15 @@ Only perform the install process.
 </para></listitem>
 </varlistentry>
 
+<varlistentry id="cmdline-metadata-only">
+<term><parameter>--metadata-only</parameter></term>
+<listitem><para>
+Only perform the metadata download process. &kdesrc-build; normally handles this
+automatically, but you might manually use this to allow the <option><link
+linkend="cmdline-pretend">--pretend</link></option> command line option to work.
+</para></listitem>
+</varlistentry>
+
 <varlistentry id="cmdline-ignore-modules">
 <term><parameter>--ignore-modules</parameter></term>
 <listitem><para>
@@ -166,7 +184,10 @@ The source updates for the modules themselves will still occur unless you pass
 <link linkend="cmdline-no-src">--no-src</link> as well.
 </para><para>
 This can be useful if you are frequently re-running &kdesrc-build; since the
-metadata does not change very often.
+metadata does not change very often. But note that many other features require
+the metadata to be available. You might want to consider running &kdesrc-build;
+with the <link linkend="cmdline-metadata-only">--metadata-only</link> option
+one time and then using this option for subsequent runs.
 </para></listitem>
 </varlistentry>
 
diff --git a/doc/features/features-overview.docbook b/doc/features/features-overview.docbook
index a167148f..7013a51c 100644
--- a/doc/features/features-overview.docbook
+++ b/doc/features/features-overview.docbook
@@ -11,7 +11,11 @@
 You can <quote>pretend</quote> to do the operations. If you pass
 <option>--pretend</option> or <option>-p</option> on the
 command line, the script will give a verbose description of the commands
-it is about to execute, without actually executing it.
+it is about to execute, without actually executing it. However if you've never
+run &kdesrc-build;, you would want to run the <command>kdesrc-build
+<option><link
+linkend="cmdline-metadata-only">--metadata-only</link></option></command>
+command first in order for <option>--pretend</option> to work.
 
 <tip><para>For an even more verbose description of what &kdesrc-build; is
 doing, try using the <option>--debug</option> option.