7 Exceptions and Logging

If during execution of this software something goes wrong, and it is possible to detect that, the user shall be notified.

Maven foresees a mechanism to abort the whole build, i.e. lifecycle phase or a single goal and accordingly ant allows to abort a task. In both cases, abortion is implemented by throwing an exception.

to abort the life-cycle phase. Since this plugin is just for documentation, there is no need to abort site creation altogether, so only the former exception occurs.

This software provides both a maven plugin and an ant task built on the same code base. Thus, the maven plugin throws a MojoFailureException if and only if the according ant-task throws an BuildException in the same situation.

Section 7.1 describes the philosophy of throwing an exception and defines in detail under what circumstances which exception is thrown.

Roughly speaking, an exception is thrown only if something is really wrong, e.g. a non-recoverable error or an indication that the build system is out of control or if this plugin/task is likely to destroy the work of another plugin/task.

If something went wrong, but no exception is thrown, the user must be notified by logging and the build process to go on, skipping a section of a task as small as possible. Both, maven and ant provide a logging mechanism with the levels error, warning, info and debug. Section 7.2 describes the errors and warnings; the lot of infos and debugging output are not described here.

Each exception offers a message and also each warning has a warning message. The messages are endowed with a unique identifier of the form KCCDD, where K is the kind which is one of

The shortcut CC describes the class where the exception is thrown or the warning is logged:

Table 7.1: The logging for MetaInfo

Identifier	Message
Explanation




WMI01	Version string from converter $conv did not match expected form:
	$conv: ’version’not?in$interv
Indicates that the version string coming from the converter $conv is not as expected. Programming error excluded, this means that the version does not fit, i.e. is not in $interv.
WMI02	$conv: ’$actVersion’not in$interv
Indicates that the version of converter $conv can be detected and is $actVersion but does not fit the expectation which is $expVersion.

Table 7.2: The logging for TexFileUtils

Identifier	Message
Explanation




WFU01	Cannot read directory ’$dir’;
	build may be incomplete.
TBD
XFU02	TBD
TBD
WFU03	Cannot close ’$file’.
TBD
EFU05	Cannot delete file ’$file’.
TBD
EFU06	Cannot move file ’$src’ to ’$dest’.
TBD
EFU07	File ’$srcFile’ to be filtered cannot be read.
WORKAROUND for inkscape filtering eps_tex-file into ptx file: The former is not a readable regular file.
EFU08	Destination file ’$destFile’ for filtering cannot be written.
WORKAROUND for inkscape filtering eps_tex-file into ptx file: The latter is not a writable regular file.
EFU09	Cannot filter file ’$srcFile’ into ’$destFile’.
WORKAROUND for inkscape filtering eps_tex-file into ptx file: Either reading a line or writing a line failed.
WFU10	Cannot overwrite/clean file ’$aFile’
	because it is not self-created.
May occur if a file, e.g. .latexmkrc is present in the latex source directory and is not created by this software. To avoid the risk of overwriting or deleting user-written files, only config files written by this software can be overwritten in goal inj or deleted in goal clr.
WFU11	Refuse to overwrite/clean file ’$aFile’
	because it may be not self-created or has dangling reader.
To avoid the risk of overwriting or deleting user-written files, this software checks whether it was this software which wrote the files by reading the headline. If this is not possible or if the reader to read that headline could not be closed after reading, this warning is emitted. Neither is the file overwritten in goal inj nor is it deleted in goal clr.

TBD: check whether workaround still necessary. TBD: complete list TBD: add missing lists

7.1 Exceptions

Exceptions are thrown only if no substantial part of this maven-goal or this ant-task may be completed as if the tex source directory does not exist or is no directory or if a failure occurs which indicates that the underlying system does not work properly, as if the tex source directory or a subdirectory is not readable or if execution of an external program fails. The latter does not mean that the program returns with an error code, but it means that execution from within java fails.

Table 7.3: The BuildFailureExceptions of the class CommandExecutorImpl

Identifier	Message
Explanation




TEX01	Error running $command.
Compare with EEX01 in Table 7.9: Error execution means the file expected to be the working directory does not exist or is not a directory. method Runtime.exec(String, String[], File) fails throwing an IOException. an error inside systemOut parser occurs an error inside systemErr parser occurs Wrapping an InterruptedException on the process to be executed thrown by Proces.waitFor(). whereas for EEX01 just a failure code is returned.

