I was posting some question about this strange thing LaTeX is doing when I try to compile my thesis. Someone asked me to provide a minimal example that reproduces the problem. My thesis is now a few hundred pages long and spans along ten different source files! How am I supposed to know what or where is the cause of the problem?

Do you have any hints or ideas on how should I go about producing such a small example?

share

migrated from tex.stackexchange.com Jul 31 '10 at 18:58

This question came from our site for users of TeX, LaTeX, ConTeXt, and related typesetting systems.

2  
When posting a minimal working example, also consider posting what you have tried; community members might find this helping in trying to solve your problem. –  Werner Jan 30 '13 at 1:51
1  
Why this question and a synthesis of the answer are not present in the help center? –  Clément Jun 26 at 17:33
add comment

8 Answers 8

Most questions about code are made more answerable by the addition of a minimal working example (MWE) or short, self-contained, correct example (SSCCE).

Your question may have an obvious answer, or it may not. You the questioner probably do not know the difference between the two! So think about it from the point of view of the answerer. To ensure that the answer she provides is sound, she will probably want to create a sample document, make the changes she recommends, and check that it works. If she thinks she knows the answer but doesn't have the time to create a sample document, she may in the interest of quality control refrain from answering at this time.

So make it easy for potential answerers! Give them a block of code that can be copied, pasted directly into a file, compiled, tweaked, corrected, and pasted back.

Here minimal means that the problem is isolated and there is nothing in the sample that distracts from the error you have or the effect you desire. Working doesn't mean the problem is solved :-), it means the code sample can be copied-and-pasted and directly compiled.

The site sscce.org is dedicated to the topic. There are also several articles on the topic as it applies specifically to LaTeX:

Errors

I didn't see your question, but I'm guessing that you got some error you haven't seen before, and said something to the effect of

