[gtkmm-documentation/wip/dboles/formatting-3: 2/10] Elaborate the section on pkg-config and API names

[Daniel Boles <dboles src gnome org>]

commit d9b0fa8d10fe5840827258988b9f7fffc4aa243e
Author: Daniel Boles <dboles src gmail com>
Date:   Mon Jan 15 21:43:27 2018 +0000

    Elaborate the section on pkg-config and API names
    
    Reorganise/reword this, explain the pkg-config mantras, identify 3.22 as
    the LTS, and update for how gtkmm-4.0 exists nowadays, albeit unstably.

 docs/tutorial/C/index-in.docbook |   38 +++++++++++++++++++++++++++++++-------
 1 files changed, 31 insertions(+), 7 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index ff4c34c..531b6e2 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -362,11 +362,21 @@ Your <function>main()</function> function will then return with an appropriate s
 After putting the source code in <filename>simple.cc</filename>, you can compile
 the above program with <application>GCC</application> using:
 <programlisting>g++ simple.cc -o simple `pkg-config gtkmm-3.0 --cflags --libs`</programlisting>
-Note that you must surround the <literal>pkg-config</literal> invocation with backquotes.
-Backquotes cause the shell to execute the command inside them, and to use
-the command's output as part of the command line.
-Note also that <literal>simple.cc</literal> must come before the <literal>pkg-config</literal>
-invocation on the command line.
+</para>
+<para>
+Some details here are important to note: You must surround the
+<command>pkg-config</command> invocation with backquotes, as those cause the
+shell to execute the command inside them and to use the command's output as
+part of the command line, i.e. to substitute the command with the switches it
+returns that your compiler needs in order to find &gtkmm;'s headers and symbols.
+Filenames, like <filename>simple.cc</filename>, must come before the
+<command>pkg-config</command> invocation on the command line, as most linkers
+work through their command-line arguments in the order given, and they must
+first process your sources in order to know which symbols they need in the
+following libraries returned by <command>pkg-config</command>. Finally, if you
+mention extra modules in addition to <application>gtkmm-3.0</application>, they
+should be separated by spaces, not commas, as <command>pkg-config</command> uses
+space-separated lists.
 </para>
 </sect1>
 
@@ -397,9 +407,23 @@ For instance:
 <programlisting>PKG_CHECK_MODULES([MYAPP], [gtkmm-3.0 >= 3.8.0])</programlisting>
 This checks for the presence of gtkmm and defines MYAPP_LIBS and MYAPP_CFLAGS for use in your Makefile.am 
files.
 </para>
-<para>gtkmm-3.0 is the name of the current stable API. There was an older API called gtkmm-2-4 which 
installs in parallel when it is available. There were several versions of gtkmm-2.4, such as gtkmm 2.10 and 
there are several versions of the gtkmm-3.0 API. Note that the API name does not change for every version 
because that would be an incompatible API and ABI break. Theoretically, there might be a future gtkmm-4.0 API 
which would install in parallel with gtkmm-3.0 without affecting existing applications.
-</para>
-<para>Note that if you mention extra modules in addition to gtkmm-3.0, they should be separated by spaces, 
not commas.
+<para><application>gtkmm-3.0</application> is the name of the current stable
+API. There was an older API called <application>gtkmm-2.4</application>. There
+is also now the newer unstable development API
+<application>gtkmm-4.0</application>, though this is in a high state of flux at
+the time of writing and so is only for users who want to try out the latest
+features and accepting the risk of their code breaking later. All three of
+these major API versions can be installed in parallel without affecting each
+other or applications that compile against different API versions.
+</para>
+<para>There were several versions of <application>gtkmm-2.4</application> such
+as &gtkmm; 2.10, there are several versions of
+<application>gtkmm-3.0</application>, and there will most likely be several
+versions of <application>gtkmm-4.0</application> too.  You can see that, while
+the actual minor version increases, the API name does not change for every
+version because that would be an incompatible API and ABI break.
+</para>
+<para>The current long-term stable version of both GTK+ and &gtkmm; is 3.22.
 </para>
 
 <para>The GNU site has more information about <ulink 
url="https://www.gnu.org/software/autoconf/";>autoconf</ulink>