Table 7.4: The BuildFailureExceptions of the class Settings

Identifier	Message
Explanation




TSS01	The tex source directory ’$texSrcDirectoryFile’
	should be an existing directory, but is not.
The tex source directory is given in the pom/build-file with default value ./src/site/tex. It contains or is $texSrcProcDirectoryFile. Thus is must be a directory.
TSS02	The tex source processing directory ’$texSrcProcDirectoryFile’
	should be an existing directory, but is not.
The tex source processing directory is given in the pom/build-file relative to $texSrcDirectoryFile with default value .. It contains all files to be processed. Thus is must be a directory.
TSS03	The output directory ’$outputDirectory’
	should be a directory if it exists, but is not.
The output directory is given in the pom/build-file with default value ./target/site/.. The output directory is where the result of the goal/task are copied to. If it does not yet exist, it is created but if it exists and is a regular file, it cannot be created anymore.
TSS04	The target set ’$targetsStr’
	contains the invalid target ’$targetStr’.
Indicates that a target $targetStr in a target set given in a context $context is unknown, e.g. because it is misspelled. The context is either the setting $targets or the target set in a chunk of setting $docClassesToTargets or in a magic comment specifying $targets. For a description of the settings see Table 6.1 on page 246. See also the Exception TSS11 in this table. For each target, there is an according goal and so it can be given on the command line as e.g. via mvn latex:pdf and also in this case, the validity of the target is checked, so that e.g. mvn latex:invalid throws an exception, but the mechanism relies directly on maven’s ability to check the targets of this plugin.
TSS05	The excluded converters ’$convertersExcluded’
	should form a subset of the registered converters ’…’.
From the possible “registered” converters the ones not used may be excluded to avoid that they cause errors when trying to check correctness of version in target vrs accessed via mvn latex:vrs. These converters may not even be installed.
TSS06	Tried to use converter ’$convStr’
	although not among the registered converters ’…’ as expected.
Only registered converters may be used.
TSS07	Tried to use converter ’$convStr’
	although among the excluded converters ’…’.
Among the registered converters only those may be used, which are not excluded, i.e. listed in configuration in section convertersExcluded.
TSS08	Tried to use converter ’$convStr’
	in configuration ’…’ instead of configuration ’…’.
Each converter may occur in a specified configuration only. So e.g. lualatex is only allowed in configuration ’latex2pdfCommand’. If used in configuration ’makeIndexCommand’ this causes this exception, because in that configuration, e.g makeindex is allowed.
TSS09	The diff directory ’$diffDirectoryFile’
	should be a directory if it exists, but is not.
The $diffDirectoryFile shall exist and be a directory. In it shall be stored the artifacts the actually created shall be compared with if chkDiff is set using the command diffPdfCommand. As the name suggests, currently only pdf-files are compared.
TSS10	Specified unregistered converter ’$convStrProper’
	with invalid category ’$catStr’; should be ’…’.
The converter convName is specified in the setting <catCommand> in the form convName:notCat with category notCat not coinciding with cat as required.
TSS11	The target set ’$targetsStr’ in $context
	repeats target ’$target’.
Indicates that a target $targetStr in a target set given in a context $context is repeated, despite sets contain elements only once. The context is either the setting $targets or the target set in a chunk of setting $docClassesToTargets or in a magic comment specifying $targets. For a description of the settings see Table 6.1 on page 246. See also the Exception TSS04 in this table.
TSS12	Invalid mapping ’$chunk’ of document classes to targets.
Indicates that the chunk $chunk in parameter docClassesToTargets is syntactically not allowed. For a description of the syntax see Table 6.1 on page 246.
TSS13	For document class ’$cls’ target set is not unique.
Indicates that in parameter docClassesToTargets a class defines its targetsmore than once.

Table 7.5: The BuildFailureExceptions of the class MetaInfo

Id.	Message
Explanation




TMI01	Cannot get stream to file ’$fileName’.
Stream to file within jar. This may be the manifest file, pom.properties or git.properties.
TMI02	Cannot load properties from file ’$fileName’.
Provided the stream to the file is ok, could not load property. This may occur for pom.properties or git.properties.
TMI03	IOException reading manifest.
Provided the stream to the manifest file is ok, could not read completely.

Table 7.6: The BuildFailureExceptions of the class TexFileUtilsImpl

Id.	Message
Explanation




TFU01	Cannot create destination directory ’$targetDir’.
This is mainly because of writing permissions.
TFU04	Cannot overwrite directory ’$destFile’.
Because this plugin shall not turn directories into regular files and vice versa. This failure indicates that another plugin/task disturbs this one.
TFU06	Cannot copy file ’$srcFileName’ to directory ’$targetDir’.
This is mainly because of writing permissions.

Table 7.7: The BuildFailureExceptions of the class LatexProcessor

Id.	Message
Explanation




TLP01	Artifact ’$pdfFileAct’ from ’$texFile’ could not be reproduced.
Processing $texFile yields $pdfFileAct which is not “alike” the stored version. Currently, that kind of check can be performed for PDF files only. Also, the diff check is executed only if parameter $chkDiff described in Section 6.13 is set. Then the diff command $diffPdfCommand is performed to determine whether the artifacts are equivalent in the sense given by the diff command. The concrete meaning of that equivalence may range from strict equivalence to some kind of visual equivalence.
TLP02	Add file ’$pdfFileCmp’ to compare with artifact ’$pdfFileAct’!
The PDF file $pdfFileCmp expected for comparison with the PDF file $pdfFileAct created from a LaTeX main file does not exist. It is expected only if a diff check is configured according to $chkDiff described in Section 6.13. This warning is normal if the document is added newly. Then just copy the created PDF file (maybe preserving modification time) after quality check. This warning is also normal if a document is actively modified. Then before building the file $pdfFileCmp shall be removed before compilation to force this software to assign a new timestamp, e.g. into first page and metadata. Currently, that kind of check can be performed for PDF files only.
TLP03	Failure while writing file ’$fileName’ or closing in-stream.
Failure while performing goal inj while writing file ’$fileName’ or closing in-stream. The file is created from a template replacing parameter names by their actual values. A reason may be that the template cannot be read or its in-stream cannot be closed. The result is written into the latex source directory.

7.2 Logging of warnings and errors

The rules for logging warnings and errors is, that the user must be notified, if something went wrong, but the run is not aborted, by a warning or an error. It is not required that for each detail going wrong, there is a separate notification, but the user must be sure, that all is ok, if no warning and no error occurs.

To decide whether it is an error or a warning to be logged, one has to distinguish, whether the problem occurs when running an external application or within internal code. In the first case, the decision whether it is an error or a warning is left to that application:

If an application does not create the expected output file, this software logs an error. This may be because of an internal error as described above, but also because of wrong parameters. So, e.g. lualatex -v xxx.tex does not create a pdf-file as expected.

Table 7.8: The errors and warnings on running a command

Id.	Message
Explanation




EEX01	Running $command failed with return code $returnCode.
Compare with TEX01 in Table 7.3: Error execution means that there is evenno valid return code.
EEX02	Running $command failed: No target file ’$fileName’ written.
FIXME
EEX03	Running $command failed: Target file ’$fileName’ is not updated.
The command $command is expected to write to the file ’$fileName’ but this file is not updated. This indicates an error executing $command.
WEX04	Cannot read target file ’$fileName’; may be outdated.
FIXME
WEX05	Update control may emit false warnings.
FIXME
EAP02	Running $command failed: No log file ’$logFileName’ written.
The command $command is expected to write a log file ’$logFileName’ but no such file exists. This indicates an error executing $command.
EAP01	Running $command failed. Errors logged in ’$logFileName’.
The command $command logged at least one error in the file ’$logFileName’,where more details can be found.
WAP03	Running $command emitted warnings logged in ’$logFileName’.
The command $command logged at least one warning in the file ’$logFileName’, where more details can be found. Note that if $command is a latex processor, this warning comes only iff the parameter $debugWarnings is set. Note also that notifications on bad boxes are not counted as warnings here.
WLP03	Running $command created bad boxes logged in ’$logFileName’.
Here, $command is a latex processor. It logged at least one bad box, overfull or underfull, horizontal or vertical in $logFileName where more details can be found. Note that this warning comes only iff the parameter $debugBadBoxes is set.
WLP06	Running $command found issues logged in ’$logFileName’.
This warning does no longer occur. The following is the original explanation: Here, $command is a checker tool. Strictly speaking, unlike the other warnings here, this does not signify that running $command went wrong but uncovered an issue (warning/error/message) logged in a file.
WLP05	Use package splitidx without option split in $texFileName.
This indicates that an extended idx-file “xxx-yy.idx” has been found without xxx.idx or without according entry \indexentry[yy]{…}{…} in xxx.idx.
WLP07	Found both ’$dviFile’ and ’$xdvFile’; convert the latter.
This indicates that for conversion to PDF there are a DVI-file and a XDV-file which may come from mixed application of xelatex and another converter. In this case, the $xdvFile is converted.

