New DEBUG facility - man pages

https://fedorahosted.org/sssd/ticket/925

Modified sssd and sssd.conf man pages to reflect new levels.
Added new man include: include/debug_levels.xml

3 files changed, 62 insertions, 17 deletions

diff --git a/src/man/include/debug_levels.xml b/src/man/include/debug_levels.xml
new file mode 100644
index 000000000..ce5064051
--- /dev/null
+++ b/src/man/include/debug_levels.xml
@@ -0,0 +1,60 @@
+<listitem>
+    <para>
+        Bit mask that indicates which debug levels will be visible. 0x0010 is the default value as well
+        as the lowest allowed value, 0xFFF0 is the most verbose mode. This setting
+        overrides the settings from config file.
+    </para>
+    <para>
+        Currently supported debug levels:
+    </para>
+    <para>
+         <emphasis>0x0010</emphasis>:
+         Fatal failures. Anything that would prevent SSSD from starting up or causes it to cease running.
+    </para>
+    <para>
+         <emphasis>0x0020</emphasis>:
+         Critical failures. An error that doesn't kill the SSSD, but one that indicates
+         that at least one major feature is not going to work properly.
+    </para>
+    <para>
+         <emphasis>0x0040</emphasis>: Serious failures. An error announcing that a particular request or
+         operation has failed.
+    </para>
+    <para>
+         <emphasis>0x0080</emphasis>: Minor failures. These are the errors that would percolate down to
+         cause the operation failure of 2.
+    </para>
+    <para>
+         <emphasis>0x0100</emphasis>: Configuration settings.
+    </para>
+    <para>
+         <emphasis>0x0200</emphasis>: Function data.
+    </para>
+    <para>
+         <emphasis>0x0400</emphasis>: Trace messages for operation functions.
+    </para>
+    <para>
+         <emphasis>0x1000</emphasis>: Trace messages for internal control functions.
+    </para>
+    <para>
+         <emphasis>0x2000</emphasis>: Contents of function-internal variables that may be interesting.
+    </para>
+    <para>
+         <emphasis>0x4000</emphasis>: Extremely low-level tracing information.
+    </para>
+    <para>
+        To log required debug levels, simply add their numbers together as shown in following examples:
+    </para>
+    <para>
+        <emphasis>Example</emphasis>: To log fatal failures, critical failures,
+        serious failures and function data use 0x0270.
+    </para>
+    <para>
+        <emphasis>Example</emphasis>: To log fatal failures, configuration settings, function data,
+        trace messages for internal control functions use 0x1310.
+    </para>
+    <para>
+        <emphasis>Note</emphasis>: This is new format of debug levels introduced in 1.7.0.
+        Older format (numbers from 0-10) is compatible but deprecated.
+    </para>
+</listitem>
diff --git a/src/man/sssd.8.xml b/src/man/sssd.8.xml
index 185671958..e4d972c4e 100644
--- a/src/man/sssd.8.xml
+++ b/src/man/sssd.8.xml
@@ -46,13 +46,7 @@
                     <option>-d</option>,<option>--debug-level</option>
                     <replaceable>LEVEL</replaceable>
                 </term>
-                <listitem>
-                    <para>
-                        Debug level to run the daemon with. 0 is the default as well
-                        as the lowest allowed value, 10 is the most verbose mode. This setting
-                        overrides the settings from config file. This parameter implies <option>-i</option>.
-                    </para>
-                </listitem>
+                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/debug_levels.xml" />
             </varlistentry>
             <varlistentry>
                 <term>
diff --git a/src/man/sssd.conf.5.xml b/src/man/sssd.conf.5.xml
index e03805561..6f85dda9e 100644
--- a/src/man/sssd.conf.5.xml
+++ b/src/man/sssd.conf.5.xml
@@ -208,16 +208,7 @@
             <variablelist>
                 <varlistentry>
                     <term>debug_level (integer)</term>
-                    <listitem>
-                        <para>
-                            Sets the debug level for the service. The
-                            value can be in range from 0 (only critical
-                            messages) to 10 (very verbose).
-                        </para>
-                        <para>
-                            Default: 0
-                        </para>
-                    </listitem>
+                    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/debug_levels.xml" />
                 </varlistentry>
                 <varlistentry>
                     <term>debug_timestamps (bool)</term>