docs: add more nm-settings manpages (dbus,nmcli,keyfile,ifcfg-rh)

A significant part of NetworkManager's API are the connection profiles, documented
in `man nm-settings*`. But there are different aspects about profiles, depending
on what you are interested. There is the D-Bus API, nmcli options, keyfile format,
and ifcfg-rh format. Additionally, there is also libnm API.

Add distinct manual pages for the four aspects. Currently the two new manual
pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the
former "nm-settings.5" manual. In the future, they will diverge to
account for the differences.

There are the following aspects:

 - "dbus"
 - "keyfile"
 - "ifcfg-rh"
 - "nmcli"

For "libnm" we don't generate a separate "nm-settings-libnm" manual
page. That is instead documented via gtk-doc.

Currently the keyfile and ifcfg-rh manual pages only detail settings
which differ. But later I think also these manual pages should contain
all settings that apply.

3 files changed, 172 insertions, 6 deletions

diff --git a/man/meson.build b/man/meson.build
index 7d9de1ffe9..8e1150833f 100644
--- a/man/meson.build
+++ b/man/meson.build
@@ -58,7 +58,8 @@ endforeach
 if enable_introspection
   mans = [
     ['nm-settings-keyfile', '5', nm_property_infos_xml['keyfile']],
-    ['nm-settings',         '5', nm_settings_docs_xml['dbus']],
+    ['nm-settings-dbus',    '5', nm_settings_docs_xml['dbus']],
+    ['nm-settings-nmcli',   '5', nm_settings_docs_xml['nmcli']],
   ]
 
   if enable_ifcfg_rh
diff --git a/man/nm-settings.xsl b/man/nm-settings-dbus.xsl
index 57d5ce41cf..0573d0d3b8 100644
--- a/man/nm-settings.xsl
+++ b/man/nm-settings-dbus.xsl
@@ -13,20 +13,20 @@
       />
 
   <xsl:template match="nm-setting-docs">
-    <refentry id="nm-settings">
+    <refentry id="nm-settings-dbus">
       <refentryinfo>
-        <title>nm-settings</title>
+        <title>nm-settings-dbus</title>
         <author>NetworkManager developers</author>
       </refentryinfo>
       <refmeta>
-        <refentrytitle>nm-settings</refentrytitle>
+        <refentrytitle>nm-settings-dbus</refentrytitle>
         <manvolnum>5</manvolnum>
         <refmiscinfo class="source">NetworkManager</refmiscinfo>
         <refmiscinfo class="manual">Configuration</refmiscinfo>
         <refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
       </refmeta>
       <refnamediv>
-        <refname>nm-settings</refname>
+        <refname>nm-settings-dbus</refname>
         <refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose>
       </refnamediv>
 
@@ -155,7 +155,7 @@
   <xsl:template match="property">
     <xsl:variable name="setting_name" select="../@name"/>
     <row>
-      <entry align="left"><xsl:attribute name="id">nm-settings.property.<xsl:value-of select="../@name"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></entry>
+      <entry align="left"><xsl:attribute name="id">nm-settings-dbus.property.<xsl:value-of select="../@name"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></entry>
       <entry align="left"><xsl:value-of select="@type"/></entry>
       <entry align="left"><xsl:value-of select="@default"/></entry>
       <entry><xsl:value-of select="@description"/><xsl:if test="@type = 'NMSettingSecretFlags (uint32)'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if></entry>