Table 7.9: The errors and warnings on files/streams

Id.	Message
Explanation




WFU01	Cannot read directory ’$dir’; build may be incomplete.
FIXME
WPP02	Cannot read tex file ’$texFile’; may bear LaTeX main file.
FIXME
WAP04	Cannot read log file ’$logFileName’; may hide warnings/errors.
FIXME
WLP02	Cannot read log/aux file ’$logFileName’; $kind may require rerun.
FIXME
WLP04	Cannot read idx file ’$idxFileName’; skip creation of index.
FIXME
WFU03	Cannot close ’$closeable’.
FIXME
WFU04	Could not assign timestamp to target file $file.
Currently NOT USED! The former explanation was as follows If either the parameter ’$chkDiff’ described in Table 6.13 on page 286 is set or the magic comment chkDiff described in Section 3.1.1.0 occurs, then the modification time of target files must be set explicitly. In this situation, this warning occurs if setting the modification time could not be set.
EFU05	Cannot delete file ’$delFile’.

EFU06	Cannot move file ’$fromFile’ to ’$toFile’.
FIXME

Table 7.10: Miscellaneous errors and warnings

Id.	Message
Explanation




WPP03	Skipped processing of files with suffixes $skipped.
FIXME
WPP04	Skip processing $srcFile: interpreted as target of $lmFile.
FIXME
WPP05	Included latex files which are not LaTeX main files:
	$includedNotMainFiles.
In parameter mainFilesIncluded only LaTeX main files shall be mentioned. The above message shows files specified which are not recognized as LaTeX main files. This is also affected by parameter patternLatexMainFile.
WPP06	Excluded latex files which are not LaTeX main files:
	$excludedNotMainFiles.
In parameter mainFilesExcluded only LaTeX main files shall be mentioned. The above message shows files specified which are not recognized as LaTeX main files. This is also affected by parameter patternLatexMainFile.
WPP07	Included/Excluded LaTeX main files not identified by their name:
	$inclExcl.
This indicates that there are different LaTeX main files with the same name (of course in different directories) and that $inclExcl are those given in parameter mainFilesIncluded or mainFilesExcluded.
WLP01	LaTeX requires rerun but maximum number $maxNumRerunsLatex reached.
FIXME
ELP01	For command ’$command’ found unexpected return code $returnCode.
Here, $command is a checker tool. The return codes are determined by reverse engineering. So possibly $returnCode cannot be interpreted.
ELP02	Checker ’$command’ logged an error in $clgFile.
Indicates that the checker found an error. Note that errors are warnings declared explicitly as errors. There is also the case that warnings are declared as simple messages and thus causes neither a warning nor an error.
WLP08	Checker ’$command’ logged a warning in $clgFile.
Indicates that the checker found a warning. Implicitly it means that no error was found since this would cause EPL02. Note that warnings can be declared as simple messages and thus cause neither a warning nor an error.
WLP09	For file ’$texFile’ targets are neither specified by magic comment
	nor restricted by document class ’$docClass’.
Indicates that the LaTeX main file $texFile has neither a magic comment specifying the targets nor for the document class parameter docClassesToTargets described in Table 6.1 specifies the allowed targets. Since no restriction on targets are known, $texFile is compiled for all targets given in $targets given also in Table 6.1. To avoid this warning, just add $docClass to docClassesToTargets or specify targets by magic comment.
WLP10	Degraded identifier for ’$file’;
	augmented risk not to rerun although necessary.
Indicates that an auxiliary file $file which is used to determine whether an auxiliary program shall be rerun could not be completely evaluated. An example of an auxiliary file is an IDX file. If it changes not only makeindex but also the LaTeX compiler need to be rerun. A special kind of auxiliary files are AUX files. They may be used to create bibliographies or glossaries. They are special in that they may include other AUX files, namely those corresponding with included TEX files. In this case, $file is the top level AUX file.

Chapter 7Exceptions and Logging

7.1 Exceptions

7.2 Logging of warnings and errors

Chapter 7
Exceptions and Logging