Table of Contents 
xsldbg is a text based tool to debug stylesheets and it is similar to the Unix/Linux debugger gdb. It uses using the libxslt library by http://www.xmlsoft.org/XSLT
- It is in the second beta stage of development with functionality now frozen until the start of the next beta cycle. Comments about feature set provided are welcome.
- add the ability to list documents created by xsl:document instruction (maybe?)
- complete support all XSL commands : Done? Needs more testing
- perform testing, add more test case descriptions
- improve the appearance of documentation and ensure it is up to date
- Create script to autogenerate def file (needed to create a win32 dll) using
sgml files created by GNOME documentation tool. (maybe?)
- Look at replacing execution of shell command "more" with a function call
- Look at allowing xsldbg to extract comments from XSL files to provided similar functionality
as XSLTDoc tool by Fabrice Desré. At the moment the libxslt preprocessor strips most comments (maybe?)
See also completed TODO'S
libxml2-2.4.23 from GNOME cvs or greater
libxslt-1.0.20 from GNOME cvs or greater
Warning! libxslt may not compile with shared library enabled as it is has been configured
for compilation tools that support prelinking. Configure libxslt with the at least following option
--with-debugger=yes
I recommend you get the latest available for your distribution. Try
libxslt rpmfind search.
libxml rpmfind search.
A system with GNU compatible make and build tools
The "more" system command is available (need by internal help system)
OR
A WIN32 system with MSVC 5.0 or later, using project files by
Igor Zlatkovic
- The format of search results needs to be fixed
- The stepup command is not accurate
- Searching can take a while with large documents ie when debugging docbook.xsl
- Both the stylesheet and xml data file will be reloaded each time xsldbg starts a "run".
It is too complex to complex considering keeping track of which files are out of date
- Libxslt and consequently xsldbg can't handle NON_ASCII template matches
- If an environment variable is used to indicate where you've installed
xsldbg's documentation the vaiable value MUST end in a path separator
ie for win32 this is a '\'
for *nix this is a '/'
- The SGML/XML catalogs provided are to be included as a "nextCatalog" in your
catalog file. Otherwise you'll get warnings about unable to find
xsldbg's DTDs
- The new search DTD allows for each element to have a comment to be extracted from
the XSL source libxslt currently does not support this function
- Under win32 the more command does not process a ".\<FILE_NAME>" properly
- When a non ASCII character are used stylesheets the printing of search results does not print
in the orginal encoding (instead uses UTF-8 ). This will be resolved if/when a replacement for
the more command is made
The primary author is Keith Isdale
The author for the riscos specific code is Justin Fletcher
The author for the MSVC project files and some of the WIN32 code is Igor Zlatkovic
This tool is available under the GPL licence
Program usage and commands
xsldbg thread usage
Running xsldbg-mode under XEmacs in Linux and WIN32
Running the qxsldbg under KDE, it will look similar under
under windows or cygwin .
Running the xsldbg plugin in Quanta+.
http://xsldbg.sourceforge.net/
http://sourceforge.net/projects/xsldbg
http://xsldbg.sourceforge.net/docs/qxsldbg/manual/, the qxsldbg manual
http://homepage.ntlworld.com/justin.fletcher/XML/ (Homepage for author or risc os port of xsldbg)
XSL documentation tool by Fabrice Desré
http://lists.sourceforge.net/lists/listinfo/xsldbg-announce
http://lists.sourceforge.net/lists/listinfo/xsldbg-users
http://lists.sourceforge.net/lists/listinfo/xsldbg-devel
Extract the latest stable version of xsldbg from http://sourceforge.net/project/showfiles.php?group_id=35673
In cvs , for example, the 3.1.0 release is tagged "rel-3-1-0" in cvs. See website for details of the latest stable release.
Below is the installation instructions for a default *nix system
make -f Makefile.cvs
./configure
make
make install
Do a
./configure --help
for details of other options to configuring xsldbg
Warning!
It is expected that
- xsldbg has been added to your PATH of system commands.
- libxml AND libxslt have been fully installed and are available to xsldbg.
- xsldbg's DTD's (search.dtd, xmldoc.dtd, config.dtd) have been added to your SGML/XML catalog file.
The default *nix installation will do these things for you (for the the assumed default *nix configuration) but other operating systems
have thier own installation requirements.
To test / try out xsldbg
cd xsldbg/docs/en
xsldbg --shell xsldoc.xsl xsldoc.xml
And you should get the xsldbg prompt like
XSLDBG <VERSION>
Starting stylesheet
Breakpoint at file xsldoc.xsl : line 18
xsldbg) xsl:param >
You can now start entering commands at the "(xsldbg) .* >" prompt. In the example text in
green has been typed by the user
Breakpoint at file xsldoc.xsl : line 18
(xsldbg) xsl:param > templates
template :"/" in file xsldoc.xsl : line 23
template :"helpOnCommand" in file xsldoc.xsl : line 49
template :"header" in file xsldoc.xsl : line 67
template :"text()" in file xsldoc.xsl : line 79
template :"para" in file xsldoc.xsl : line 83
template :"list | usage" in file xsldoc.xsl : line 89
template :"comment" in file xsldoc.xsl : line 99
template :"cmd-summary" in file xsldoc.xsl : line 103
template :"cmd" in file xsldoc.xsl : line 109
Total of 9 templates found
Total of 9 templates printed
(xsldbg) xsl:param > break /
Size of line list was 0 adding 24 entries
(xsldbg) xsl:param > break header
Size of line list was 24 adding 44 entries
(xsldbg) xsl:param > showbreak
Breakpoint 1 enabled for template :"/" in file xsldoc.xsl : line 23
Breakpoint 2 enabled for template :"header" in file xsldoc.xsl : line 67
Total of 2 breakPoints present
(xsldbg) xsl:param > break -l xsldoc.xsl 44
(xsldbg) xsl:param > showbreak
Breakpoint 1 enabled for template :"/" in file xsldoc.xsl : line 23
Breakpoint 3 enabled in file xsldoc.xsl : line 44
Breakpoint 2 enabled for template :"header" in file xsldoc.xsl : line 67
Total of 3 breakPoints present
(xsldbg) xsl:param > continue
Reached template :"/"
Breakpoint 1 Breakpoint in file xsldoc.xsl : line 23
(xsldbg) xsl:template > continue
Reached template :"/"
Breakpoint 1 Breakpoint in file xsldoc.xsl : line 23
(xsldbg) text > continue
Reached template :"header"
Breakpoint 2 Breakpoint in file xsldoc.xsl : line 67
(xsldbg) xsl:template >exit
To print help just type "help"
To exit xsldbg just type "exit"
Start Quanta as normal. On the toolbar select the "XslDebug" tab. Click the
"configure" button on the Xsldbg toolbar tab.The Xsldbg inpector/configure dialog
will then display. Choose the XSL source, XMLData and Output files using the ".."
buttons. Click the "Apply" button, then click the "Run" button on the Xsldbg
toolbar tab. You are now able to use the other button on the Xsldbg toolbar
tab to set/delete/enable breakpoints.
To set a break point move the cursor to where you want a breakpoint then click the
"Add a breakpoint" button Xsldbg toolbar tab. Alternatively you can enter the
details of where you want the breakpoint into the "Breakpoints inspector"
Open an XML file into a buffer, then press <META>-x followed by entering
"xsldbg-buffer" into the dialog xemacs provides. At the first prompt enter the file name of
stylesheet to use. At the prompt for "Parameters" enter any extra parameters that
you would normaly provide to xsldbg via the command line
After xsldbg-mode initializes you will have cursor highlighting the first line
that xsldbg can debug. Use the right mouse button, the toolbar icon's or enter commands
direclty into xsldbg's command prompt. The right mouse button menu can be called up on
text that is "highlighted"
To set a breakpoint you can print the list of templates and then right mouse click
on the template name listed that you want to stop at. Or move the cursor to where
you want a breakpoint (The start of a node in the XSLT source or XML DATA) then click
the "Stop at selected postion" icon.
The "Stop at selected function" button at the moment operates exactly the same as
the "Stop at selected postion" icon.
xsldbg is has built using xml/xslt. To help an overview of commands type
help
You can use "help" to get a more detailed information about a command eg
help help
See release notes associated with package.
These issues are still current
1) Several of the File related commands are disabled for the moment.
2) When you do a cat on the style source the output is white space stripped so it will look different to
your original source files. This is NOT a "bug"! This is the default behaviour of the stylesheet processor of libxslt. This
tool is intended to be used by other programs which can handle formatting the output.
Libxslt doesn't compile
- Check http://xmlsoft.org/XSLT/ and mail.gnome.org/archives/xslt/ for current issues
- Ensure that libxslt was configured with at least
--with-debugger=yes
Where can I find a binary distribution for xsldbg
Sorry I am not able to do that at this time, as I'm not sure how to make a generic
binary that would not come back and haunt me. :-) A submission by someone who can do this would be
most welcome.
Where's the documentation
Plain html documenation is built by default and is found in the <XSLDBG_COMPILE_DIRECTORY>/docs/en/plain
directory. You can generate either KDE or GNOME style during a compile of xsldbg. Use
./configure --help
To find out how to do that.
xsldbg compiles ok but doesn't run when used from command line/ does not start debugging
- Make sure that you set and exported the correct LD_LIBRARY_PATH
- Make sure that you've configure the correct libxml and libxslt prefix in libxslt, and xsldbg. Check the values supplied to
- Make sure that you have a version of libxslt that has debugging support enabled
this is done by default un *nix but it handled manualy under other platforms
--with-libxslt-prefix
--with-libxml-prefix
Why do I get a message about Breakpoint @ text node
xsldbg tries to find a line number near the current node. But sometimes it is
unable to find a "parent" for the current node. This normally means the node is part of
the document preamble, a comment node or text node.
In the Quanta+ plugin why to I get messages about text being too big to display
The plugin for Quanta+ is in its first beta. It is expected that future development will
re-organise the "inspector" windows.
Why does xsldbg restart when I reload the configuration
This is unavoidable because of the way xsldbg interupts libxslt execution.
Why is the text/html output when searching not better formmated
It is left up to the user to provide a stylsheet to replace
docs/en/searchhtml.xsl and docs/en/search.xsl. Contributions of better XSL for
search database formatting would be appreciated
How big is this program
At last count there was over twenty thousand lines of text in xsldbg, some of this is
automaticaly generated. This is about the same size as the libxslt directory in the
libxslt distribution.
Why do I get a strange prompt
If the prompt looks like:
(xsldbg) xsldbg_default_node >
For some reason xsldbg could not load or use the specified stylesheet or xml data file.
Try using the "source" or "data" commands and then "run".
What's the deal with all those USE_KDE_DOCS, USE_GNOME_DOCS, BUILD_DOCS
They are a mechanism used by docs/en/KDE/Makefile.am and docs/en/GNOME/Makefile.am
to generate API documenation in the style of KDE and GNOME respectively.
For problems with this project or web site please use the bug tracking system provided by Source Forge
See sourceforge file downloads
See Win32 binaries WIN32 provided by Igor Zlatkovic
- create project files to build as MSVC project. Being looked at by Igor Zlatkovic Done !
- Create a patch for kDbg to support xsldbg. Done! Prototype available on web site
- validate the breakpoint API is complete :Done!
- Update xsldbg when debugger support is built into libxslt. Done! libxslt only contains the code needed to call xsldbg. No further review by libxslt@gnome.org needed but may be done :-)
- add the ability to validate file and line number
- Redo configure and build scripts : Done!
- Track down all sources of the crashes :-( : Done!
- Complete line break points : Done!
- Update documentation : Done!
- Work on a patch for the xemacs module xslt-process to support debugging from within xemacs : Done! (modified gdb.el)
- Create new functions to handle lists that are implemented as arrays. Done!
- Break points to a specific line in the stylesheet are yet made stable : Done!
- The debugger suffers from crashes "segmentation faults" which is being looked into : Fixed
- The configure/build scripts need to be redone because they expect KDE to be installed : Done!
- Confirmed that only the basic XSL/XSLT commands work. Which means that it may not stop where expected. Done!
- Can only handle a fixed number of breakpoints. Fixed!
- Does not handle a large number of variables/templates well. Fixed!
- Does not allow libxslt parameters to be passed at xsldbg command prompt. Done!
- Redo implemention of src/dbgbreakpoint.c to use hash tables not a fixed array of breakpoints Done!
- Add new search functions Done!
- Add ability to change variables Done!
- Only simple simple XSL commands are supported as yet.: Fixed!. But yet to verify that all commands work as expected
- Allow xsldbg's configuration to be loaded/saved . Done!
http://xsldbg.sourceforge.net/ : Helping understand stylesheets
Last updated 16th Feb 2003