[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: feat: support organising cloned source directories according to the 'layout' of repositories on invent.kde.org

[Johan Ouwerkerk]

Git commit 74b141e309a6e65f0b35f3c4cda5965b90c626d9 by Johan Ouwerkerk.
Committed on 23/12/2020 at 18:01.
Pushed by ashark into branch 'docbook_historied_per_file'.

feat: support organising cloned source directories according to the 'layout' of repositories on invent.kde.org

Issues: #59

Original commit: 6c17bceb
https://invent.kde.org/sdk/kdesrc-build/-/commit/6c17bceb1f4e890fa588f0814843a8b8da955027

M  +35   -8    doc/kdesrc-buildrc/conf-options-table.docbook

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

diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index 699ef4e4..7567f440 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -568,15 +568,42 @@ on also use that proxy server, if possible, by setting the
 <row id="conf-ignore-kde-structure">
 <entry>ignore-kde-structure</entry>
 <entry>Module setting overrides global</entry>
-<entry><para>This option is used to store the source and the build files directly
-in the name of the module. For example,
-<literal>source/extragear/network/telepathy/ktp-text-ui</literal>
-becomes
-<literal>source/ktp-text-ui</literal>.
-This option is disabled by default. If you want to enable this option you need to set it
-to <userinput>true</userinput>.</para>
+<entry>
+<para>This option is deprecated and will be removed (again) in a future release.</para>
 
-<para>This option was introduced with &kdesrc-build; 1.16.</para>
+<para>Please use <option><link linkend="conf-directory-layout">directory-layout</link></option>
+instead, which offers more options.</para>
+</entry>
+</row>
+
+<row id="conf-directory-layout">
+<entry>directory-layout</entry>
+<entry>Module setting overrides global</entry>
+<entry><para>This option is used to configure the layout which &kdesrc-build; should use when
+creating source and build directories.</para>
+<para>Currently, there are three possible values: <userinput>metadata</userinput>,
+<userinput>invent</userinput> and <userinput>flat</userinput></para>
+<para>The <userinput>flat</userinput> layout will group all modules directly underneath the top level
+source and build directories. For example,
+<literal>source/extragear/network/telepathy/ktp-text-ui</literal> in the <userinput>metadata</userinput>
+layout would be <literal>source/ktp-text-ui</literal> using the <userinput>flat</userinput> layout
+instead.
+</para>
+<para>The <userinput>invent</userinput> layout creates a directory hierarchy mirroring the relative
+paths of repositories on <ulink url="https://invent.kde.org/">invent.kde.org</ulink>. For example
+<literal>source/kde/applications/kate</literal> in the <userinput>metadata</userinput> layout would
+be <literal>source/utilities/kate</literal> using the <userinput>invent</userinput> layout instead.
+This layout only affects KDE projects. It is a good choice for people starting out with
+&kdesrc-build;.
+</para>
+<para>Finally, the <userinput>metadata</userinput> layout is the same as the old default
+behaviour. This layout organises KDE projects according to the project paths specified in the
+project metadata for these modules. This is a good choice if you want a directory layout which
+tracks with certain KDE processes, but note that this path is therefore not always stable. As a
+result, &kdesrc-build; may abandon an old copy of the repository and clone a new one for a project
+due to changes in the project metadata.</para>
+<para>By default the <userinput>metadata</userinput> layout will be used, to preserve backwards
+compatibility for existing users of &kdesrc-build;.</para>
 </entry>
 </row>