MAN: Clarify debug level documentation

Originally, we planned to deprecate the decimal values for the debug
levels, but that has proven to be too difficult for most users to
understand. Instead, we will document both the simple decimal and
complex bitmask values and recommend the use of the decimal values.

1 files changed, 20 insertions, 6 deletions

diff --git a/src/man/include/debug_levels.xml b/src/man/include/debug_levels.xml
index ce506405..14e666c7 100644
--- a/src/man/include/debug_levels.xml
+++ b/src/man/include/debug_levels.xml
@@ -1,49 +1,61 @@
 <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.
+        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 debug levels, simply add their numbers together as shown in following examples:
+        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,
@@ -54,7 +66,9 @@
         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.
+        <emphasis>Note</emphasis>: The bitmask format of debug levels was introduced in 1.7.0.
+    </para>
+    <para>
+        <emphasis>Default</emphasis>: 0
     </para>
 </listitem>