I tried to compile, but I got the error `Undefined control sequence.' How can I fix it?

This is next to impossible to answer, unless you expect only answers from psychics.

Instead, look at the line numbers, and post that paragraph or sentence, depending on the scope of the error. You'll have to add any referenced packages or other components which are critical to the compilation of the section, but make it as focused as possible on the part which is the source of the error.

If there are no helpful line numbers, (make a backup and then) begin removing things you added after the last successful compile. If you remove everything you just added, perform a binary search by removing halves of the document until you can narrow it down. Then, post the section which caused the problem.

Often, this process will help you to discover the problem and solution yourself! If this happens, please still post your minimal example, add your solution as an answer, and accept it later. This way, future readers can benefit from your work (and you can get a self-learner badge if your solution was novel enough to get some upvotes!)

A better approach to the "I tried to compile..." example above would be something like:

I am trying to typeset the following equation:

\documentclass{article}  
\begin{document}  
Alpha particles (named after and denoted by the first letter in the
Greek alphabet,\[\alpha\]) consist of two protons and two neutrons bound
together.
This means that an \[\alfa\] particle is a helium nucleus. 
\end{document}  

But when I compile it with LaTeX I get this error message:

[22]
Undefined control sequence:
\alfa
`An \[\alfa\] particle is a helium nucleus.`

What am I doing wrong?

Enhancements

Other questions are not related to errors, but to a desired effect that the user wants to achieve, of the form:

I want to put (thing) at (place). How do I do that?

The MWE in this case should:

  • be a full document including \documentclass, a preamble, \begin{document}, and \end{document}.
  • include enough dummy text to make the document look like the one you're writing. The lipsum, kantlipsum and blindtext packages are helpful here in that they provide macros to make lots of text without actually having to type lots of text.
  • have your best-so-far implementation of the desired effect.

Try to keep your vocabulary accessible—do not assume that because many experts in your field use TeX that all TeX users are familiar with your field. A question about typesetting affine Dynkin diagrams will not get answered until you find someone who knows TeX and math.

If you have enough reputation to include images, please do. Images of both the desired effect (mocked up or copied from another document), and the result of your best-so-far implementation. If you do not have enough reputation to include images, upload to http://imgur.com/ anyway and post the links (an editor will include the images for you). If you do not have enough reputation to post links, enter the bare URLs.

share
10  
I've never seen th abbreviation 'SSCCE': I think 'MWE' is much more common. –  Joseph Wright Jul 29 '10 at 20:41
5  
SSCCE, I take it, is more often used on programming forums for Java and C. MWE is much more common in the TeX community after some recent research. Edited. –  Kevin Vermeer Jul 29 '10 at 21:01
1  
Good answer, but this isn’t really an MWE, right? I thought that the point of MWEs is that they are complete working (La)TeX documents. –  Konrad Rudolph Jul 30 '10 at 14:15
2  
@ Konrad - Good point. Edited! However, next time, feel free to edit it yourself. –  Kevin Vermeer Jul 31 '10 at 15:34
2  
@Kurt I don't think that adding \listfiles is good: it can convey the idea that \listfiles is a required command in all documents. –  egreg Feb 26 '13 at 11:13
    
@egreg; No problem. There are a lot of questions on TeX.Se were \listfiles was helpful. So my idea was to add it here to show it people asked to prepare a MWE. Perhaps a second MWE with listfile and an explanation why would be better? Here or in the next aanswer? –  Kurt Feb 26 '13 at 13:49
    
@Kurt Maybe adding a note about adding it if requested in comments can be worthy. –  egreg Feb 26 '13 at 13:53
add comment

This answer focuses more on minimalizing the code, rather than finding the source of the problem, as the top-voted answer does. It is intended to be concise and hands-on, but digestible rather than exhaustive. Suggestions for improvement welcome!


Here are some strategies for reducing your code, which will help you get better and faster answers, since it will be clearer what your problem is and the other users will see that you put some effort into producing a concise Minimal Working Example. Thanks for that!

Most likely, not all of these things will apply to your question, so just pick what does apply.

Document Class

- Bad:

\documentclass{MyUniversitysThesisClass}

+ Good:

\documentclass{article}

Using a non-standard document class? Does your problem still show up with article? Then use article.

Document Class Options

- Bad:

\documentclass[12pt, a5paper, final, oneside, onecolumn]{article}

+ Good:

\documentclass{article}

Using any options for your document class? Does your problem still show up without them? Then get rid of them.

Comments

- Bad:

\usepackage{booktabs} % hübschere Tabllen, besseres Spacing
\usepackage{colortbl} % farbige Tabellenzellen
\usepackage{multirow} % mehrzeilige Zellen in Tabellen
\usepackage{subfloat} % Sub-Gleitumgebungen

+ Good:

\usepackage{booktabs}
\usepackage{colortbl}
\usepackage{multirow}
\usepackage{subfloat}

You put comments in your code to remember what packages are there for? Great habit, but usually not necessary in a MWE – get rid of them.

Loading Packages

- Bad:

\usepackage{a4wide}
\usepackage{amsmath, amsthm, amssymb}
\usepackage{url}
\usepackage[algoruled,vlined]{algorithm2e}
\usepackage{graphicx}
\usepackage[ngerman, american]{babel}
\usepackage{booktabs}
\usepackage{units}
\usepackage{makeidx}
  \makeindex  
\usepackage[usenames,dvipsnames]{color}
\usepackage{colortbl}
\usepackage{epstopdf}
\usepackage{rotating}

+ Good:

% Assuming your problem is related e.g. to the rotation of a figure, you might need:
\usepackage{graphicx}
\usepackage{rotating}

You’ve developed an awesome template with lots of helpful packages? Does your problem still show up if you remove some or even most of them? Then get rid of those that aren’t necessary for reproducing the problem. (If you should later find out that another package is complicating the situation, you can always ask another question or edit the existing question.)

In most cases, even packages like inputenc or fontenc are not necessary in MWEs, even though they are essential for many non-English documents in “real” documents.

Images

- Bad:

\includegraphics{graphs/dataset17b.pdf}

+ Good:

\usepackage[demo]{graphicx}
....
\includegraphics{graphs/dataset17b.pdf}

+ Good:

\usepackage{mwe} % just for dummy images
....
\includegraphics{example-image}

Your problem includes an image? Does your problem show up with any image? Then use the option demo for the package graphicx – this way, other users who don’t have your image file won’t get an error message because of that. If you prefer an actual image that you can rotate, stretch, etc., use the mwe package, which provides a number of dummy images, named e.g. example-image.

Text

- Bad:

In \cite{cite:0}, it is shown that $\Delta \subset {U_{\mathcal{{D}}}}$. Hence 
Y. Q. Qian's characterization of conditionally uncountable elements was a 
milestone in constructive algebra. Now it has long been known that there exists 
an almost everywhere Clifford right-canonically pseudo-integrable, Clairaut 
subset \cite{cite:0}. The groundbreaking work of J. Davis on isomorphisms was a 
major advance. In future work, we plan to address questions of uniqueness as 
well as degeneracy. Thus in \cite{cite:0}, the main result was the 
classification of meromorphic, completely left-invariant systems.

+ Good:

\usepackage{lipsum} % just for dummy text
...
\lipsum[1-3]

+ Good:

Foo bar baz.

Need a few paragraphs of text to demonstrate your problem? Use a package that produces dummy text. Popular choices are lipsum (plain paragraphs) and blindtext (can produce entire documents with section titles, lists, and formulae).

Need just a tiny amount of text? Then keep it maximally simple; avoid formulae, italics, tables – anything that’s not essential to the problem. Popular choices for dummy words are foo, bar, and baz.

Bibliography Files

+ Good:

\usepackage{filecontents}

\begin{filecontents*}{\jobname.bib}
  @book{Knu86,
    author = {Knuth, Donald E.},
    year = {1986},
    title = {The \TeX book},
  }
\end{filecontents*}

\bibliography{\jobname} % if you’re using BibTeX
\addbibresource{\jobname.bib} % if you’re using biblatex

Need a .bib file to reproduce your problem? Use a maximally simple entry embedded in a filecontents environment in the preamble. During the compilation, this will create a .bib file in the same directory as the .tex file, so users compiling your code only need to save one file by themselves.

Another option for biblatex would be to use the file biblatex-examples.bib, which should be installed with biblatex by default. You can find it in bibtex/bib/biblatex/.

Data

-- Bad:

enter image description here

Never include data as an image.

- Bad:

Number of points    Values
10                   100
20                   400
30                  1200
40                  2345
etc...

+ Good:

\usepackage{filecontents}

\begin{filecontents*}{data.txt}
Number of points, Values
10, 100
20, 400
30, 1200
40, 2345
\end{filecontents*}

Including the data as part of the MWE makes the example portable as well. Of course, the input may differ depending on what package you use to manage the data (some require CSV, some don't).

Posting a Picture of Your Output

It’s often helpful to see what your current, faulty output looks like. If you’re not sure how to do that, have a look at How does one add a LaTeX output to a question/answer? and how can i upload an image to be included in a question or answer?.


Selection of packages inspired by Inconsistent rotations with \sidewaysfigure. Math ramble generated by Mathgen. Bibliography sample from lockstep’s question biblatex: Putting thin spaces between initials.

share
6  
This is excellent. We could use this as a basis for a more useful mwe tag wiki. –  Charles Stewart Jan 31 '13 at 20:11
1  
Indeed, this is really great work! Thanks! –  Jake Jan 31 '13 at 20:16
    
@CharlesStewart Thanks! If others find this useful, we could either use it as a tag wiki, or link here from the tag wiki. I think I’d lean towards the latter option, just because collectively edited answers tend to see more action and “peer review” than tag wikis: Post edits displayed at the top of the main (meta) page, whereas a tag wiki edit is only (?) visible in the suggested edits history (if review is required), which I don’t think many people look at on meta. –  doncherry Feb 2 '13 at 16:22
2  
I have to agree with Charles Stewart and Jake. This is a long-needed advice on how to create a MWE from already existing documents rather than to actually produce an example at all (i.e. Do-It-For-Me questions or “There is an error. Help!”). Re Comments: Not all comments in MWEs are bad. (Though, I agree that those package-describing comments are mostly unnecessary, and, interestingly, always in German.) Re mwe: It is actual not necessary to load (but to install) mwe, the images are included without it. Though, loading mwe has its perks as the manual’s chapter 2 elaborates. –  Qrrbrbirlbel Feb 3 '13 at 1:43
1  
@Qrrbrbirlbel Re Comments: True, but I don’t expect users to follow these guidelines stubbornly. If they think they really need a comment, they’re gonna have it. Note how I even inserted comments myself for mwe and lipsum. Generally, I aimed at brevity and 90% accuracy, rather than 100% accuracy. Re mwe: The same idea applies here. I didn’t want to go through the pain of explaining how you can use a package’s files even if it’s not loaded. Loading it just makes everything easier – and I might even consider it good practice, just to indicate where the files come from. –  doncherry Feb 3 '13 at 15:12
    
@doncherry I would suggest to add \listfiles to build the table of used packages in the log file for posting it in the question. –  Kurt Feb 25 '13 at 22:30
    
@Kurt As egreg remarked on the other answer: No need to add this to every MWE – I’d be afraid it’d cause more confusion to new users than it would actually help. If we suspect an installation isn’t up-to-date, it’s easy enough to request \listfiles “manually”. –  doncherry Mar 16 '13 at 18:24
    
@doncherry No problem. Perhaps a new question like "How to check if my system is up to date?" –  Kurt Mar 16 '13 at 21:29
    
@Speravir I purposely omitted kantlipsum because it doesn’t seem to add any functionality over lipsum, and it was more important to me to keep things simple rather than giving a complete overview of the options available. –  doncherry Jan 26 at 11:13
add comment

Hopefully if your thesis is a few hundred pages long, you haven't been experiencing the problem you're asking about since you began it! If you were having the problem the whole time, then you could probably construct a minimal example basically by pretending to start a new thesis in the same way you started your existing one.

In the more likely scenario that you've just encountered a new problem, the best approach I've found is to start commenting out the newest pieces you've added one at a time and seeing when the problem goes away. At that point, you can try to make a new minimal document containing only the part you had to remove to make the problem go away -- if all goes well, you'll be able to make the new (much smaller) document reproduce the same problem.

It's actually not uncommon to end up finding the solution yourself when you start trying to construct a minimal example, but if that's not the case then once you have it you can add it to your original question to find help here.

Good luck!

share
34  
Binary search is usually the fastest solution. Remove roughly 1/2 of your thesis. If the problem persists, repeat. If not, undo and remove the other 1/2 of your thesis. Of course it isn't quite that straightforward always, but even if you have hundreds of pages of text, you can fairly quickly reduce the problem to a short fragment of code. –  Jukka Suomela Jul 29 '10 at 20:34
2  
+1 for observing that this is a good way to debug the problem oneself –  Norman Gray Jul 29 '10 at 21:23
1  
+1 for a newbie this is the most useful strategy. I am writing my thesis and I do this often. I also use binary search. –  denilw Feb 8 '11 at 21:18
4  
For those like me who do not have a text editor that allows to comment part of your .tex, for the binary search you can use the verbatim package, which allow you to use \begin{comment} ... \end{comment} commands. –  Gopi Jul 11 '11 at 13:55
add comment

Please note that the "minimal" in minimal working example means that the document should not contain any (yes any!) code which isn't related to the error. If a code line can be removed without changing the error/issue it doesn't belong into the example. If a non-standard class is used1 for the original document and the error/issue still happens with a standard class then a standard class should be substituted. This means normally article or, if \chapter is required, report or book).

It is not required to use the minimal class for a minimal working example! In fact it should be avoided to prevent issues with missing definitions which are present in any real class, cf. also "Why should the minimal class be avoided?".

1 Standard classes are: article, book, report and letter.

share
add comment

There’s a new package on CTAN called mwe, providing some features for creating MWEs. This is the announcement text:

mwe provides several files useful to create a minimal working examples (MWEs). A mwe package is provided which loads a small set of often used packages for MWEs. In addition several different images are provided which will be installed in the TEXMF tree, so that they can be used in any (La)TeX document. This allows different users to easily share MWEs which include images commands without requiring to share image files or use replacement code.

See Martin’s announcement here on TeX.SX

share
1  
Thanks for posting it here. I was planning to do so, but I didn't found time yet. –  Martin Scharrer May 10 '12 at 8:16
add comment

Several TeX-specific pieces of advice exist. I'd start with the UK TeX FAQ: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl

share
5  
    
@KevinVermeer It's been moved to dickimaw-books.com/latex/minexample but thanks for mentioning it :-) –  Nicola Talbot Feb 4 at 18:53
add comment

What is a minimal working example? is a work of some regulars of de.comp.text.tex. Here they describe in detail, how to produce a minimal working example.

share
1  
Since this question is community wiki, I've added your link to the official answer. In the future, please edit the official answer rather than adding your own. Having too many answers to a FAQ like this just adds noise and makes it more difficult for noobs. –  Kevin Vermeer Jul 29 '10 at 22:54
    
@reemrevnivek: Really? I'm not used to seeing that behaviour in StackOverflow. –  Will Robertson Jul 30 '10 at 5:02
1  
@Will - There are some polls, and some examples with lots of answers, but the FAQs (or at least the ones I've read) are all one answer, sometimes with noise at the bottom. Click through the questions at the official FAQ –  Kevin Vermeer Jul 30 '10 at 12:22
add comment

Well, you can't just post your whole thesis and expect people to debug it for you...

It shouldn't be that hard to know which part of your thesis is causing the problem. Error messages should help you pinpoint which section of your LaTeX code is the problem - they usually include a file name and line number. You can then copy and paste it on here without any doubt that it will get solved.

share
    
:D Have you ever tried to debug problems in (La)TeX files? Btw, I'm seeding this question, pretending to be a real user having a problem with my thesis. –  Juan A. Navarro Jul 29 '10 at 20:26
add comment

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .