Section 48.2 Run-Time Messages
XSL provides a
<xsl:message>element, which writes to the console (the
stderrstream really, I believe). This makes it useful for debugging (like a
<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.
<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 LaTeX 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
- Reserve adding
terminate="yes"for extreme situations where there is absolutely no hope of recovery. This should be a last resort.
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
and align the start of messages in column 14 (so they all line up).
PTX:ERROR:for recoverable problems
PTX:FATAL:for case when processing terminates
PTX:BUG:for situations that are unexpected (and problematic)
- 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).