>From d6c878114d0088ff1a313b52f08e40c011bc1e2f Mon Sep 17 00:00:00 2001
From: Colin Walters <walters verbum org>
Date: Tue, 9 Apr 2013 16:41:00 -0400
Subject: [PATCH] man: Rewrite NetworkManager.8 and NetworkManager.conf.5 in DocBook

DocBook is not my favorite thing in the world, but it's
<lots-of-emphasis>far</lots-of-emphasis> saner than troff.  Some style
parts cribbed from systemd.

This is preparatory work for actually improving the content of the
man pages.
---
 configure.ac                 |    2 -
 man/Makefile.am              |   16 ++
 man/NetworkManager.8.in      |  145 -----------------
 man/NetworkManager.conf.5.in |  310 ------------------------------------
 man/NetworkManager.conf.xml  |  362 ++++++++++++++++++++++++++++++++++++++++++
 man/NetworkManager.xml       |  223 ++++++++++++++++++++++++++
 6 files changed, 601 insertions(+), 457 deletions(-)
 delete mode 100644 man/NetworkManager.8.in
 delete mode 100644 man/NetworkManager.conf.5.in
 create mode 100644 man/NetworkManager.conf.xml
 create mode 100644 man/NetworkManager.xml

diff --git a/configure.ac b/configure.ac
index 034bd68..fb2e118 100644
--- a/configure.ac
+++ b/configure.ac
@@ -706,8 +706,6 @@ initscript/linexa/networkmanager
 introspection/Makefile
 introspection/all.xml
 man/Makefile
-man/NetworkManager.8
-man/NetworkManager.conf.5
 man/nm-system-settings.conf.5
 man/nm-online.1
 man/nmcli.1
diff --git a/man/Makefile.am b/man/Makefile.am
index 7db5623..fdf2041 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -14,6 +14,22 @@ nm-settings.xml: $(top_builddir)/tools/generate-settings-spec $(top_builddir)/li
 	$(top_builddir)/tools/generate-settings-spec refentry $(builddir)/$@
 CLEANFILES += nm-settings.xml
 
+XSLTPROC_FLAGS = \
+        --nonet \
+        --stringparam man.output.quietly 1 \
+        --stringparam funcsynopsis.style ansi \
+        --stringparam man.th.extra1.suppress 1 \
+        --stringparam man.authors.section.enabled 0 \
+        --stringparam man.copyright.section.enabled 0
+
+XSLTPROC_MAN_FLAGS = $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+
+%.8: %.xml
+	$(AM_V_GEN) xsltproc $(XSLTPROC_MAN_FLAGS) $<
+
+%.5: %.xml
+	$(AM_V_GEN) xsltproc $(XSLTPROC_MAN_FLAGS) $<
+
 man_MANS +=				\
 	NetworkManager.8		\
 	NetworkManager.conf.5		\
