What is a minimal working example?
Christian Faulhammer |
Version: 0.7 |
2021-06-09
This document was created out of a need to supply newcomers to the newsgroup de.comp.text.tex with a collection of examples to demonstrate and clarify the principle of minimal working examples. This text is in the public domain, the newsgroup’s version (in German) is currently maintained by Christian Faulhammer and referred to in the regularly posted introduction. Please direct corrections, suggestions and comments to christian(at)faulhammer.org.
Anyone wanting to dive further into the meaning of error messages should have a look on the LaTeX Companion, which is besides not suitable for beginners.
Note concerning the English language version: Initial work and the first complete translation was done by Ulrich Schwarz. Now this has been overtaken by Christian Faulhammer.
First of all thanks to all members of the newsgroup who repeatedly tell people how important a minimal working example is and hints how to create it. Specifically I want to thank Ulrich Schwarz for the inital translation into English, Hilmar Preuße for the first LaTeX version and Kurt Lidwin for the rework of the latter.
Creating an MWE is a way of tracking down and fixing bugs, as well as finding the cause of certain behaviour. MWEs must be as small and simple as possible, yet complete, i.e. they accord to the base structure of a LaTeX document and can be LaTeXed without further additions.
An MWE should be complete and working,
so that you cannot accidentally omit information important to diagnose the problem;
so that the person responding can just copy-and-paste the code to try it out.
An MWE should be small,
so that responders does not have to concern themselves with long unnecessary lines of code;
because it will narrow down possible causes of misbehaviour;
because short examples are well suited for posting;
because many problems, such as missing brackets, faulty syntax, forgotten switches, etc. will easily be found in the process creating it;
because short documents will help you not to lose track of what’s going on.
Even beginners should have no problems creating MWEs, since it only takes a little patience and a schematic process paired with common sense. In most cases, you will find the cause of your problems yourself, thereby making posts unnecessary. After this short motivation, we will list the tools and procedures at hand, followed by some examples. We will deal with different sources of problems (wrong package options, packages clashing, faulty syntax, etc.) seperately. In complex cases, all these have to be applied at the same time.
The basic concept underlying the creation of an MWE is: "divide and conquer". There are several ways of dividing, some of which depend on the structure of the document. First of all, the command \listfiles should be added to the document, so that all used files (packages, classes etc.), including version information, will be logged. This information can be important to people replying and should not be omitted. Also, the usual rule holds: make a backup, and only work on copies, to prevent accidental deleting of important material!
As LaTeX always stops processing the file at the first occurence of the command \end{document}, it is well suited to search for errors.
If the whole source is in one single file, the following technique is useful: suitable advancing of the command "\end{document}" will help to coarsely narrow down where the problem is. Doing this, we move upwards by blocks. (This meaning logical blocks, i.e. paragraphs, environments given by \begin- \end pairs etc.) In doing this, we only need to move a single line (don’t forget to reLaTeX each time!) and will get an estimate in which block the error is. Now delete everything from just after "\begin{document}" up to just before the suspicious block, and if the problem still remains, that is where the problem is.
Basically, our procedure is similar to the procedure outlined above, just the end of a file that is read using \input is signified by \endinput. Beforehand, though, you should identify the parts responsible by successively commenting out of \input and/or include commands or by using \includeonly.
When the block containing the problem has been found, it needs to be simplified sufficiently in order to track down the bug to a single line. This is what the following examples will illustrate.
There are packages that just will not work together. We will remove the packages step-by-step to see if this is our problem. To facilitate this, it is advisable to use the \usepackage command like this:
so that packages can be commented out using a single % in the first column. As soon as the error disappears, re-enable the last package commented out and move on to the next.
User-defined commands and environments should be
omitted completely if they are not used anymore in the remaining document,
"emptied" otherwise, i.e. just have a #1 as second argument or do nothing at all.
This as well should be carried out step-by-step, in case the error is caused by one of these commands.
Now, we will basically go back to "moving the end", only not block- but linewise. I do not think this needs to be spelled out in full detail. Optimally, a single line of the document remains, that can be investigated further, or, if all else fails, posted to comp.text.tex (or suitable equivalents such as de.comp.text.tex or fr.comp.tex).
There are yet more ways of disabling parts of the document, such as the comment package, conditionals (if) and others.
Insertion of pictures is (almost) always a problem. We would need to pass them along in order to get a compilable document. But they are usually of big file size and might contain confidental information. Hence, we cannot put them up on the web somewhere either. What do we do, then? Well, we can just replace the picture with a black rectangle of appropriate size, which we can generate using \rule.
Sometimes there is no way round additional files to describe a problem, e.g. a small BibTeX file. LaTeX offers a simple way to keep everything in one file and the additional files are created on-the-fly with a given content: the filecontents environment.
Please note: line numbers have been inserted for clarification and ease of reference. As given below, the examples are not LaTeXable. Please omit the line numbers in your own examples.
The following is a simple aligned equation, that could be created using the eqnarray environment, but the amsmath package is more powerful by far.
The error message is:
The above leads us to suspect, that the error occurs in lines 6 to 9. Hence, we comment out all remaining lines in the align environment.
The error does not occur anymore, indicating that we have removed too much. Reinserting the lines one by one, LaTeXing again after each one, shows that with line 8, the error reoccurs. Then, everything prior to this up to \begin{align*} is commented out, but the error still remains. Hence, we now delete those lines, resulting in an MWE, since the only package loaded is the one providing the align environment in the first place:
A close look (and maybe help by your editor—any good editor can highlight matching parentheses) now reveals that we have forgotten the closing brace in \mathrm{e^{x}.
Let us assume the following source:
We dislike the apparently too small space in between the fraction and the equals sign created in line 7. We would like to detail this to the readers of comp.text.tex, but we are aware that this example is anything but clear. Hence, we limit the example to the relevant parts, possibly not including the user-defined commands in lines 3 and 4, which we verify by emptying them out.
We are not interested in the correctness of the mathematics involved for our purpose. Yet our document is still quite complex (well, we will pretend this for the moment, since otherwise, this all makes little sense.) What we really need is line 7, and of this only the beginning, so we remove the rest and simplify some more.
And now, we have an MWE that illustrates our problem without lugging around additional overhead. The following might be suggested to fix problem:
This example serves to illustrate mainly how to replace things that cannot be easily posted to the newsgroup as text. What is this to mean? When you insert pictures into your document, these are usually quite large and usually cannot be embedded as text into a posting, since most servers do not allow binary messages in text groups such as comp.text.tex.
So we have a nice little document containing a picture and some text, and since we want to do a bit of maths, we have some additional packages for that.
At first we check if the problem is related to any other package used, but commenting out line 3 does not change the result. Since we do not use a standard class here, but a replacement from the very recommendable KOMA-Script collection, we blame this class. Replacing "scrreprt" with "report" does not, however, improve the matter, but we leave this situation, since we can expect the report class in every installation. Now we reduce the remaining clutter and arrive at a truly minimal state.
But, come to think of it, it is not truly minimal yet, so we replace the graphic. Now, we are done:
Many people will use one of the common frontends or TeX-supporting editors (Emacs, Kile, TeXnicCenter, WinEdt to name but a few, with no claim to completeness nor recommendation) to edit their files and the interface to LaTeX they provide (menu items, buttons, keyboard shortcuts to run LaTeX, BibTeX, etc.). But sometimes, even these programs can be misguided in the assistance they offer: they can be misconfigured, maybe they do not find some executables, maybe they do not spot error messages under some circumstances, maybe they are limited in their abilities. Maybe they think your paper is in ISO A5 format because you insert the fifth appendix via \input{a5}. If things are going wrong and you really think they should not, keep the following in mind:
If you are dealing with rotation, graphics or color, your DVI viewer will possibly not display these correctly. What counts is the PostScript or PDF output.
Try to run latex or pdflatex, bibtex, makeindex etc. manually, i.e. from a command prompt or shell window. Maybe your editor is hiding their messages from you. Especially makeindex is good at generating hard-to-spot errors:
Can you see it? Would you see it if it is in between two LaTeX runs that generate 120 lines of output each? Running one step at a time gives you time to check the output without having to read the log file, which can often be confusingly verbose.
Sometimes, LaTeX or some package gets confused about the contents of auxiliary files. For example, try the following:
You do not need to understand what is going on here beyond the fact it is writing "foo" to the aux file (go check!). The first run will succeed, the second run will fail, because you are not allowed to output text at the point when the aux file is read. If you abort latex (with x), no new aux file is generated and further runs will fail, too. This is completely independent of what you change the tex file to!
To narrow down where it is happening, you can count braces: when TeX opens a file, it puts (filename to the screen, and ) when it closes them. In our case, we obtain something like
Note that test.aux is the last file opened and not closed, so it is likely that the error is there. (Well, I have already told you it is there.)
Of course, you can go the easy way by deleting the auxiliary files: we list some common extensions of auxiliary files along with where their content comes from and what it is for (so you know how to regenerate them after you delete them).
aux: Labels, references, citations, babel settings, various other. Source: tex or ltx file
toc, lof, lot: Table of contents, lists of figures and tables. Source: tex or ltx file
bbl: Bibliography. Source: bib and aux files via bibtex
ind, idx: Index. Source: ind from idx via makeindex or xindy, idx from tex or ltx file
gls, glo: Glossary. Just as ind and idx.