-*- mode: outline -*-

* Introduction

Since the version number of 0.96 Sablotron supports a debugging of
stylesheets. Although it is just an experimental state, it works quite
fine, and may be found useful by many XSLT developers.

* License

!!! Important change, read this !!!

The Sablotron library is dual-licensed. You may choose either of MPL
or GPL.

Optionally the debugger command line interface uses a great GNU library
'readline'. This library may not be linked to non GPL'ed programs, so
if you want to use the debugger, you have to choose the GPL from
Sablotron license model.

See the *Building* section, how to do it.

* Building

For short, all you need is to pass the --enable-debugger to the
configure script. If you want to use the readline library (what is
great), read the detailed description.

To enable the debugger, you need meed following:

1. Optionally you may install ``readline'' and ``ncurses'' libraries
   of GNU. (nice systems have it by default) and make it available to
   the compiler and linker (you may use CPLUS_INCLUDE_PATH and
   LIBRARY_PATH environment).

2. If you want to use the readline library, you have to confirm, that
   you accept the GPL license terms. You do it with setting the
   SABLOT_GPL environment to whatever else then empty string. You need
   set this variable when the configure script is ran (later it is not
   needed).

3. You have to add the --enable-debugger to the configure script.

4. Optionally you may set the --with-readline too.

That should be enough.

* Invocation

Run 'sabcmd --debugger'. That's all.

* Features

You may trace, how your templates are executing. The only point, where
the debugger may stop the execution is the element start.

** Setting the Data

The first thing, you need to do is to specify the stylesheet and the
data file. Use the `sheet' and `data' commands for it.

If you want to set external parameters (for top level <xsl:param>
elements) use the `param' command.

** Running the Transformation

Use the `run' command to fire the processor. A new processor instance
is created for any new round.

If the debugger stooped at the breakpoint, you may use the `cont'
command to run further.

You may use the `templ' command to run the processor and stop in the
first template called.

If you want to kill currently running transformation, use the `kill'
command.

** Setting Breakpoints

You may use the `break' command to set the breakpoint. Processor then
stops on marked line every time it hits it.

There are some issues: 

  - breakpoint must be set at the line with the element start

Another command are `B' - list all breakpoints and `D' delete all
breakpoints.

You may toggle a breakpoint enabled/disabled with the `disable'
command.

You may set a XPath expression for the breakpoint, what is evaluated
each time the breakpoint is met. The breakpoint takes an effect only
if this expression is true.

** Walking Trough the Source

You may use the `step' command to move to the next element start.

You may use the `next` command to move to the next sibling of the
current element.

You may use the `finish' command to move to the next sibling of the
parent of the current element.

Suppose:

<xsl:template>
  <a>
->  <b>
      <c/>
      <d/>
    <b>
    <d/>
  <a>
  <x/>
</xsl:template>

The arrow marks, where you are. In this case

`step'   - goes to <c>
`next'   - goes to <d>
`finish' - goes to <x>

The very special (and very useful) command id the `templ'
command. This one continues the execution, until any template is
executed. It may be used to run the transformation as well as to resume
stopped execution.

** XPath Evaluation

You may evaluate any XPath expression using the `eval' command. It
evaluates in the current context and displays the result and its type.

** Examinig the Context

You may examine the current context with the `x' command.

x     - shows brief info
x all - list all context nodes
x n   -  detailed info on the n-th context node (n is an integer)

** Batches

You may create files containing the sequences of you favorite commands
(one per line) and execute them with the `batch' command

** Abbreviations

You need to type as few letters to specify the command as is needed to
recognize, what you mean. The most frequent command may be run with
single command not caring, whether another command starts with this
letter. The `s' abbrev runs the `step' command rather the `sheet'.

* Emacs Integration

There is an Emacs library available. You may use it, if you want to
debug your stylesheets and see, what is happening.

You need to grab the sabdbg.el from the Sablotron source tree.

Next you need to put something like this into your .emacs file:

(load "sabdbg.el")
(sabdbg-set-keys)

The sabdbg-set-keys function should be called the best from some hook
for your favorite xsl mode.

We use the xml-mode (part of psgml-mode). My .emacs looks like this:

(add-hook 'xml-mode-hook 
	  (function (lambda ()
		      ;;set debugger staff
		      (when (string-match "\\.xsl$" buffer-file-name))
                      (sabdbg-init))))

As the result several keys should be mapped locally in you buffers for
the XSL files.

(local-set-key [(control c)(control g)(control x)] 'sabdbg-debug-current)
(local-set-key [(control c)(control g)(control s)] 'sabdbg-step)
(local-set-key [(control c)(control g)(control n)] 'sabdbg-next)
(local-set-key [(control c)(control g)(control t)] 'sabdbg-step-template)
(local-set-key [(control c)(control g)(control c)] 'sabdbg-continue)
(local-set-key [(control c)(control g)(control p)] 'sabdbg-show-point)
(local-set-key [(control c)(control g)(control b)] 'sabdbg-set-breakpoint)
(local-set-key [(control c)(control g)(control r)] 'sabdbg-run)

E.g. while you are in the buffer holding the XSL file, you may press
and hold control and press `c' `g' `x' sequence to execute the
debugger and set the current buffer file name as the stylesheet.

Next you need to use the `data' command in the debugger buffer, switch
back to the stylesheet and continue debugging using mapped keys.

sabdbg-debug-current
  opens debugger for current buffer (only one debugger may be ran at once

sabdbg-step
  steps the debugger

sabdbg-next
  preform the `next' command

sabdbg-step-template
  perform the `templ' command

sabdbg-continue
  continues the execution

sabdbg-show-point
  synchronize file displayed with debugger

sabdbg-set-breakpoint
  sets breakpoint to file and line, where currently the point is

sabdbg-run
  runs processor