diff --git a/man/nm-settings-nmcli.xsl b/man/nm-settings-nmcli.xsl
new file mode 100644
index 0000000000..28e7504931
--- /dev/null
+++ b/man/nm-settings-nmcli.xsl
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE stylesheet [
+<!ENTITY % entities SYSTEM "common.ent" >
+%entities;
+]>
+<xsl:stylesheet version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+  <xsl:output
+      method="xml"
+      doctype-public="-//OASIS//DTD DocBook XML V4.3//EN"
+      doctype-system="http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+      />
+
+  <xsl:template match="nm-setting-docs">
+    <refentry id="nm-settings-nmcli">
+      <refentryinfo>
+        <title>nm-settings-nmcli</title>
+        <author>NetworkManager developers</author>
+      </refentryinfo>
+      <refmeta>
+        <refentrytitle>nm-settings-nmcli</refentrytitle>
+        <manvolnum>5</manvolnum>
+        <refmiscinfo class="source">NetworkManager</refmiscinfo>
+        <refmiscinfo class="manual">Configuration</refmiscinfo>
+        <refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
+      </refmeta>
+      <refnamediv>
+        <refname>nm-settings-nmcli</refname>
+        <refpurpose>Description of settings and properties of NetworkManager connection profiles</refpurpose>
+      </refnamediv>
+
+      <refsect1 id='description'><title>Description</title>
+        <para>
+          NetworkManager is based on a concept of connection profiles, sometimes referred to as
+          connections only. These connection profiles contain a network configuration. When
+          NetworkManager activates a connection profile on a network device the configuration will
+          be applied and an active network connection will be established. Users are free to create
+          as many connection profiles as they see fit. Thus they are flexible in having various network
+          configurations for different networking needs. The connection profiles are handled by
+          NetworkManager via <emphasis>settings service</emphasis> and are exported on D-Bus
+          (<emphasis>/org/freedesktop/NetworkManager/Settings/&lt;num&gt;</emphasis> objects).
+          The conceptual objects can be described as follows:
+          <variablelist>
+            <varlistentry>
+              <term>Connection (profile)</term>
+              <listitem>
+                <para>
+                  A specific, encapsulated, independent group of settings describing
+                  all the configuration required to connect to a specific network.
+                  It is referred to by a unique identifier called the UUID. A connection
+                  is tied to a one specific device type, but not necessarily a specific
+                  hardware device. It is composed of one or more <emphasis>Settings</emphasis>
+                  objects.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+          <variablelist>
+            <varlistentry>
+              <term>Setting</term>
+              <listitem>
+                <para>
+                  A group of related key/value pairs describing a specific piece of a
+                  <emphasis>Connection (profile)</emphasis>. Settings keys and allowed values are
+                  described in the tables below. Keys are also referred to as properties.
+                  Developers can find the setting objects and their properties in the libnm-core
+                  sources. Look for the <function>*_class_init</function> functions near the bottom
+                  of each setting source file.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+          <variablelist>
+            <para>
+              The settings and properties shown in tables below list all available connection
+              configuration options. However, note that not all settings are applicable to all
+              connection types. NetworkManager provides a command-line tool <emphasis>nmcli</emphasis>
+              that allows direct configuration of the settings and properties according to a connection
+              profile type. <emphasis>nmcli</emphasis> connection editor has also a built-in
+              <emphasis>describe</emphasis> command that can display description of particular settings
+              and properties of this page.
+            </para>
+          </variablelist>
+        </para>
+        <xsl:apply-templates/>
+        <refsect2 id="secrets-flags">
+          <title>Secret flag types:</title>
+          <para>
+            Each password or secret property in a setting has an associated <emphasis>flags</emphasis> property
+            that describes how to handle that secret. The <emphasis>flags</emphasis> property is a bitfield
+            that contains zero or more of the following values logically OR-ed together.
+          </para>
+          <itemizedlist>
+            <listitem>
+              <para>0x0 (none) - the system is responsible for providing and storing this secret. This
+              may be required so that secrets are already available before the user logs in.
+              It also commonly means that the secret will be stored in plain text on disk, accessible
+              to root only. For example via the keyfile settings plugin as described in the "PLUGINS" section
+              in <link linkend='NetworkManager.conf'><citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>.
+              </para>
+            </listitem>
+            <listitem>
+              <para>0x1 (agent-owned) - a user-session secret agent is responsible for providing and storing
+              this secret; when it is required, agents will be asked to provide it.</para>
+            </listitem>
+            <listitem>
+              <para>0x2 (not-saved) - this secret should not be saved but should be requested from the user
+              each time it is required. This flag should be used for One-Time-Pad secrets, PIN codes from hardware tokens,
+              or if the user simply does not want to save the secret.</para>
+            </listitem>
+            <listitem>
+              <para>0x4 (not-required) - in some situations it cannot be automatically determined that a secret
+              is required or not. This flag hints that the secret is not required and should not be requested from the user.</para>
+            </listitem>
+          </itemizedlist>
+        </refsect2>
+      </refsect1>
+
+      <refsect1 id='files'><title>Files</title>
+        <para><filename>/etc/NetworkManager/system-connections</filename> or distro plugin-specific location</para>
+      </refsect1>
+
+      <refsect1 id='see_also'><title>See Also</title>
+        <para><link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
+        <link linkend='nmcli'><citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
+        <link linkend='nmcli-examples'><citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>7</manvolnum></citerefentry></link>,
+        <link linkend='NetworkManager.conf'><citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></link></para>
+      </refsect1>
+    </refentry>
+  </xsl:template>
+
+  <xsl:template match="setting">
+    <refsect2>
+      <title><xsl:value-of select="@name"/> setting</title>
+      <para><xsl:value-of select="@description"/>.</para>
+      <informaltable>
+        <tgroup cols="4">
+          <thead>
+            <row>
+              <entry>Key Name</entry>
+              <entry>Value Type</entry>
+              <entry>Default Value</entry>
+              <entry>Value Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <xsl:apply-templates/>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </refsect2>
+  </xsl:template>
+
+  <xsl:template match="property">
+    <xsl:variable name="setting_name" select="../@name"/>
+    <row>
+      <entry align="left"><xsl:attribute name="id">nm-settings-nmcli.property.<xsl:value-of select="../@name"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></entry>
+      <entry align="left"><xsl:value-of select="@type"/></entry>
+      <entry align="left"><xsl:value-of select="@default"/></entry>
+      <entry><xsl:value-of select="@description"/><xsl:if test="@type = 'NMSettingSecretFlags (uint32)'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if></entry>
+    </row>
+  </xsl:template>
+
+</xsl:stylesheet>