Usage documentation
Version: 4.7.0
Copyright © 2002- Keith Isdale
Abstract
qxsldbg is a provides a graphic user interface front end to xsldbg; which supports debugging of XSLT scripts via API added to the libxslt library.
For details of license and contributers see the Chapter 4, Credits and Licence section.
A good deal of effort has been put into
- creating a XEmacs front end called xsldbg-mode.
- creating a Qt5 front end called qxsldbg.
- creating a kate plugin(KF5/Qt5) called kxsldbg.
For details of recent changes see qxsldbg ChangeLog file.
Table of Contents
- 1. Introduction
- 2. Installation
- 3. Using qxsldbg
- 4. Credits and Licence
List of Tables
Table of Contents
Provides access to most of xsldbg commands to
-
Set and modify breakpoints
-
Display value of expressions
-
Display in formation about breakpoints, templates, variables, callstack, stylesheets and entities found
-
Move around XSL source and XML document via XPaths
-
Lookup PUBLIC and SYSTEM ID's in the current XML catalog
Table of Contents
Table 2.1. Required libraries
| pthread | not needed under WIN32 |
| xsldbg | supplied by xsldbg, part of qxsldbg package 4.5.0 or later |
| qtnotifer | supplied by xsldbg, part of qxsldbg package 4.5.0 or later |
| ncurses | optional, not needed under WIN32 |
| readline | optional, not needed under WIN32 |
| history | optional, not needed under WIN32 |
| Qt | QT5.5 or greater |
| xml2 | supplied by libxml2 |
| xslt | supplied by libxslt and libxslt has XSLT debuging support enable (done by default) |
| exslt | supplied by libexslt |
Table of Contents
Start qxsldbg from "Development" Desktop menu or where it was compiled.
Click the
(Configure) button in tool bar.In the dialog that now is visable choose the xsldoc.xsl as the "XSL source", xsldoc.xml as the "XML data file", and dump.txt as the "Output file".
Click the "Apply" button on the dialog.
Click the
(Run) button in toolbar to update qxsldbg with the new configuration.Click the
(Step) button on the toolbar and xsldoc.xsl will display with the cursor at the first debuggable line in xsldoc.xsl. Press the "Continue" toolbar button and xsldbg will run the stylesheet and stop at the first debuggable line in xsldoc.xsl.Click the
(Continue) button to contiue running XSLT transform to the end.Click the
(Output) button on toolbar to view result of XSLT transform.To reload the current file displayed use the
(Refresh) toolbar button.The result of last execution of the stylesheet will be shown in Xsldbg Outut window, by default docked at the bottom of screen.
Once the XSLT engine has reach its first *valid* node you can enter any valid XPath expression in the field next to a "Evaluate" button
For example, using "XPath query" box enter $xsldbg_version and press the "Evaluate" button, after a moment the value of $xsldbg_version will be displayed.
You start configuration by clicking the(Configure) button in the toolbar
| The dialog show below then is displayed |
 |
To be able to run a stylesheet you need to specify the
XSL source
XML data
Output file
By using the ".." button to choose file desired. Be sure to check that the "Output file" is not the same as the other files.
To follow along with the examples
For the XSL source use <qxsldbg root>/tests/test2.xsl
For XML data use <qxsldbg root>/tests/test2..xml
For Output file use dump.txt
You can select zero or more options from the "Options". Each option has a tool tip with a hint on what effect it has.
You can add zero or more parameters via the "Libxslt parameters" section of dialog. This allows you to provide parameter values to the stylesheet
For example if you had a stylesheet like addparam.xsl you could add a parameter called myparam with a value of Hello World!. To update the value of an existing parameter just add it again with the new value desired. ( Hint: To view addparam.xsl use the right mouse button and choose a text editor to view file. )
qxsldbg provides a text view of the current file being debugged,as seen in the image below
In the text viewer the following indication are used to show execution/cursor focus
the next line be executed is highlighted with a green background
the cursor position is shown via underline text style or a flashing cursor
There are two coloured markers that are can show up on the start of a line of text
A red mark: Indicating an active breakpoint
A yellow mark: Indicating a disabled breakpoint
To set/disable/delete a breakpoint at the start of a XML node by *double* click of left mouse button.
To move the cursor arround the text use the
Arrow keys: left, right, up, down
Page keys: page up, page down
Most of the output from xsldbg is captured and presented either in the inspectors dialog or the xsldbg output window. The exceptions to this rule are
-
An error message that comes from xsldbg is displayed inside a message dialog.
The result of evaluating an expression is displayed in a message dialog
The output of search is sent to the file indicated in the xsldbg output window
Table 3.1. Tool bar icons and thier meaning
|
| Configure application see: the section called “Configure the files, options and parameters to use” |
 | Open inspector dialog showing data obtained from xsldbg. |
