6. Error recovery. When it goes wrong

Rather fake, but in order to find and correct errors it is necessary to see how they are reported. Two potential sources of errors are possible. Firstly in the source XML document. It could be either syntax or validity. Secondly, an error in the input to IREn. Often generated by an XSLT conversion, where the properties are mis-used. IREn has a tool to validate this input and isolate the source of the error.

Firstly then the source code error. Open the hammer.xml file, near the top there is an annotation element. Modify the markup as shown below

 <annotation>
    <p>
      The purpose of this document is to illustrate handling complex
      layout patterns in the Extended Stylesheet Language (XSL).
      To simulate a real text, I have written an operation instruction
      for a hammer. The genre of operation instructions turned out
      to be quite convenient for showing most standard formatting
      properties. Features used in this text include:
    </b>

The closing p tag has been replaced by a b tag. The structure is now unbalanced, in a manner that is called not well-formed. Run this through either Assistant, or the command line IREn. Assistant produces the following report.

[error] javax.xml.transform.TransformerException: \
org.xml.sax.SAXParseException:                    \
unexpected characters in element end tag (expected "p")

Again the lines are split using the \ character, where on the screen they are on a single line.

The message is clear. The software expected an end tag of p, and didn't find one. No indication of where though. For a long document this is a problem. For shorter ones perhaps your XML editor of choice can help you.

If you have no other help, then use the tools provided with IREn. Open up an MSDOS window (Command prompt), or a shell, and selecting the correct paths, type in the following, repeating what the use in Using the command line section above.

>java -jar \xep\lib\saxon.jar  -o hammer.fo hammer.xml hammer.xsl

This time the error reporting is clear and concise

>java -jar \xep4\lib\saxon.jar -o hammer.fo hammer.xml hammer.xsl \
Error on line 23 column 7 of
      file: .. /hammer.xml: \
      Error reported by XML parser:                  \
unexpected characters in element end tag (expected "p")
Transformation failed: Run-time errors were reported

Your display will vary a little from this, dependant on the location of your files, but the information is clear. Somewhere on line 23, the end tag is suspect. Now remove the error, by replacing the </b> with a </p>, and re-run the transformation. The error will not show if you have cleared it.

This demonstrates the increased detail available from a two step process, which is just a nuisance on a correct file.

If you ran the command line transformation, using saxon, then you will have a file named hammer.fo, into which we can now insert an error, to view the second source of errors.

In summary. When converting from XML to PDF (or PostScript), errors may be detected in either of the two stages of the transformation. It is often easier to isolate from which stage the error is originating. Now to inject and detect an error in the second stage, the XSL-FO to PDF stage.

Open up the hammer.fo file, using any text editor. Far more difficult to read, since much more is happening, but you should see the structure of the file if you spend a few minutes with it. In particular, look for that first paragraph again, where we inserted the error before. It looks different, since its now ready for the formatter. Look for

      <fo:block space-before.optimum="6pt" text-align='centre'>
      The purpose of this document is to illustrate handling complex
      layout patterns in the Extended Stylesheet Language (XSL).
      To simulate a real text, I have written an operation instruction
      for a hammer. The genre of operation instructions turned out
      to be quite convenient for showing most standard formatting
      properties. Features used in this text include:
    </fo:block>

An error has been introduced, specifying that the text should be aligned centre, which is a misspelling according to the official recommendation, which uses the American spelling (center). A perfectly innocent typographical error. Now to find it.

Note: If you regenerate the pdf file, this intermediate XSL-FO file will be overwritten, as mentioned above.

If you introduce the error as shown, then run the command shown below, the validate program should find it.

>\xep\validate hammer.fo
file: ... hammer.fo: line 2
Attribute 'text-align' cannot have a value of "centre".

hammer.fo: 1 error

The validate script, located in the distributeion directory has a single purpose, to spot these errors. The output could not be clearer, the text-align property cannot take a value of centre. To remove the error, either change the value to center, or remove the attribute and its value.

Re-run the validator, and a successful validation will result. Since the normal source of such errors is the XSLT stylesheet, that is where you would normally locate and remove these errors, since the purpose of the stylesheet is to convert the source XML into the form you have just seen in hammer.fo.

That is a view of finding errors in the two stages. Although not normally done in two separate stages like that, it is worth remembering that it can be done this way, since it is often easier to locate errors, and the objective is to produce the output efficiently.