tools: enhance description for the nm-settings manual page

1 files changed, 28 insertions, 13 deletions

diff --git a/tools/generate-settings-spec.c b/tools/generate-settings-spec.c
index 3e2d6df90e..3ba370fa3a 100644
--- a/tools/generate-settings-spec.c
+++ b/tools/generate-settings-spec.c
@@ -261,20 +261,23 @@ writer_header_docbook_manpage (FILE *f)
 		"  </refmeta>\n"
 		"  <refnamediv>\n"
 		"    <refname>nm-settings</refname>\n"
-		"    <refpurpose>Description of settings and parameters of NetworkManager connections.</refpurpose>\n"
+		"    <refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose>\n"
 		"  </refnamediv>\n"
 		"  <refsect1>\n"
 		"    <title>DESCRIPTION</title>\n"
 		"    <para>\n"
-		"      NetworkManager is based on a concept of connections. These connections are\n"
-		"      then applied to a device to make an active network connection. Users can create\n"
-		"      as many connections as they see fit. The connections are handled by NetworkManager\n"
-		"      via <emphasis>settings service</emphasis> and are exported on D-Bus \n"
+		"      NetworkManager is based on a concept of connection profiles, sometimes referred to as\n"
+		"      connections only. These connection profiles contain a network configuration. When\n"
+		"      NetworkManager activates a connection profile on a network device the configuration will\n"
+		"      be applied and an active network connection will be established. Users are free to create\n"
+		"      as many connection profiles as they see fit. Thus they are flexible in having various network\n"
+		"      configurations for different networking needs. The connection profiles are handled by\n"
+		"      NetworkManager via <emphasis>settings service</emphasis> and are exported on D-Bus\n"
 		"      (<emphasis>/org/freedesktop/NetworkManager/Settings/&lt;num&gt;</emphasis> objects).\n"
 		"      The conceptual objects can be described as follows:\n"
 		"      <variablelist>\n"
 		"        <varlistentry>\n"
-		"          <term>Connection</term>\n"
+		"          <term>Connection (profile)</term>\n"
 		"          <listitem>\n"
 		"            <para>\n"
 		"              A specific, encapsulated, independent group of settings describing\n"
@@ -285,7 +288,7 @@ writer_header_docbook_manpage (FILE *f)
 		"              objects.\n"
 		"            </para>\n"
 		"          </listitem>\n"
-		"      </varlistentry>\n"
+		"        </varlistentry>\n"
 		"      </variablelist>\n"
 		"      <variablelist>\n"
 		"        <varlistentry>\n"
@@ -293,13 +296,25 @@ writer_header_docbook_manpage (FILE *f)
 		"          <listitem>\n"
 		"            <para>\n"
 		"              A group of related key/value pairs describing a specific piece of a\n"
-		"              <emphasis>Connection</emphasis>. Settings keys and allowed values are\n"
-		"              described in the tables below. Developers can find the settings\n"
-		"              objects in the libnm-util sources. Look for the <function>class_init</function>\n"
-		"              functions near the bottoms of each setting source file.\n"
+		"              <emphasis>Connection (profile)</emphasis>. Settings keys and allowed values are\n"
+		"              described in the tables below. Keys are also reffered to as properties.\n"
+		"              Developers can find the setting objects and their properties in the libnm-util\n"
+		"              sources. Look for the <function>class_init</function> functions near the bottom of\n"
+		"              each setting source file.\n"
 		"            </para>\n"
 		"          </listitem>\n"
-		"      </varlistentry>\n"
+		"        </varlistentry>\n"
+		"      </variablelist>\n"
+		"      <variablelist>\n"
+		"        <para>\n"
+		"          The settings and properties shown in tables below list all available connection\n"
+		"          configuration options. However, note that not all settings are applicable to all\n"
+		"          connection types. NetworkManager provides a command-line tool <emphasis>nmcli</emphasis>\n"
+		"          that allows direct configuration of the settings and properties according to a connection\n"
+		"          profile type. <emphasis>nmcli</emphasis> connection editor has also a built-in\n"
+		"          <emphasis>describe</emphasis> command that can display description of particular settings\n"
+		"          and properties of this page.\n"
+		"        </para>\n"
 		"      </variablelist>\n",
 		time_str, VERSION);
 }
@@ -352,7 +367,7 @@ writer_footer_docbook_manpage (FILE *f)
 		"  <refsect1>\n"
 		"    <title>SEE ALSO</title>\n"
 		"    <para>https://live.gnome.org/NetworkManagerConfiguration</para>\n"
-		"    <para>NetworkManager(8), nmcli(1), NetworkManager.conf(5)</para>\n"
+		"    <para>NetworkManager(8), nmcli(1), nmcli-examples(5), NetworkManager.conf(5)</para>\n"
 		"  </refsect1>\n"
 		"</refentry>\n");
 }