diff --git a/man/NetworkManager.8.in b/man/NetworkManager.8.in
deleted file mode 100644
index 38a195f..0000000
--- a/man/NetworkManager.8.in
+++ /dev/null
@@ -1,145 +0,0 @@
-.\" NetworkManager(8) manual page
-.\"
-.\" Copyright (C) 2005 - 2013 Red Hat, Inc.
-.\" Copyright (C) 2005 - 2009 Novell, Inc.
-.\" Copyright (C) 2005 Robert Love
-.\"
-.TH NETWORKMANAGER "8" "17 January 2012"
-.SH NAME
-NetworkManager \- network management daemon
-.SH SYNOPSIS
-.B NetworkManager [\-\-version] | [\-\-help]
-.PP
-.B NetworkManager [\-\-no\-daemon] [\-\-pid\-file=<filename>] [\-\-state\-file=<filename>] [\-\-config=<filename>] [\-\-config-dir=<directory>] [\-\-plugins=<plugin1>,plugin2>,...] [\-\-log\-level=<level>] [\-\-log\-domains=<domain1>,<domain2>,...]
-.SH DESCRIPTION
-The \fINetworkManager\fP daemon attempts to make  networking configuration and
-operation as painless and automatic as possible by managing the primary network
-connection and other network interfaces, like Ethernet, WiFi, and Mobile
-Broadband devices.  NetworkManager will connect any network device when a
-connection for that device becomes available, unless that behavior is disabled.
-Information about networking is exported via a D-Bus interface to any interested
-application, providing a rich API with which to inspect and control network
-settings and operation.
-.P
-NetworkManager will execute scripts in the /etc/NetworkManager/dispatcher.d
-directory in alphabetical order in response to network events.  Each script
-should be:
-.IP "(a)" 4
-a regular file
-.IP "(b)" 4
-owned by root
-.IP "(c)" 4
-not writable by group or other
-.IP "(d)" 4
-not set-uid
-.IP "(e)" 4
-and executable by the owner
-.PP
-Each script receives two arguments, the first being the interface name of the
-device just activated, and second an action.
-.PP
-Actions:
-.TP
-.I "up"
-The interface has been activated.  The environment contains more information
-about the interface; CONNECTION_UUID contains the UUID of the connection.  Other
-variables are IP4_ADDRESS_N where N is a number from 0 to (# IPv4 addresses \- 1),
-in the format "address/prefix gateway".  IP4_NUM_ADDRESSES contains the number
-addresses the script may expect.  IP4_NAMESERVERS contains a space-separated
-list of the DNS servers, and IP4_DOMAINS contains a space-separated list of the
-search domains.  Routes use the format IP4_ROUTE_N where N is a number from 0
-to (# IPv4 routes \- 1), in the format "address/prefix next-hop metric", and
-IP4_NUM_ROUTES contains the number of routes to expect.  If the connection used
-DHCP for address configuration, the received DHCP configuration is passed in the
-environment using standard DHCP option names, prefixed with "DHCP4_", like
-"DHCP4_HOST_NAME=foobar".
-.TP
-.I "down"
-The interface has been deactivated.
-.TP
-.I "vpn\-up"
-A VPN connection has been activated.  The environment contains the connection
-UUID in the variable CONNECTION_UUID.
-.TP
-.I "vpn\-down"
-A VPN connection has been deactivated.
-.TP
-.I "hostname"
-The system hostname has been updated.  Use gethostname(2) to retrieve it.
-.TP
-.I "dhcp4\-change"
-The DHCPv4 lease has changed (renewed, rebound, etc).
-.TP
-.I "dhcp6\-change"
-The DHCPv6 lease has changed (renewed, rebound, etc).
-.SH OPTIONS
-The following options are supported:
-.TP
-.I "\-\-version"
-Print the NetworkManager software version and exit.
-.TP
-.I "\-\-help"
-Print NetworkManager's available options and exit.
-.TP
-.I "\-\-no\-daemon"
-Do not daemonize.  This is useful for debugging, and directs log output to the
-controlling terminal in addition to syslog.
-.TP
-.I "\-\-pid\-file=<filename>"
-Specify location of a PID file.  The PID file is used for storing PID of the
-running proccess and prevents running multiple instances.
-.TP
-.I "\-\-state\-file=<filename>"
-Specify file for storing state of the NetworkManager persistently.  If not specified,
-the default value of '<LOCALSTATEDIR>/lib/NetworkManager/NetworkManager.state' is
-used; where <LOCALSTATEDIR> is dependent on your distribution (usually it's /var).
-.TP
-.I "\-\-config=<filename>"
-Specify configuration file to set up various settings for NetworkManager.  If not
-specified, the default value of '<SYSCONFDIR>/NetworkManager/NetworkManager.conf'
-is used with a fallback to the older 'nm\-system\-settings.conf' if located in
-the same directory; where <SYSCONFDIR> is dependent on your distribution (usually
-it's /etc).  See \fBNetworkManager.conf\fP(5) for more information on configuration
-file.
-.TP
-.I "\-\-config-dir=<directory>"
-Specify configuration directory for files that override NetworkManager.conf.  If not
-specified, the default value of '<SYSCONFDIR>/NetworkManager/conf.d'
-is used.  See \fBNetworkManager.conf\fP(5) for more information on configuration
-file.
-.TP
-.I "\-\-plugins=<plugin1>,<plugin2>, ...
-List plugins used to manage system-wide connection settings.   This list has
-preference over plugins specified in the configuration file.  Currently supported
-plugins are: keyfile, ifcfg\-rh, ifcfg\-suse, ifupdown.
-See \fBNetworkManager.conf\fP(5) for more information on the plugins.
-.TP
-.I "\-\-log\-level=<level>
-Sets how much information NetworkManager sends to the log destination (usually
-syslog's "daemon" facility).  By default, only informational, warning, and error
-messages are logged.  See \fBNetworkManager.conf\fP(5) for more information on
-log levels and domains.
-.TP
-.I "\-\-log\-domains=<domain1>,<domain2>, ...
-Sets which operations are logged to the log destination (usually syslog).  By
-default, most domains are logging-enabled.  See \fBNetworkManager.conf\fP(5) for
-more information on log levels and domains.
-
-.SH DEBUGGING
-The following environment variables are supported to help debugging.  When used
-in conjunction with the "\-\-no\-daemon" option (thus echoing PPP and DHCP helper
-output to stdout) these can quickly help pinpoint the source of connection
-issues.  Also see the \-\-log\-level and \-\-log\-domains to enable debug logging inside
-NetworkManager itself.
-.TP
-.I "NM_PPP_DEBUG"
-When set to anything, causes NetworkManager to turn on PPP debugging in pppd,
-which logs all PPP and PPTP frames and client/server exchanges.
-.SH SEE ALSO
-.BR nm\-online (1),
-.BR nmcli (1),
-.BR NetworkManager.conf (5),
-.BR nm\-settings (5),
-.BR nm\-applet (1),
-.BR nm\-connection\-editor (1).
-
diff --git a/man/NetworkManager.conf.5.in b/man/NetworkManager.conf.5.in
deleted file mode 100644
index 368d776..0000000
--- a/man/NetworkManager.conf.5.in
+++ /dev/null
@@ -1,310 +0,0 @@
-.\" NetworkManager.conf(5) manual page
-.\"
-.\" Copyright (C) 2010 - 2013 Red Hat, Inc.
-.\"
-.TH "NetworkManager.conf" "5" "14 March 2013" ""
-.SH NAME
-NetworkManager.conf \- NetworkManager configuration file
-.SH SYNOPSIS
-/etc/NetworkManager/NetworkManager.conf
-.br
-/etc/NetworkManager/conf.d/*.conf
-.br
-or
-.br
-\fI<SYSCONFDIR>\fP/NetworkManager/NetworkManager.conf
-.br
-\fI<SYSCONFDIR>\fP/NetworkManager/conf.d/*.conf
-.br
-where <SYSCONFDIR> depends on your distribution or build.
-.SH DESCRIPTION
-.P
-.I NetworkManager.conf
-is a configuration file for NetworkManager. It is used to set up various
-aspects of NetworkManager's behavior. The location of
-the file may be changed through use of the "\-\-config=" argument for
-\fBNetworkManager\fP (8).
-.P
-If a default
-.I NetworkManager.conf
-is provided by your distribution's packages, you should not modify it,
-since your changes may get overwritten by package updates. Instead,
-you can add additional
-.I .conf
-files to the
-.I conf.d
-directory. These will be read in order, with later files overriding
-earlier ones.
-.SH "FILE FORMAT"
-.P
-The configuration file format is so-called key file (sort of ini-style format).
-It consists of sections (groups) of key-value pairs. Lines beginning with a '#' and blank
-lines are considered comments. Sections are started by a header line containing
-the section enclosed in '[' and ']', and ended implicitly by the start of
-the next section or the end of the file. Each key-value pair must be contained
-in a section.
-.P
-For keys that take a list of devices as their value, you can specify
-devices by their MAC addresses or interface names, or "*" to specify
-all devices.
-.P
-Minimal system settings configuration file looks like this:
-.P
-.nf
-[main]
-plugins=keyfile
-.fi
-.P
-As an extension to the normal keyfile format, you can also append a
-value to a previously-set list-valued key by doing:
-.P
-.nf
-[main]
-plugins+=another-plugin
-.fi
-.P
-Description of sections and available keys follows:
-.SS [main]
-This section is the only mandatory section of the configuration file.
-.TP
-.B plugins=\fIplugin1\fP,\fIplugin2\fP, ...
-List system settings plugin names separated by ','. These plugins are used to
-read/write system-wide connection. When more plugins are specified, the
-connections are read from all listed plugins. When writing connections, the
-plugins will be asked to save the connection in the order listed here. If the
-first plugin cannot write out that connection type, or can't write out any
-connections, the next plugin is tried. If none of the plugins can save the
-connection, the error is returned to the user.
-.P
-.RS
-.B "Available plugins:"
-.br
-.TP 
-.I keyfile
-plugin is the generic plugin that supports all the connection types and
-capabilities that NetworkManager has. It writes files out in a .ini-style format in
-/etc/NetworkManager/system-connections. For security, it will ignore files
-that are readable or writeable by any user or group other than
-.I root
-since private keys and passphrases may be stored in plaintext inside the file.
-.TP 
-.I ifcfg\-rh
-plugin is used on the Fedora and Red Hat Enterprise Linux distributions
-to read and write configuration from the standard /etc/sysconfig/network-scripts/ifcfg-* files.
-It currently supports reading wired, WiFi, and 802.1x connections, but does not yet support reading
-or writing mobile broadband, PPPoE, or VPN connections. To allow reading and writing of these
-add \fIkeyfile\fP plugin to your configuration as well.
-.TP
-.I ifupdown
-plugin is used on the Debian and Ubuntu distributions, and reads connections from
-/etc/network/interfaces. Since it cannot write connections out (that support isn't planned),
-it is usually paired with the \fIkeyfile\fP plugin to enable saving and editing of new connections.
-The \fIifupdown\fP plugin supports basic wired and WiFi connections, including WPA-PSK.
-.TP
-.I ifcfg\-suse
-plugin is only provided for simple backward compatibility with SUSE and OpenSUSE configuration.
-Most setups should be using the \fIkeyfile\fP plugin instead. The \fIifcfg\-suse\fP plugin supports
-reading wired and WiFi connections, but does not support saving any connection types.
-.RE
-.TP
-.B dhcp=\fIdhclient\fP | \fIdhcpcd\fP
-This key sets up what DHCP client NetworkManager will use. Presently
-\fIdhclient\fP and \fIdhcpcd\fP are supported. The client configured here should
-be available on your system too. If this key is missing, available DHCP clients
-are looked for in this order: dhclient, dhcpcd.
-.TP
-.B no-auto-default=\fI<device>\fP,\fI<device>\fP,... | \fI*\fP
-Set devices for which NetworkManager shouldn't create default wired connection
-(Auto eth0). NetworkManager creates a default wired connection for any Ethernet
-device that is managed and doesn't have a connection configured. List a device
-in this option to inhibit creating the default connection for the device.
-.br
-When the default wired connection is deleted or saved to a new persistent connection
-by a plugin, the device is added to a list in the file
-\fI<LOCALSTATEDIR>\fP/run/NetworkManager/no-auto-default.state
-to prevent creating the default connection for that device again.
-.br
-Examples:
-.nf
-no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee
-no-auto-default=eth0,eth1
-no-auto-default=*
-.fi
-.TP
-.B ignore-carrier=\fI<device>\fP,\fI<device>\fP,... | \fI*\fP
-Set devices for which NetworkManager should ignore device carrier state when
-deciding whether to activate or deactivate connections.
-.TP
-.B dns=\fImode\fP
-Set the DNS/resolv.conf-processing mode.
-.P
-.RS
-.B "Supported modes:"
-.br
-.TP
-.I default
-The default if the key is not specified. NetworkManager will update
-resolv.conf to reflect the nameservers provided by currently active
-connections.
-.TP
-.I dnsmasq
-NetworkManager will run dnsmasq as a local caching nameserver, using
-a "split DNS" configuration if you are connected to a VPN, and then
-update resolv.conf to point to the local nameserver.
-.TP
-.I none
-NetworkManager will not modify resolv.conf.
-.RE
-.SS [keyfile]
-This section contains keyfile-specific options and thus only has effect when using \fIkeyfile\fP plugin.
-.TP
-.B hostname=\fI<hostname>\fP
-Set a persistent hostname when using the \fIkeyfile\fP plugin.
-.TP
-.B unmanaged-devices=\fImac:<hwaddr>\fP;\fIinterface\-name:<iface name>\fP;...
-Set devices that should be ignored by NetworkManager when using the \fIkeyfile\fP
-plugin. Devices are specified in the following format:
-.br
-"mac:<hwaddr>" or "interface\-name:<iface name>"
-.sp
-\fI<hwaddr>\fP is MAC address of the device to be ignored, in hex-digits-and-colons notation
-.br
-\fI<iface name>\fP is the interface name of the ignored device
-.br
-Multiple entries are separated with semicolons. No spaces are allowed in the value.
-.sp
-Examples:
-.nf
-unmanaged-devices=interface-name:em4
-unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
-.fi
-.SS [ifupdown]
-This section contains ifupdown-specific options and thus only has effect when using \fIifupdown\fP plugin.
-.TP
-.B managed=\fIfalse\fP | \fItrue\fP
-Controls whether interfaces listed in the 'interfaces' file are managed by NetworkManager.
-If set to \fItrue\fP, then interfaces listed in /etc/network/interfaces are managed by NetworkManager.
-If set to \fIfalse\fP, then any interface listed in /etc/network/interfaces will be
-ignored by NetworkManager. Remember that NetworkManager controls the default route,
-so because the interface is ignored, NetworkManager may assign the default route to
-some other interface.
-When the option is missing, \fIfalse\fP value is taken as default.
-.SS [logging]
-This section controls NetworkManager's logging.  Any settings here are
-overridden by the \-\-log\-level and \-\-log\-domains command-line options.
-.TP
-.B level=\fI<level>\fP
-One of [ERR, WARN, INFO, DEBUG].  The ERR level logs only critical errors.  WARN
-logs warnings that may reflect operation.  INFO logs various informational
-messages that are useful for tracking state and operations.  DEBUG enables
-verbose logging for debugging purposes.  Subsequent levels also log all messages
-from earlier levels; thus setting the log level to INFO also logs error and
-warning messages.
-.TP
-.B domains=\fI<domain1>,<domain2>, ...\fP
-The following log domains are available: [HW, RFKILL, ETHER, WIFI, BT, MB, DHCP4,
-DHCP6, PPP, WIFI_SCAN, IP4, IP6, AUTOIP4, DNS, VPN, SHARING, SUPPLICANT, AGENTS,
-SETTINGS, SUSPEND, CORE, DEVICE, OLPC, WIMAX, INFINIBAND, FIREWALL, ADSL, BOND,
-VLAN, BRIDGE].
-.br
-In addition to them, these special domains can be used: [NONE, ALL, DEFAULT, DHCP, IP].
-.PP
-.RS
-NONE = when given by itself, logging is disabled
-.br
-ALL = all log domains will be switched on
-.br
-DEFAULT = default log domains
-.br
-DHCP = a shortcut for "DHCP4, DHCP6"
-.br
-IP = a shortcut for "IP4, IP6"
-.br
-.PP
-HW = Hardware related operations
-.br
-RFKILL = RFKill subsystem operations
-.br
-ETHER = Ethernet device operations
-.br
-WIFI = Wi-Fi device operations
-.br
-BT = Bluetooth
-.br
-MB = Mobile Broadband
-.br
-DHCP4 = DHCP for IPv4
-.br
-DHCP6 = DHCP for IPv6
-.br
-PPP = Point-to-point protocol operations
-.br
-WIFI_SCAN = Wi-Fi scanning operations
-.br
-IP4 = Domain for IPv4 logging
-.br
-IP6 = Domain for IPv6 logging
-.br
-AUTOIP4 = AutoIP (avahi) operations
-.br
-DNS = Domain Name System related operations
-.br
-VPN = Virtual Private Network connections and operaions
-.br
-SHARING = Connection sharing
-.br
-SUPPLICANT = WPA supplicant related operations
-.br
-AGENTS = Secret agents operations and communication
-.br
-SETTINGS = Settings/config service operations
-.br
-SUSPEND = Suspend/resume
-.br
-CORE = Core daemon operations
-.br
-DEVICE = Activation and general interface operations
-.br
-OLPC = OLPC Mesh device operations
-.br
-WIMAX = Wimax device operations
-.br
-INFINIBAND = InfiniBand device operations
-.br
-FIREWALL = FirewallD related operations
-.br
-ADSL = ADSL device operations
-.br
-BOND = Bonding device operations
-.br
-VLAN = VLAN device operations
-.br
-BRIDGE = Bridging device operations
-.br
-.SS [connectivity]
-This section controls NetworkManager's optional connectivity checking
-functionality.  This allows NetworkManager to detect whether or not the system
-can actually access the internet or whether it is behind a captive portal.
-.TP
-.B uri=\fI<uri>\fP
-The URI of a web page to periodically request when connectivity is being checked.
-This page should return the header "X-NetworkManager-Status" with a value of
-"online".  Alternatively, it's body content should be set to "NetworkManager
-is online".  The body content check can be controlled by the \fIresponse\fP
-option.  If this option is blank or missing, connectivity checking is disabled.
-.TP
-.B interval=\fI<seconds>\fP
-Controls how often connectivity is checked when a network connection exists. If
-set to 0 connectivity checking is disabled.  If missing, the default is 300
-seconds.
-.TP
-.B response=\fI<response>\fP
-If set controls what body content NetworkManager checks for when requesting the
-URI for connectivity checking.  If missing, defaults to "NetworkManager is online"
-.SH "SEE ALSO"
-.BR http://live.gnome.org/NetworkManager/SystemSettings
-.sp
-.BR NetworkManager (8),
-.BR nmcli (1),
-.BR nm\-online (1),
-.BR nm\-settings (5).
diff --git a/man/NetworkManager.conf.xml b/man/NetworkManager.conf.xml
new file mode 100644
index 0000000..23f7244
--- /dev/null
+++ b/man/NetworkManager.conf.xml
@@ -0,0 +1,362 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+Copyright (C) 2010 - 2013 Red Hat, Inc.
+-->
+
+<refentry id="NetworkManager.conf">
+  <refentryinfo>
+    <title>NetworkManager.conf</title>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>NetworkManager.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>NetworkManager.conf</refname>
+    <refpurpose>NetworkManager configuration file</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>/etc/NetworkManager/NetworkManager.conf</filename>,
+    <filename>/etc/NetworkManager/conf.d/<replaceable>name</replaceable>.conf</filename>
+    </para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>This is a configuration file for NetworkManager. It is used
+    to set up various aspects of NetworkManager's behavior. The
+    location of the file may be changed through use of the
+    <option>--config</option> argument for NetworkManager.
+    </para>
+    <para>If a default <literal>NetworkManager.conf</literal> is
+    provided by your distribution's packages, you should not modify
+    it, since your changes may get overwritten by package
+    updates. Instead, you can add additional <literal>.conf</literal>
+    files to the <literal>conf.d</literal> directory. These will be read in order,
+    with later files overriding earlier ones.
+    </para>
+    
+  </refsect1>
+
+  <refsect1>
+    <title>File Format</title>
+    <para>
+      The configuration file format is so-called key file (sort of
+      ini-style format).  It consists of sections (groups) of
+      key-value pairs. Lines beginning with a '#' and blank lines are
+      considered comments. Sections are started by a header line
+      containing the section enclosed in '[' and ']', and ended
+      implicitly by the start of the next section or the end of the
+      file. Each key-value pair must be contained in a section.
+    </para>
+    <para>
+      For keys that take a list of devices as their value, you can
+      specify devices by their MAC addresses or interface names, or
+      "*" to specify all devices.
+    </para>
+    <para>
+      Minimal system settings configuration file looks like this:
+      <programlisting>
+	[main]
+	plugins=keyfile
+      </programlisting>
+    </para>
+    <para>
+      As an extension to the normal keyfile format, you can also
+      append a value to a previously-set list-valued key by doing:
+      <programlisting>
+	plugins+=another-plugin
+      </programlisting>
+    </para>
+  </refsect1>
+  
+  <refsect1>
+    <title><literal>main</literal> section (mandatory)</title>
+    <variablelist>
+      <varlistentry>
+	<term><varname>plugins</varname></term>
+	<listitem><para>List system settings plugin names separated
+	by ','. These plugins are used to read/write system-wide
+	connection. When more plugins are specified, the connections
+	are read from all listed plugins. When writing connections,
+	the plugins will be asked to save the connection in the
+	order listed here. If the first plugin cannot write out that
+	connection type, or can't write out any connections, the
+	next plugin is tried. If none of the plugins can save the
+	connection, the error is returned to the user.  See below
+	for available plugins.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>dhcp</varname></term>
+	<listitem><para>This key sets up what DHCP client
+	NetworkManager will use. Presently
+	<literal>dhclient</literal> and <literal>dhcpcd</literal>
+	are supported. The client configured here should be
+	available on your system too. If this key is missing,
+	available DHCP clients are looked for in this order:
+	dhclient, dhcpcd.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>no-auto-default</varname></term>
+	<listitem><para>Comma-separated list of devices for which
+	NetworkManager shouldn't create default wired connection
+	(Auto eth0).  By default, NetworkManager creates a temporary
+	wired connection for any Ethernet device that is managed and
+	doesn't have a connection configured. List a device in this
+	option to inhibit creating the default connection for the
+	device. May have the special value <literal>*</literal> to
+	apply to all devices.</para>
+	<para>When the default wired connection is deleted or saved
+	to a new persistent connection by a plugin, the device is
+	added to a list in the file
+	<filename>/var/run/NetworkManager/no-auto-default.state</filename>
+	to prevent creating the default connection for that device
+	again.</para>
+	<para>
+	  <programlisting>
+	    no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee
+	    no-auto-default=eth0,eth1
+	    no-auto-default=*
+	  </programlisting>
+	</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>ignore-carrier</varname></term>
+	<listitem><para>Set devices for which NetworkManager should
+	ignore device carrier state when deciding whether to
+	activate or deactivate connections.  May have the special
+	value <literal>*</literal> to apply to all
+	devices.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>dns</varname></term>
+	<listitem><para>Set the DNS (<filename>resolv.conf</filename>) processing mode.</para>
+	<para><literal>default</literal>: The default if the key is
+	not specified. NetworkManager will update
+	<filename>resolv.conf</filename> to reflect the nameservers
+	provided by currently active connections.</para>
+	<para><literal>dnsmasq</literal>NetworkManager will run
+	dnsmasq as a local caching nameserver, using a "split DNS"
+	configuration if you are connected to a VPN, and then update
+	<filename>resolv.conf</filename> to point to the local
+	nameserver.</para>
+	<para><literal>none</literal>: NetworkManager will not
+	modify resolv.conf.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title><literal>keyfile</literal> section</title>
+    <para>This section contains keyfile-specific options and thus only has effect when using the <literal>keyfile</literal> plugin.</para>
+
+    <para>
+      <variablelist>
+	<varlistentry>
+	  <term><varname>hostname</varname></term>
+	  <listitem><para>Set a persistent hostname.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><varname>unmanaged-devices</varname></term>
+	  <listitem><para>Set devices that should be ignored by
+	  NetworkManager when using the <literal>keyfile</literal>
+	  plugin. Devices are specified in the following
+	  format:</para>
+	  <para><literal>mac:&lt;hwaddr&gt;</literal> or
+	  <literal>interface-name:&lt;ifname&gt;</literal>.  Here
+	  <literal>hwaddr</literal> is the MAC address of the device
+	  to be ignored, in hex-digits-and-colons notation.
+	  <literal>ifname</literal> is the interface name of the
+	  ignored device.</para>
+	  <para>Multiple entries are separated with semicolons. No
+	  spaces are allowed in the value.</para>
+	  <para>
+	    Example:
+	    <programlisting>
+unmanaged-devices=interface-name:em4
+unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
+	    </programlisting>
+	  </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title><literal>ifupdown</literal> section</title>
+    <para>This section contains keyfile-specific options and thus only
+    has effect when using the <literal>ifdown</literal> plugin.</para>
+
+    <para>
+      <variablelist>
+	<varlistentry>
+	  <term><varname>managed</varname></term>
+	  <listitem><para>If set to <literal>true</literal>, then
+	  interfaces listed in
+	  <filename>/etc/network/interfaces</filename> are managed by
+	  NetworkManager.  If set to <literal>false</literal>, then
+	  any interface listed in
+	  <filename>/etc/network/interfaces</filename> will be ignored
+	  by NetworkManager. Remember that NetworkManager controls the
+	  default route, so because the interface is ignored,
+	  NetworkManager may assign the default route to some other
+	  interface.</para>
+	  <para>
+	    The default value is <literal>false</literal>.
+	  </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title><literal>logging</literal> section</title>
+    <para>This section controls NetworkManager's logging.  Any
+    settings here are overridden by the <option>--log-level</option>
+    and <option>--log-domains</option> command-line options.</para>
+
+    <para>
+      <variablelist>
+	<varlistentry>
+	  <term><varname>level</varname></term>
+	  <listitem><para>One of <literal>ERR</literal>,
+	  <literal>WARN</literal>, <literal>INFO</literal>,
+	  <literal>DEBUG</literal>.  The ERR level logs only critical
+	  errors.  WARN logs warnings that may reflect operation.
+	  INFO logs various informational messages that are useful for
+	  tracking state and operations.  DEBUG enables verbose
+	  logging for debugging purposes.  Subsequent levels also log
+	  all messages from earlier levels; thus setting the log level
+	  to INFO also logs error and warning messages.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><varname>domains</varname></term>
+	  <listitem><para>The following log domains are available:
+	  HW, RFKILL, ETHER, WIFI, BT, MB, DHCP4, DHCP6, PPP,
+	  WIFI_SCAN, IP4, IP6, AUTOIP4, DNS, VPN, SHARING, SUPPLICANT,
+	  AGENTS, SETTINGS, SUSPEND, CORE, DEVICE, OLPC, WIMAX,
+	  INFINIBAND, FIREWALL, ADSL, BOND, VLAN, BRIDGE.</para>
+	  <para>In addition, these special domains can be used: NONE,
+	  ALL, DEFAULT, DHCP, IP.</para></listitem>
+	</varlistentry>
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title><literal>connectivity</literal> section</title>
+    <para>This section controls NetworkManager's optional connectivity
+    checking functionality.  This allows NetworkManager to detect
+    whether or not the system can actually access the internet or
+    whether it is behind a captive portal.</para>
+    
+    <para>
+      <variablelist>
+	<varlistentry>
+	  <term><varname>uri</varname></term>
+	  <listitem><para>The URI of a web page to periodically
+	  request when connectivity is being checked.  This page
+	  should return the header "X-NetworkManager-Status" with a
+	  value of "online".  Alternatively, it's body content should
+	  be set to "NetworkManager is online".  The body content
+	  check can be controlled by the <literal>response</literal>
+	  option.  If this option is blank or missing, connectivity
+	  checking is disabled.
+	  </para></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><varname>interval</varname></term>
+	  <listitem><para>Specified in seconds; controls how often
+	  connectivity is checked when a network connection exists. If
+	  set to 0 connectivity checking is disabled.  If missing, the
+	  default is 300 seconds.</para></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><varname>response</varname></term>
+	  <listitem><para>If set controls what body content
+	  NetworkManager checks for when requesting the URI for
+	  connectivity checking.  If missing, defaults to
+	  "NetworkManager is online" </para></listitem>
+	</varlistentry>
+      </variablelist>
+    </para>
+  </refsect1>
+  
+  <refsect1>
+    <title>Plugins</title>
+    
+    <variablelist>
+      <varlistentry>
+	<term><varname>keyfile</varname></term>
+	<listitem><para>plugin is the generic plugin that supports
+	all the connection types and capabilities that
+	NetworkManager has. It writes files out in an .ini-style
+	format in /etc/NetworkManager/system-connections. For
+	security, it will ignore files that are readable or
+	writeable by any user or group other than root since
+	private keys and passphrases may be stored in plaintext
+	inside the file.  </para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>ifcfg-rh</varname></term>
+	<listitem><para>This plugin is used on the Fedora and Red
+	Hat Enterprise Linux distributions to read and write
+	configuration from the standard
+	<filename>/etc/sysconfig/network-scripts/ifcfg-*</filename>
+	files.  It currently supports reading wired, WiFi, and
+	802.1x connections, but does not yet support reading or
+	writing mobile broadband, PPPoE, or VPN connections. To
+	allow reading and writing of these add <literal>keyfile</literal>
+	plugin to your configuration as well.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>ifupdown</varname></term>
+	<listitem><para>This plugin is used on the Debian and Ubuntu
+	distributions, and reads connections from
+	<filename>/etc/network/interfaces</filename>. Since it cannot
+	write connections out (that support isn't planned), it is
+	usually paired with the <literal>keyfile</literal> plugin to
+	enable saving and editing of new connections.  The
+	<literal>ifupdown</literal> plugin supports basic wired and
+	WiFi connections, including WPA-PSK.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>ifcfg-suse</varname></term>
+	<listitem><para>This plugin is only provided for simple
+	backward compatibility with SUSE and OpenSUSE
+	configuration.  Most setups should be using the
+	<literal>keyfile</literal> plugin instead. The
+	<literal>ifcfg-suse</literal> plugin supports reading
+	wired and WiFi connections, but does not support saving
+	any connection types.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nm-applet</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nm-connection-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+</refentry>
+
diff --git a/man/NetworkManager.xml b/man/NetworkManager.xml
new file mode 100644
index 0000000..df1815a
--- /dev/null
+++ b/man/NetworkManager.xml
@@ -0,0 +1,223 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  Copyright (C) 2005 - 2013 Red Hat, Inc.
+ Copyright (C) 2005 - 2009 Novell, Inc.
+ Copyright (C) 2005 Robert Love
+
+-->
+
+<refentry id="NetworkManager">
+  <refentryinfo>
+    <title>NetworkManager</title>
+  </refentryinfo>
+  <refmeta>
+    <refentrytitle>NetworkManager</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+  
+  <refnamediv>
+    <refname>NetworkManager</refname>
+    <refpurpose>network management daemon</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>NetworkManager <arg choice="opt" rep="repeat">OPTIONS</arg></command>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      The NetworkManager daemon attempts to make networking
+      configuration and operation as painless and automatic as
+      possible by managing the primary network connection and other
+      network interfaces, like Ethernet, WiFi, and Mobile Broadband
+      devices.  NetworkManager will connect any network device when a
+      connection for that device becomes available, unless that
+      behavior is disabled.  Information about networking is exported
+      via a D-Bus interface to any interested application, providing a
+      rich API with which to inspect and control network settings and
+      operation.
+    </para>
+    <para>
+      NetworkManager will execute scripts in the
+      /etc/NetworkManager/dispatcher.d directory in alphabetical order
+      in response to network events.  Each script should be a regular
+      executable file, owned by root.  Furthermore, it must not be
+      writable by group or other, and not setuid.
+    </para>
+    <para>
+      Each script receives two arguments, the first being the interface name of the
+      device just activated, and second an action.
+    </para>
+    <variablelist class="dispatcher-options">
+      <varlistentry>
+	<term><varname>up</varname></term>
+	<listitem><para>The interface has been activated.  The
+	environment contains more information about the interface;
+	CONNECTION_UUID contains the UUID of the connection.  Other
+	variables are IP4_ADDRESS_N where N is a number from 0 to (#
+	IPv4 addresses \- 1), in the format "address/prefix gateway".
+	IP4_NUM_ADDRESSES contains the number addresses the script may
+	expect.  IP4_NAMESERVERS contains a space-separated list of
+	the DNS servers, and IP4_DOMAINS contains a space-separated
+	list of the search domains.  Routes use the format IP4_ROUTE_N
+	where N is a number from 0 to (# IPv4 routes \- 1), in the
+	format "address/prefix next-hop metric", and IP4_NUM_ROUTES
+	contains the number of routes to expect.  If the connection
+	used DHCP for address configuration, the received DHCP
+	configuration is passed in the environment using standard DHCP
+	option names, prefixed with "DHCP4_", like
+	"DHCP4_HOST_NAME=foobar".</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>down</varname></term>
+	<listitem><para>
+	  The interface has been deactivated.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>vpn-up</varname></term>
+	<listitem><para>
+	  A VPN connection has been activated.  The environment contains the connection
+	  UUID in the variable CONNECTION_UUID.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>vpn-down</varname></term>
+	<listitem><para>
+	  A VPN connection has been deactivated.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>hostname</varname></term>
+	<listitem><para>
+	  The system hostname has been updated.  Use gethostname(2) to retrieve it.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>dhcp4-change</varname></term>
+	<listitem><para>
+	  The DHCPv4 lease has changed (renewed, rebound, etc).
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><varname>dhcp6-change</varname></term>
+	<listitem><para>
+	  The DHCPv6 lease has changed (renewed, rebound, etc).
+	</para></listitem>
+      </varlistentry>
+    </variablelist>
+  
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    
+    <para>The following options are understood:</para>
+
+    <variablelist>
+      <varlistentry>
+	<term><option>--version</option></term>
+	<listitem><para>Print the NetworkManager software version and exit.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--help</option></term>
+	<listitem><para>Print NetworkManager's available options and exit.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--no-daemon</option></term>
+	<listitem><para>Do not daemonize.  This is useful for
+	debugging, and directs log output to the controlling terminal
+	in addition to syslog.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--pid-file</option></term>
+	<listitem><para>Specify location of a PID file.  The PID file
+	is used for storing PID of the running proccess and prevents
+	running multiple instances.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--state-file</option></term>
+	<listitem><para>Specify file for storing state of the
+	NetworkManager persistently.  If not specified, the default
+	value of /var/lib/NetworkManager/NetworkManager.state is used.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--config</option></term>
+	<listitem><para> Specify configuration file to set up various
+	settings for NetworkManager.  If not specified, the default
+	value of /etc/NetworkManager/NetworkManager.conf is used with
+	a fallback to the older 'nm\-system\-settings.conf' if located
+	in the same directory.  See
+	<citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+	for more information on configuration file.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--plugins</option></term>
+	<listitem><para>List plugins used to manage system-wide
+	connection settings.  This list has preference over plugins
+	specified in the configuration file.  Currently supported
+	plugins are: keyfile, <option>ifcfg-rh</option>,
+	<option>ifcfg-suse</option>, <option>ifupdown</option>.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--log-level</option></term>
+	<listitem><para>
+	  Sets how much information NetworkManager sends to the log destination (usually
+	  syslog's "daemon" facility).  By default, only informational, warning, and error
+	  messages are logged.
+	</para></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--log-domains</option></term>
+	<listitem><para>A comma-separated list specifying which
+	operations are logged to the log destination (usually syslog).
+	By default, most domains are logging-enabled.
+	</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>DEBUGGING</title>
+    <para>
+      The following environment variables are supported to help
+      debugging.  When used in conjunction with the
+      <option>--no-daemon</option> option (thus echoing PPP and DHCP
+      helper output to stdout) these can quickly help pinpoint the
+      source of connection issues.  Also see the
+      <option>--log-level</option> and <option>--log-domains</option>
+      to enable debug logging inside NetworkManager itself.
+    </para>
+    <para>
+      <option>NM_PPP_DEBUG</option>: When set to anything, causes
+      NetworkManager to turn on PPP debugging in pppd, which logs
+      all PPP and PPTP frames and client/server exchanges.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nm-applet</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>nm-connection-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+</refentry>
-- 
1.7.1