[kde-doc-english] doc contest: kdebugdialog

[Adriaan de Groot]

<!-- DocBook-style comments and fake (partial) markup included -->

<section><title>KDebugDialog - Controlling KDE's Debugging Output</title>

KDE has extensive debugging support; nearly every application can produce a 
mountain of debugging output to help you or the developers track down where a 
problem occurs. Turning that mountain back into a molehill <!-- perhaps too 
idiomatic, then use "Managing that mountain of output" --> is kdebugdialog's 
task. By default, all the debugging output is discarded, and it will not 
clutter up your shell windows or .xsession-errors file<!-- footnote: well, it 
depends on your distribution, really -->.

Each application in KDE is assigned a number of debug areas to which it writes 
its debugging output. These debug areas correspond roughly to the various 
parts of the application -- for instance, kontact has three areas, one for 
its core, one for debugging output related to the loading of plugins, and one 
more for interface-related output. Some "hidden" parts of KDE also have debug 
areas assigned -- various libraries and technologies you normally don't see 
on your desktop like the netscape plugin scanner. Each debug area can be 
controlled individually, so that you can fine-tune the debugging output that 
you get to see. This is most useful when you are trying to track down a 
problem in something specific and do not want to see the whole mountain.

The kdebugdialog application can be used in two different modes: the default 
mode allows you to switch a particular debug area on or off; an advanced mode 
lets you do real fine-tuning like sending warning messages to a file while 
discarding regular debug messages. We will examine each mode in turn.

<subsection>
<title>KDebugDialog in plain mode</title>

KDebugDialog is not in the K menu by default. You will need to run it from the 
shell or from the mini-CLI <!-- link to CLI, for sure --> with the command 
<literal>kdebugdialog</literal>. KDebugDialog pops up a window with a long 
list of debugging areas. Each area has a checkbox that you can check or 
uncheck <!-- perhaps select/deselect --> in order to enable or disable 
debugging output for that part of KDE.

The list of debugging areas is sorted numerically, not alphabetically, so kio 
(127) comes before artskde (400). The numbers go up to 200000 or so, but 
there are really only 400 areas. You don't have to scroll through the entire 
list to find the area you need, though. There is a line edit <!-- 
text-entry ? --> box at the top of the dialog where you can enter a part of 
the name of the area you want. The list of entries that is displayed is 
filtered to include only those debug areas that contain the text you have 
entered. E.g. entering "k" does not filter very much at all, but entering 
"kont" <!-- that's "butt" in dutch, haha --> will show you just the kontact 
debugging areas. As an even quicker way of enabling or disabling debugging 
output, there are also "select all" and "deselect all" buttons which will 
cause KDE to produce a mountain of debugging output, or very little.

</subsection>



<subsection>
<title>KDebugDialog in full mode</title>

<!-- this text partly taken from the kdebugdialog handbook -->

In full mode, which is what you get when you start kdebugdialog as 
<literal>kdebugdialog --fullmode</literal>, the same list of debugging areas 
as in plain mode is available, but you can select only one at a time from a 
drop-down <!-- combo? --> box. You maythen  independently set the output for 
various types of messages:
Information, Warning, Error and Fatal Error. For each of these types, you can 
choose where the messages are sent. The choices are:

File, in which case you can enter a filename. This file is written into your 
$HOME directory.

Message Box. Each debugging message is displayed in an information dialog, 
which you must OK to continue with the application.

Shell, the default entry. Messages are printed to stderr, and will appear 
either in the shell window where the application was started, or 
in .xsession-errors.

Syslog. This sends each debugging message to the system's syslog facility, 
which can perform its own processing of the message.

None. This suppresses the output of this type of message.

For messages generated by  fatal errors, it is generally a bad idea to choose 
None or Syslog, since in both cases you most likely will not see the message 
and the application that encounters the fatal error will vanish without 
leaving a clue as to why it vanishes. Whether or not the application will 
vanish on fatal errors can be controlled by the checkbox "abort on fatal 
errors", which is checked by default -- but you might expect an application 
to crash (in a messy fashion) if a fatal error is encountered anyway.


</subsection>
</section>



<!-- PhilRod: there, serves you right for mentioning it while I was waiting on 
a compile job -->


-- 
Don't worry, 't ain't no shame to be stupid - ol' mouse.
    GPG: FEA2 A3FE Adriaan de Groot