Logging messages and errors

In addition to set_var and custom_marker, four functions are provided for inserting messages into the typesetting log file:

  • TopLeaf::message(MSG)

  • TopLeaf::warning(MSG)

  • TopLeaf::error(MSG)

  • TopLeaf::fatal(MSG)

where MSG is the message string to be added to the log. The only difference between these calls is the effect on the job status:

  • message allows the run to complete successfully (if there are no other errors). Log messages can be used toembed diagnostic or progress information within the typesetting log.

  • warning allows the run to complete with a warning (e.g. a problem that causes content to be set incorrectly).

  • error allows the run to complete with an error (e.g. a problem that causes content to be lost).

  • fatal causes the run to terminate immediately. A fatal error indicates that the whole run is compromised.

For example:

TopLeaf::message("$count items have been processed");
TopLeaf::error("unknown area code");
[Warning] Warning

The above commands pass information back to the TopLeaf typesetting log file. They cannot be used to indicate errors in the perl routines. Any perl code called from TopLeaf is assumed to be free from error.

If a Perl subroutine causes a compile time or run time error, then a fatal TopLeaf error will be triggered and the typesetting run will halt at that point. It is the user's responsibility to ensure that all perl code has been thoroughly tested before being used in a production system.