Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Section 48.2 Run-Time Messages

XSL provides a <xsl:message> element, which writes to the console (the stderr stream really, I believe). This makes it useful for debugging (like a print statement in another language). A mix of text, <xsl:apply-templates/>, and <xsl:value-of/> works well. Include delimiters (colons perhaps) so you don’t get fooled by unexpected empty strings that are part of your problem anyway.
But our point here is to discuss messages broadcast to an author or publisher.
  • Use <xsl:message> to communicate with authors and publishers as described above in Section 48.1 while negotiating their input used to control their content.
  • Otherwise, during actual processing, use <xsl:message> only when there is the potential for a real disaster in the output, such as a file that will not compile at all, meaning more than simple recoverable errors.
  • Do not duplicate parent-child relationships that are expressed in the schema. There are good validation tools for that job.
  • Consider using our auxiliary “validation-plus” stylesheet for detecting more complicated relationships that the schema cannot, or does not, detect.
  • See the advice above (Section 48.1) about checking author and publisher input and providing a “safe” result so there is no danger of creating broken output and thus less temptation to use <xsl:message> at all.
  • Reserve adding terminate="yes" for extreme situations where there is absolutely no hope of recovery. This should be a last resort.
  • Place terminate="no" (the default) in your code only when some future removal of deprecated code means this message will transition to terminate="yes". Include clear code comments describing the situation.
  • Prefix messages with
    • PTX:WARNING: for advisories
    • PTX:ERROR: for recoverable problems
    • PTX:FATAL: for case when processing terminates
    • PTX:BUG: for situations that are unexpected (and problematic)
    and align the start of messages in column 14 (so they all line up).
  • There is a template with mode="location-report" you can use to provide standardized assistance for an author or publisher looking for the place to correct a problem (in lieu of line numbers, which are not available).
PrevTopNext