Question

I am using the MiKTeX 2.8 distibution for Windows.

We develop software primarily, and use LaTeX to make our user instructions. We use LaTeX because:

• It’s great under source control for tracking changes etc.
• The source files don’t suddenly decide to become corrupt, unlike Word documents.
• Multiple documents can share single sections, so we can apply the DRY principle to our documentation and avoid some documents getting out of sync with others. You can have master documents in Word, but I’ve found them to be flaky as hell.

As a part of the unattended build process on our build server, we build the documentation using MiKTeX’s texify executable. This works fairly well.

However, problems occur when a developer makes an error (e.g. a \ref to a \label that doesn’t exist). An error such as that only generates a warning in LaTeX. The warning goes unnoticed by texify, and we’re left with errors in the documentation.

I currently have a build step which scans log files for lines beginning with ‘LaTeX Warning’ and fails the build if there are any. This works, but is obviously pretty flaky, and may let warnings slip through. It currently is not used on local builds on dev machines, but if that’s the only way to do it, I may have to integrate it with the editor we’re currently using (TeXworks shipped with MiKTeX).

I’d like to fail the build if any warnings such as an undefined reference occur, and I’d rather not do flaky scans of log files. Does anything offer this feature?

If I can use this feature in local builds on dev machines as well as on the build server it would be a huge bonus.

Answer 1

The following (untested) code should turn any warning into an error:

\renewcommand{\GenericWarning}[2]{\GenericError{#1}{#2}{}{This warning has been turned into a fatal error.}}

Then you may be interested in the silence package to filter warnings.

However you will also need to arrange to do this only for the last run of LaTeX, because some warnings such as undefined reference are to be expected during the first runs.

Editors with good LaTeX support will tell you if you need to re-run LaTeX (doesn’t TeXworks do it?). They do it by parsing the console output or the log file. It is in fact reasonably robust (and if you’re really worried you could redefine \GenericWarning to add a characteristic string to all warnings). I think parsing the logs is the right way to do it.

Think of this as a test to run against the documentation. If there are undefined references, the documentation build succeeds. The build products are the pdf (or whatever) and the TeX logs. Checking for warnings in the logs is a test.