3 — Transforming & exporting

Running a transformation asks three things: a stylesheet, an input document, an output file. Debug XML Tool guesses them to get you going quickly, then hands control back as soon as your needs become more precise.

This chapter covers the configuration dialogue, output formats, parameters, entry points, multiple outputs and saved scenarios.

3.1 Two ways to run

Without configuring anything

Open your stylesheet, press F5. Debug XML Tool fills in what is missing:

• the stylesheet is the one in the active tab;
• the XML document is the first one found in the workspace;
• the output file is generated next to the source document.

Each decision is traced in the console, prefixed [Auto-config]. It is made to get started, not to last: as soon as your workspace holds several documents, designate them.

By designating the files

Two ways, from the quickest to the most complete:

• Right-click in the explorer → Set as XML source or Set as main XSL. The status message confirms: XML source set: input.xml.
• The ⚙ dialogue (Transformation settings button), which gives access to everything.

3.2 The ⚙ dialogue

The Transformation settings button opens Transformation configuration, in six rows:

The output file is not for you to type: it is derived from the source document, the date and the format — input.xml processed as HTML gives input_out_2026-08-02.html, next to the source. It is recomputed at each change of format.

The configuration is applied only when the dialogue is confirmed, and only if it is complete. The status message then confirms: Configured: main.xsl + input.xml → HTML.

3.3 Choosing the output format

Auto is the default and imposes nothing: your xsl:output prevails. The other four override what the stylesheet declares — that is how you get a text output from a stylesheet that produces HTML, without modifying it.

The result opens in a new read-only tab. The tab is closed and regenerated at each run: what you read always matches the latest run.

Exporting to PDF

The PDF format expects a stylesheet producing XSL-FO. The file is written to disk then opened in your usual PDF viewer; the console confirms it — [PDF] Opening file in default viewer: ….

Your PDF viewer keeps the file open, therefore locked. Close it before running the transformation again or deleting the file.

3.4 Passing parameters to the stylesheet

A stylesheet declaring <xsl:param name="currency" select="'EUR'"/> can be driven from the ⚙ dialogue, without being modified.

1. Open ⚙, row XSLT parameters:.
2. Type the Name (currency) and the Value (USD).
3. Click + Param: the row joins the table.
4. Confirm, then F5.

The output reflects the value passed. While no parameter is defined, the table shows No parameter.

To remove a parameter: select its row, click − Param.

Parameters are reloaded when the dialogue is reopened and apply as much to the ▶ run as to the profiler: you therefore profile exactly the configuration you run.

3.5 Choosing the entry point

By default, a transformation starts from the source document: Saxon applies the templates to the XML document. That is the classic case, and the historical behaviour.

XSLT 3.0 allows two other starting points, both available in the Entry point: row:

Initial template

Choose Initial template and leave the name empty: Saxon invokes xsl:initial-template, the default name. Type a name to start on another template.

No XML document is needed. The XML selector becomes optional and shows (none — initial template); the output file is then derived from the name of the stylesheet. This is the mode for stylesheets that generate their content with no input — code generation, data sets, parameterised reports.

Initial mode

Choose Initial mode and type the name of the mode: execution starts in that mode rather than in the default mode.

The name is mandatory. If you leave it empty, the status message tells you so — Error: a mode name is required for the initial mode. — and your previous configuration is kept. The dialogue confirms only a usable configuration; it never wipes yours in passing.

Nothing else changes

The debugger, the profiler, back-mapping and multiple outputs work identically whatever the entry point. A breakpoint set in an initial template is reached like any other, and the call stack shows that template as the root frame.

If you name a template that does not exist, the engine error is relayed to the console and the application returns to the IDLE state — without crashing.

3.6 Stylesheets producing several files

Stylesheets using xsl:result-document are fully supported.

Each secondary output is:

• written to disk, its relative path resolved next to the main output — an href="pages/3.html" does create the pages/ folder;
• announced in the console — [xsl:result-document] Secondary output generated: …, one line per file;
• visible in the explorer, with no manual refresh;
• usable like the main output: open it from the explorer, and Ctrl+click jumps back to the generating XSLT instruction and to the source node (chapter Analysing).

A breakpoint set inside an xsl:result-document is reached normally.

A secondary file already open in a tab is closed when you regenerate: you never read a stale version.

The profiler, for its part, writes none of these outputs: profiling a stylesheet has no side effect on your files.

3.7 Saving a configuration: scenarios

A scenario is a complete configuration — stylesheet, document, format, parameters, entry point — saved under a name and re-run with one click. It is what replaces "reconfiguring the ⚙ every time" when you alternate between several production chains.

Creating

1. Click Transformation scenarios on the toolbar.
2. + New.
3. Fill in Name: (for example Catalogue → PDF Production), XSL:, XML:, Format:, and if needed the XSLT parameters: and the Entry point:.
4. 💾 Save — the dialogue closes.

The name is mandatory, as are the XSL and XML files; the application tells you rather than saving an unusable scenario.

Running

Reopen Transformation scenarios, select the scenario in Saved scenarios — the fields fill again — then ▶ Run. The transformation starts immediately, and the console announces it: --- Launching from scenario "…" ---.

Comparing with a reference

The Reference output: field is optional. Fill it in, and the Run and compare button runs the transformation then compares the result with the reference file. It is the shortest way to check that a change to a stylesheet has broken nothing — the comparison is detailed in the chapter Validating & comparing §7.6.

Deleting

Select the scenario, click 🗑 Delete, confirm.

Persistence

Scenarios are saved in the workspace and restored at the next startup. Two projects therefore each have their own.

If you create a scenario with no workspace open, the console warns you that it will be saved in your personal folder rather than in a project.

3.8 Reading the console

A nominal run leaves a complete trace:

--- Starting transformation ---
XML: C:\...\input.xml
XSLT: C:\...\main.xsl
Output: C:\...\input_out_2026-08-02.html (format: AUTO)
[HTML] Result generated: C:\...\input_out_2026-08-02.html
--- Transformation completed in 136 ms ---

Your xsl:message calls appear in between, line by line, in the order the engine produces them.

Configuration errors — no stylesheet designated, no XML in the workspace, file not found — do not go through the console: they appear in the status message on the toolbar. A useful reflex: nothing runs ⇒ read the toolbar, not the console.

3.9 Limits worth knowing

• The engine is Saxon-HE. The schema-aware transformations and the streaming of the Professional and Enterprise editions are not available.
• Back-mapping is not available on PDF export. It works on HTML, XML and Text outputs (chapter Analysing).
• The PDF format assumes a stylesheet producing XSL-FO. It does not convert HTML to PDF.
• The output path is computed, not chosen: it is derived from the source document (or from the stylesheet in the absence of a source), the date and the format.

What next

• Debugging — stop the transformation and watch what it does.
• Analysing — profiler, template coverage, output back-mapping.
• Validating & comparing — compare an output with its reference, validate a whole folder, run XSpec tests.