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?

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}

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.

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 VermeerJul 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 RudolphJul 30 '10 at 14:15

2

@ Konrad - Good point. Edited! However, next time, feel free to edit it yourself.
–
Kevin VermeerJul 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.
–
egregFeb 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?
–
KurtFeb 26 '13 at 13:49

@Kurt Maybe adding a note about adding it if requested in comments can be worthy.
–
egregFeb 26 '13 at 13:53

@Caramdir -- you seem to be the source of the suggestion "(make a backup)". i'd like to suggest an alternative (i hesitate to edit the text directly, as it's quite venerable by now): "make a copy (and edit that)". even if the source is under version control, it's usually not a good idea to make changes that might not get reverted when one is rushed into production. (to be continued with a different suggestion.)
–
barbara beetonSep 22 '14 at 15:48

another bit that might be added (although the text is already very long) is how to make a "minimal" image to insert. recently i've noticed a number of images that consisted of an entire, nearly empty, page, with text too small to be read. a link to a suitable explanation should suffice. i'm not sure there's an existing great answer, but that can be remedied; i'll try to research the available postings.
–
barbara beetonSep 22 '14 at 15:50

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. However, it is advised that you provide the community with something that will reproduce the problem in the easiest way possible. Typically this requires code that starts with \documentclass and ends with \end{document} (if using LaTeX). It will allow readers to copy-and-paste-and-compile your code and see exactly what problems you might be experiencing.

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.

＋ Good:

% Assuming your problem is related e.g. to the rotation of a figure, you might need:
\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:

＋ Good:

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.

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/.

@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.
–
doncherryFeb 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.
–
QrrbrbirlbelFeb 3 '13 at 1:43

2

@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.
–
doncherryFeb 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.
–
KurtFeb 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”.
–
doncherryMar 16 '13 at 18:24

@doncherry No problem. Perhaps a new question like "How to check if my system is up to date?"
–
KurtMar 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.
–
doncherryJan 26 '14 at 11:13

There's a sample file called xampl.bib (installed with all TeX distributions) that can be used for dummy citations. (The glossaries package also comes with a load of dummy entries that can be used in MWEs.)
–
Nicola TalbotAug 15 '14 at 10:48

@Mico I’d argue that even though rotating loads graphicx anyway, it’s still good practice to load graphicx explicitly to get well-readable and comprehensible code, and also in case you want to add an option to graphicx later?
–
doncherryMar 1 at 15:35

@doncherry - I fully agree with your proposition in general. It's just that the comment made the specific example explicitly about rotating a float; for such a use case, it should be ok to pare back the example a bit more and load only the rotating package, right?
–
MicoMar 1 at 19:24

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.

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 SuomelaJul 29 '10 at 20:34

2

+1 for observing that this is a good way to debug the problem oneself
–
Norman GrayJul 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.
–
denilwFeb 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.
–
GopiJul 11 '11 at 13:55

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?".

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.

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 VermeerJul 29 '10 at 22:54

@reemrevnivek: Really? I'm not used to seeing that behaviour in StackOverflow.
–
Will RobertsonJul 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 VermeerJul 30 '10 at 12:22

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.