sss_override: improve --debug description

Resolves:
https://fedorahosted.org/sssd/ticket/2813

Reviewed-by: Justin Stephenson <jstephen@redhat.com>
(cherry picked from commit 11540d9efb85b9ed0341e8a1fc97fc078c6ce418)

3 files changed, 83 insertions, 1 deletions

diff --git a/src/man/include/debug_levels_tools.xml b/src/man/include/debug_levels_tools.xml
new file mode 100644
index 000000000..631e19d39
--- /dev/null
+++ b/src/man/include/debug_levels_tools.xml
@@ -0,0 +1,81 @@
+<listitem>
+    <para>
+        SSSD supports two representations for specifying the debug level. The
+        simplest is to specify a decimal value from 0-9, which represents
+        enabling that level and all lower-level debug messages. The more
+        comprehensive option is to specify a hexadecimal bitmask to enable or
+        disable specific levels (such as if you wish to suppress a level).
+    </para>
+    <para>
+        Currently supported debug levels:
+    </para>
+    <para>
+         <emphasis>0</emphasis>,
+         <emphasis>0x0010</emphasis>:
+         Fatal failures. Anything that would prevent SSSD from starting up or
+         causes it to cease running.
+    </para>
+    <para>
+         <emphasis>1</emphasis>,
+         <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>2</emphasis>,
+         <emphasis>0x0040</emphasis>: Serious failures. An error announcing
+         that a particular request or operation has failed.
+    </para>
+    <para>
+         <emphasis>3</emphasis>,
+         <emphasis>0x0080</emphasis>: Minor failures. These are the errors that
+         would percolate down to cause the operation failure of 2.
+    </para>
+    <para>
+         <emphasis>4</emphasis>,
+         <emphasis>0x0100</emphasis>: Configuration settings.
+    </para>
+    <para>
+         <emphasis>5</emphasis>,
+         <emphasis>0x0200</emphasis>: Function data.
+    </para>
+    <para>
+         <emphasis>6</emphasis>,
+         <emphasis>0x0400</emphasis>: Trace messages for operation functions.
+    </para>
+    <para>
+         <emphasis>7</emphasis>,
+         <emphasis>0x1000</emphasis>: Trace messages for internal control
+         functions.
+    </para>
+    <para>
+         <emphasis>8</emphasis>,
+         <emphasis>0x2000</emphasis>: Contents of function-internal variables
+         that may be interesting.
+    </para>
+    <para>
+         <emphasis>9</emphasis>,
+         <emphasis>0x4000</emphasis>: Extremely low-level tracing information.
+    </para>
+    <para>
+        To log required bitmask 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>: The bitmask format of debug levels was
+        introduced in 1.7.0.
+    </para>
+    <para>
+        <emphasis>Default</emphasis>: 0
+    </para>
+</listitem>
diff --git a/src/man/po/po4a.cfg b/src/man/po/po4a.cfg
index 6dbf11906..5708318bc 100644
--- a/src/man/po/po4a.cfg
+++ b/src/man/po/po4a.cfg
@@ -33,6 +33,7 @@
 [type:docbook] include/param_help.xml $lang:$(builddir)/$lang/include/param_help.xml opt:"-k 0"
 [type:docbook] include/param_help_py.xml $lang:$(builddir)/$lang/include/param_help_py.xml opt:"-k 0"
 [type:docbook] include/debug_levels.xml $lang:$(builddir)/$lang/include/debug_levels.xml opt:"-k 0"
+[type:docbook] include/debug_levels_tools.xml $lang:$(builddir)/$lang/include/debug_levels_tools.xml opt:"-k 0"
 [type:docbook] include/experimental.xml $lang:$(builddir)/$lang/include/experimental.xml opt:"-k 0"
 [type:docbook] include/local.xml $lang:$(builddir)/$lang/include/local.xml opt:"-k 0"
 [type:docbook] include/seealso.xml $lang:$(builddir)/$lang/include/seealso.xml opt:"-k 0"
diff --git a/src/man/sss_override.8.xml b/src/man/sss_override.8.xml
index ef73aee98..1e741e741 100644
--- a/src/man/sss_override.8.xml
+++ b/src/man/sss_override.8.xml
@@ -266,7 +266,7 @@
                     <option>--debug</option>
                     <replaceable>LEVEL</replaceable>
                 </term>
-                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/debug_levels.xml" />
+                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/debug_levels_tools.xml" />
             </varlistentry>
         </variablelist>
     </refsect1>