|
| Restart execution applying current configuration |
|
| Continue execution stoping at next breakpoint. This will cause the debugger to stop at the start of the stylesheet if no further breakpoints are found |
|
| Step to the next XSLT instruction found. |
 | Proceed to the next instruction at the same call stack depth. This is useful for stepping over a xsl:appply-templates or xsl:call-template |
 | Proceed to the next instruction in a cooler stack frame. This is best used within a template at a greater depth than the root match template |
 | Proceed to the next instruction in a warmer stack frame. |
 | Add a breakpoint at the current cursor location |
 | Enable or disable a breakpoint at the current cursor location |
 | Delete a breakpoint at the current cursor location |
 | Cause the current XSLT source file to be shown |
 | Cause the current XML data file to be shown |
|
| Cause the current Output file to be shown |
|
| Cause the displayed file to be reloaded from disk |
The primary way to work with breakpoints is via the main window see the section called “Using the main window”
Once you have started the stylesheet you can use the Tools->Show inspectors menu item. Then click on the "Breakpoints" tab. See below for an example |
 |
To add a breakpoint in Inspector dialog supply either
a file and line number of *either* XSLT script being debugged *or* XML data file being transformed by XSLT script
a template name
a template name and a mode name
a mode name
And then pressing the "Add" button
A file name may be absolute path to a local file or 'basename' for file eg: test2.xsl
A template or mode name supports fully Qualified Name where the non-local part is optional eg. xsl:mytemplate is matched by mytemplate
Firstly left mouse click the breakpoint you want to delete in the list of current breakpoints. Then click the "Delete" button.
All call stack items found are listed here. The older the callstack entry the lower the frame number it will have.
Note that clicking on a callstack entry in the list shown will cause the cursor in the main window to move to the file and line number indicated.
See below for an example of "Call Stack" tab
If the inspector dialog is not showing use the Tools->Show inspectors menu item. To work with templates click on the templates tab of dialog shown
All templates found are listed here. Please note that the export rules of XSLT apply. So only there may be more than one template with the same match and mode details. xsl:param. Clicking on a template entry in the list shown will cause the cursor in the main window to move to the file and line number indicated.
To find a the template enter a partial *or* full name of template into the "Template name" field then click the "Search" button. To reset template view to defaults clear value from the "Template name" field.
See below for an example of templates page within Inspector
Local and global XSLT variables are show in separate tabs on the inspector dialog.
If the inspector dialog is not showing use the Tools->Show inspectors menu item.
Note that clicking on a variable entry with known file name/line number will cause the cursor in the main window to move to the file and line number indicated.
To see value of expression
Enter XPath expression in "Expression" field
Click "Evaluate" button
The Global variables tab shows XSLT variables that are global in scope (defined outside of a template).
See below for an example the "Global Variables" tab
The Local variables tab shows XSLT variables that are local in scope (available within a template).
Some variables can be edited via
Selecting variable in list
Enter new value in "Variable expression" field
Clicking "Set Expression" button
See below for an example the "Local Variables" tab
If the inspector dialog is not showing use the Tools->Show inspectors menu item. To work with sources click on the sources tab of dialog shown
All XSLT source files that are included by the XSLT file or one of its simblings are listed here. See below for an example
Clicking on a source entry in the list shown will cause the cursor in the main window to move to the start of file indicated.
If the inspector dialog is not showing use the Tools->Show inspectors menu item. To work with entities click on the Entities tab of dialog shown
All external XML entities included via the DATA file or one of its siblings are listed here. For this example I have run qxsldbg on test14.xsl with test14.xml (found in the tests directory of xsldbg source distribution) so that you can see some entities. See below for an example
Clicking on a entity entry in the list shown will cause the cursor in the main window to move to the start of the file indicated.
Several tools are available via the tools menu, the main tool is the inspector tool.
The inspector tool is the contains all the individual dialogs for working with
Breakpoints
Global Variables
Local Variables
Callstack entries
Templates
Source files
XML Enties
By clicking on "Start execution with walking" menu a dialog is shown to allow the walk speed to be chosen
To stop walking either use the "W" key or select the "Stop execution with walking" menu item
By clicking on "Start execution with tracing" this will cause XSLT transformation to run completely with resulting output shown in "Xsldbg Output" window. See also the section called “Working with xsldbg output”
To tracing select the "Stop execution with walking" menu item
To lookup a System ID in the current XML catalog use the "Lookup System ID" menu then enter path of entity to find such as "notemessage2.xml"
The writers of libxml and libxslt for their support in adding debugging to libxslt.
Robert JACOLIN for feedback on earlier version of qxsldbg
Igor Zlatkovic for creating WIN32 binaries of libxml/xslt and xsldbg