New upstream version 1.8.0 upstream/1.8.0

1 files changed, 171 insertions, 69 deletions

diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml
index 45164ce0..dd5f0e47 100644
--- a/docs/api/network-manager-docs.xml
+++ b/docs/api/network-manager-docs.xml
@@ -6,7 +6,11 @@
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
     <title>NetworkManager Reference Manual</title>
-    <releaseinfo>Version &version;</releaseinfo>
+    <releaseinfo>
+      for NetworkManager &version;
+      The latest version of this documentation can be found on-line at
+      <ulink url="https://developer.gnome.org/NetworkManager/stable/">https://developer.gnome.org/NetworkManager/stable/</ulink>.
+    </releaseinfo>
 
     <copyright>
       <year>2012</year>
@@ -14,6 +18,7 @@
       <year>2014</year>
       <year>2015</year>
       <year>2016</year>
+      <year>2017</year>
       <holder>The NetworkManager Authors</holder>
     </copyright>
 
@@ -38,78 +43,42 @@
 	</address>
       </para>
     </legalnotice>
+
+    <abstract>
+      <para>
+        This manual is the reference documentation for NetworkManager, the standard
+        Linux network management service. It is intended for system administrators and
+        integrators who need to understand the capabilities of NetworkManager, its
+        configuration options, command line tools and the D-Bus API for programmatic
+        control of the service.
+      </para>
+      <para>
+        The end users NetworkManager should instead refer to respective documentation
+        of their desktop environment of choice.
+      </para>
+      <para>
+        The application developers who prefer not to use the D-Bus API directly can use the
+        <ulink url="https://developer.gnome.org/libnm/stable/">libnm</ulink> library
+        shipped with NetworkManager or its bindings to a higher level language such as
+        Python, Ruby or Vala via GObject introspection.
+      </para>
+    </abstract>
   </bookinfo>
 
-  <chapter id="manpages">
+  <part id="manpages">
     <title>Manual Pages</title>
+    <xi:include href="../../man/NetworkManager.xml"/>
+    <xi:include href="../../man/NetworkManager.conf.xml"/>
     <xi:include href="../../man/nmcli.xml"/>
+    <xi:include href="../../man/nmcli-examples.xml"/>
     <xi:include href="../../man/nmtui.xml"/>
-    <xi:include href="../../man/nm-online.xml"/>
-    <xi:include href="../../man/NetworkManager.conf.xml"/>
     <xi:include href="../../man/nm-settings.xml"><xi:fallback /></xi:include>
     <xi:include href="../../man/nm-settings-keyfile.xml"><xi:fallback /></xi:include>
     <xi:include href="../../man/nm-settings-ifcfg-rh.xml"><xi:fallback /></xi:include>
-    <xi:include href="../../man/nmcli-examples.xml"/>
-    <xi:include href="../../man/NetworkManager.xml"/>
-  </chapter>
-
-  <chapter id="spec">
-    <title>D-Bus API Reference</title>
-
-    <para>
-      This part documents the D-Bus interface used to access the
-      NetworkManager daemon.
-    </para>
-
-    <section id="dbus-interfaces">
-      <title>Interfaces</title>
-      <!-- TODO: Split me into chapters about daemon, vpn plugins, dispatcher and the secret agent.
-                    Then describe the daemon's singletons and object hierarchy. -->
-      <xi:include href="dbus-org.freedesktop.NetworkManager.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.AgentManager.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.AccessPoint.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.PPP.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.Connection.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Connection.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Connection.Active.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Adsl.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bond.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bridge.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bluetooth.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wired.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Generic.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Infiniband.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.IPTunnel.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macsec.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macvlan.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Modem.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OlpcMesh.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Team.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Tun.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Veth.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vlan.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vxlan.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wireless.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.WiMax.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP4Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP6Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.IP4Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.IP6Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Plugin.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.SecretAgent.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Statistics.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.DnsManager.xml"/>
-    </section>
-    <section id="dbus-types">
-      <title>Types</title>
-      <xi:include href="../../libnm-core/nm-dbus-types.xml"/>
-      <xi:include href="../../libnm-core/nm-vpn-dbus-types.xml"/>
-    </section>
-  </chapter>
+    <xi:include href="../../man/nm-online.xml"/>
+  </part>
 
-  <chapter id="ref-settings">
+  <part id="ref-settings">
     <title>Network Configuration Setting Specification</title>
     <para>
       This part documents the properties and value types of each "Setting"
@@ -120,16 +89,16 @@
     </para>
     <xi:include href="settings-spec.xml">
       <xi:fallback>
-	<section>
+	<chapter>
 	  <title>Configuration Settings</title>
 	  <note><para>
 	    (NetworkManager was built without full introspection support. Setting
 	    documentation is not available.)
 	  </para></note>
-	</section>
+	</chapter>
       </xi:fallback>
     </xi:include>
-    <section id="secrets-flags">
+    <chapter id="secrets-flags">
       <title>Secret flag types</title>
       <para>
         Each secret property in a setting has an associated "flags" property
@@ -163,8 +132,141 @@
           </listitem>
         </itemizedlist>
       </para>
-    </section>
-  </chapter>
+    </chapter>
+  </part>
+
+  <part id="spec">
+    <title id="dbus-interfaces">D-Bus API Reference</title>
+
+    <para>
+      This part documents the D-Bus interface used to access the
+      NetworkManager daemon.
+    </para>
+
+    <chapter id="ref-dbus-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-agent-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager/AgentManager</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.AgentManager.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-dns-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager/DnsManager</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.DnsManager.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-settings-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager/Settings</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-settings">
+      <title>The <literal>/org/freedesktop/NetworkManager/Settings/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.Connection.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-devices">
+      <title>The <literal>/org/freedesktop/NetworkManager/Devices/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Statistics.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Adsl.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bond.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bridge.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bluetooth.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Dummy.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wired.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Generic.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Infiniband.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.IPTunnel.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macsec.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macvlan.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Modem.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OlpcMesh.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Team.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Tun.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Veth.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vlan.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vxlan.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wireless.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.WiMax.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.PPP.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-active-connections">
+      <title>The <literal>/org/freedesktop/NetworkManager/ActiveConnection/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Connection.Active.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Connection.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-ip4-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/IP4Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.IP4Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-ip6-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/IP6Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.IP6Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-dhcp4-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/DHCP4Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP4Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-dhcp6-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/DHCP4Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP6Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-access-points">
+      <title>The <literal>/org/freedesktop/NetworkManager/AccessPoint/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.AccessPoint.xml"/>
+    </chapter>
+
+    <chapter id="dbus-types">
+      <title>Types</title>
+      <xi:include href="../../libnm-core/nm-dbus-types.xml"/>
+    </chapter>
+  </part>
+
+  <part id="secret-agents">
+    <title>Secret Agent D-Bus API Reference</title>
+
+    <chapter id="dbus-secret-agent">
+      <title>Secret agents</title>
+      <!-- TODO: Describe the secret agent here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.SecretAgent.xml"/>
+    </chapter>
+  </part>
+
+  <part id="vpn-plugins">
+    <title>VPN Plugin D-Bus API Reference</title>
+
+    <chapter id="dbus-vpn-types">
+      <title>VPN services</title>
+      <!-- TODO: Describe the VPN services here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Plugin.xml"/>
+    </chapter>
+    <chapter id="dbus-vpn-types">
+      <title>Types</title>
+      <xi:include href="../../libnm-core/nm-vpn-dbus-types.xml"/>
+    </chapter>
+  </part>
 
   <index>
     <title>Index</title>