path: root/doc/quanta/debugging-quanta.docbook

<?xml version="1.0" encoding="UTF-8" ?>

<sect1 id="debugging-3-2">
<sect1info>
<title>Debugging in &quantaplus;</title>
<authorgroup>
<author>
<firstname>Christopher</firstname>
<surname>Hornbaker</surname>
<affiliation>
<address><email>chrishornbaker@earthlink.net</email></address>
</affiliation>
</author>

<author>
<firstname>Linus</firstname>
<surname>McCabe</surname>
<affiliation>
<address><email>Linus@McCabe.nu</email></address>
</affiliation>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>
</sect1info>

<title>Debugging in &quantaplus;</title>

<sect2 id="php-debugging-3-2">
<title>Using the &PHP; Debugger</title>

<para>
With &quantaplus; version 3.3, the debugger handling was reimplemented.
The support for the now obsolete &PHP; (3) builtin debugger and was dropped,
as was the support for the dbg debugger. Instead, a general debug plugin system
was developed, to allow different plugin implementations.
</para>
<para>
Currently only one plugin is available which adds support to use &gubed; with
&quantaplus;.
</para>
<para>
To use a debugger for your project, open the project settings and chose a suitable
debugger plugin. To alter debugger specific settings, press the 'Options' button
next to the debugger plugin drop down.
</para>

<sect3 id="php-debuggin-3-2-general">
<title>General usage</title>
<para>
Once a project has a debugger activated, a few additional items will appear in the
&quantaplus; user interface:
</para>

<variablelist>
<varlistentry>
<term>Debugger menu</term>
<listitem>
<para>
A new menu will appear where you can reach most of the debugger functionality.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Debugger toolbar</term>
<listitem>
<para>
A toolbar with access to the most common debugging commands.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Variables toolview</term>
<listitem>
<para>
A toolview where the contents of watched variables is showed. Appears in the left dock by default.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Breakpoints toolview</term>
<listitem>
<para>
A toolview where all the breakpoints, line and conditional, are listed. Appears in the bottom dock by default.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Debug Output toolview</term>
<listitem>
<para>
A toolview where the output (as in HTML) of the debugger is shown. Appears in the bottom dock by default.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
Depending on what the debugger plugin supports, all or a subset of the following functionality will be available.
</para>



<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Session</guimenuitem>
<guimenuitem>Start Session</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
This action is used to connect to the debugger if that is required, or tell the plugin to start listening for debug requests.
This action is triggered by default when a project using a debugger is opened, so usually you don't need to care about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Session</guimenuitem>
<guimenuitem>End Session</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
The opposite of
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Session</guimenuitem>
<guimenuitem>Start Session</guimenuitem>
</menuchoice>. Closes a connection to the debugger or stops listening for requests.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Send HTTP Request</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Sends a HTTP request to the server to initiate a debug request. Using this action is equivalent to
using a browser to look at the current document. The output of the request ends up in the Debug
Output dock.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Pause</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Pauses a running script
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Run</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Tells the debugger to start executing the script and send information about watched variables and current
line of execution as it goes along. If this is done while a script is paused, execution will proceed. If it's done
before a debug request is initiated, the script will start running as soon as the request is initiated.
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Leap</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Tells the debugger to start executing the script without sending information about watched variables and current
line of execution. If this is done while a script is paused, execution will proceed. If it's done
before a debug request is initiated, the script will start leaping as soon as the request is initiated.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Step</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Tells the debugger to execute the next instruction in the script, without stepping into functions or inclusions.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Step Into</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Tells the debugger to execute the next instruction in the script, stepping into functions or inclusions if possible.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Step Out</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Tells the debugger to execute until it escapes the current function.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Skip</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Tells the debugger to skip the next instruction and proceed to the next one as if the current one didn't exist.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Execution</guimenuitem>
<guimenuitem>Kill</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Tells the debugger to kill the currently running script.
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Breakpoints</guimenuitem>
<guimenuitem>Break when...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Opens a dialog where you can specify conditional breakpoints.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Breakpoints</guimenuitem>
<guimenuitem>Toggle breakpoint</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Toggles a line breakpoint at the line of the cursor in the current line
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Breakpoints</guimenuitem>
<guimenuitem>Clear breakpoints</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Clears all the breakpoints.
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Variables</guimenuitem>
<guimenuitem>Watch variable</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Opens a dialog where you can enter a variable or expression you wish to watch. The value of the watch will appear
in the variables tool view.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu>Debug</guimenu>
<guimenuitem>Variables</guimenuitem>
<guimenuitem>Set value of variable</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
Opens a dialog where you can enter a variable and a new value for it.
</para>
</listitem>
</varlistentry>



</variablelist>



</sect3>
</sect2>

<sect2 id="kxsldbg-debugging-3-2">
<title>Using &kxsl;, the &XSL; Debugger</title>

<para>
&kxsl; is the creation of Keith Isdale, as is this section of the
documentation. &kxsl; is a &kde; front-end and a KPart to
<command>xsldbg</command>, which you can find at
http://xsldbg.sf.net along with many other works by
Keith.
</para>

<para>
To start &kxsl;, select
<menuchoice>
<guimenu>Plugins</guimenu>
<guimenuitem>&kxsl;</guimenuitem>
</menuchoice>.
</para>

<para>
Please refer to the &kxsl; documentation for further information
regarding its usage.
</para>
</sect2>
</sect1>