357

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?

Reference:

9

12 Answers 12

246

This answer focuses more on minimalizing the code, rather than finding the source of the problem, as the once top-voted answer does. It is intended to be concise and hands-on, but digestible rather than exhaustive. Suggestions for improvement are 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.

What follows below are snippets of code; bad references imply that it should typically not be used, as it may not be part of the problem, while good references make suggestions that should be used instead. Note that these snippets should still form part of a larger, \documentclass...\end{document} structure as mentioned above.

Document Class

- Bad:

\documentclass{MyUniversitysThesisClass}

- Bad:

\documentclass[..]{standalone}

...unless your problem relates to the standalone document class. standalone is meant for cropping stand-alone images within a main document usually. If this doesn't pertain to you, don't use it.

+ 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{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{graphicx}
....
\includegraphics{example-image}% Image from the mwe package

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.

If your problem is specific to the size of the included image, still use mwe's example-image, but also specify the width and height so it more readily replicates your custom-image dimensions. Again, this way the problem is reproducible without using your 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:

\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:

\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).

Index

+ Good:

\begin{filecontents*}{\jobname.ist}
delim_0 "\\dotfill "
\end{filecontents*}

The index style can be included in the filecontents* environment in the preamble. The contents (and file extension) will differ according to the required indexing application (makeindex or xindy).

Sometimes a problem can only be demonstrated with an index that spans several pages. The testidx package is like lipsum etc but the dummy text is interspersed with \index to make it easier to test index styles. It has over 400 top-level terms (along with some sub-items and sub-sub-items) that includes every basic Latin letter group (A–Z) as well some extended Latin characters and a few digraphs.

- Bad:

\begin{document}
aa\index{aa}
ab\index{ab}
...
zy\index{zy}
zz\index{zz}
\printindex
\end{document}

+ Good:

\begin{document}
\testidx    
\printindex
\end{document}

If page breaking is the source of your problem (for example, after a letter group heading or between an item and sub-item), there's a high probability of an awkward break occurring given the large number of test items, but you can alter the page dimensions or font size to ensure one occurs in your MWE.

Glossaries

The glossaries package comes with some files containing dummy entries, which can be used in MWEs.

- Bad:

\newglossaryentry{sample1}{name={sample1},description={description 1}}
...
\newglossaryentry{sample100}{name={sample100},description={description 100}}
\newacronym{ac1}{ac1}{acronym 1}
...
\newacronym{ac100}{ac100}{acronym 100}

+ Good:

\loadglsentries{example-glossaries-brief}
\loadglsentries[\acronymtype]{example-glossaries-acronym}

See Dummy Entries for Testing for a complete list of dummy entry files provided by glossaries. There's an additional file example-glossaries-xr.tex provided by glossaries-extra.

Formatting your code

Formatting of code is done using Markdown. See the relevant FAQ How do I mark code blocks?. There also exists some syntax-highlighting, a discussion of which can be following at What is syntax highlighting and how does it work?.

With the above in mind, don't post your code in comments, since comments only support a limited amount of Markdown.

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.

11
  • 29
    This is excellent. We could use this as a basis for a more useful mwe tag wiki. Commented Jan 31, 2013 at 20:11
  • 3
    Indeed, this is really great work! Thanks!
    – Jake
    Commented Jan 31, 2013 at 20:16
  • 1
    @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
    Commented Feb 2, 2013 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. Commented Feb 3, 2013 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.
    – doncherry
    Commented Feb 3, 2013 at 15:12
  • @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
    Commented Jan 26, 2014 at 11:13
  • 1
    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.) Commented Aug 15, 2014 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?
    – doncherry
    Commented Mar 1, 2015 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?
    – Mico
    Commented Mar 1, 2015 at 19:24
  • For some problem, dummy texs from lipsum and other package are not a good idea, as it could interfere with box decomposition mechanism (for example, in reledmac)
    – Maïeul
    Commented Nov 24, 2017 at 10:47
  • There’s one piece of advice in there that I see differently: I often want to rasterize a MWE at a given dpi and have it fit within the size limits of TeX.SX. \documentclass[varwidth=...]{standalone} is great for that, although sometimes I need to insert a minipage environment instead.
    – Davislor
    Commented Jan 31, 2019 at 7:30
156

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.

7
  • 17
    I've never seen th abbreviation 'SSCCE': I think 'MWE' is much more common.
    – Joseph Wright Mod
    Commented Jul 29, 2010 at 20:41
  • 6
    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. Commented Jul 29, 2010 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. Commented Jul 30, 2010 at 14:15
  • 2
    @ Konrad - Good point. Edited! However, next time, feel free to edit it yourself. Commented Jul 31, 2010 at 15:34
  • @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.) Commented Sep 22, 2014 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. Commented Sep 22, 2014 at 15:50
  • @JosephWright what's the current version of the 'if you don't have enough rep to post images ...' advice?
    – cfr
    Commented Dec 4 at 6:26
37

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!

4
  • 51
    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. Commented Jul 29, 2010 at 20:34
  • 2
    +1 for observing that this is a good way to debug the problem oneself Commented Jul 29, 2010 at 21:23
  • 2
    +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
    Commented Feb 8, 2011 at 21:18
  • 5
    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
    Commented Jul 11, 2011 at 13:55
33

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.

27

You may find the mwe package from CTAN helpful. Announcement:

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 with the example:

\documentclass{article}
\usepackage{mwe}
\begin{document}

\blindtext

\noindent
\includegraphics[width=.4\textwidth]{example-image-a}\hfill
\includegraphics[width=.4\textwidth]{example-image-b}

\blindtext

\end{document}

The above example shows how to include images in a MWE.

2
  • 1
    Thanks for posting it here. I was planning to do so, but I didn't found time yet.
    – Martin Scharrer Mod
    Commented May 10, 2012 at 8:16
  • Might be useful to include an excerpt of the MWE from the announcement on some of its basic features. Commented Aug 28, 2021 at 5:06
17

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

2
13

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.

3
  • 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. Commented Jul 29, 2010 at 22:54
  • @reemrevnivek: Really? I'm not used to seeing that behaviour in StackOverflow. Commented Jul 30, 2010 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 Commented Jul 30, 2010 at 12:22
7

1 Start a fresh file

This one certainly will compile:

\documentclass[10pt]{article}% <<< well known document class

\begin{document}% <<< you can't compile without
hi world%         <<< some content to compile
\end{document}% <<< you can't compile without

hiWorld

2 Include your problematic code

Just as an example let me pick The sign pi doesn't appear for educational purpose only. So, let's include the two lines of code which are claimed to not show the pi-symbol:

\documentclass[10pt]{article}% <<< well known document class
% ~~~ NO package specified (which can be a problem for us, your reader) ~~~
\begin{document}% <<< you can't compile without

% ~~~ the posted problematic code ~~~~~~~
\textbf{Perímetro:} $2\pi r$\\
\textbf{Área:} $r\pi^2$\\+

\end{document}% <<< you can't compile without

compile1

Though it compiles, it's not an MWE ... because it shows the pi-symbol, it doesn't cause the problem claimed (not showing pi).

3 Digging deeper

The orignal post mentions some font changes, where it is not too clear, what is needed, and what's irrelevant here. As a reader I'm in a bad position, as I have to guess, what else might have been coded. So, let's try this from the posted question:

\documentclass[10pt]{article}% <<< well known document class

% ~~~ changing font IS part of the problem ~~~~~~~
\usepackage{fontspec}
\newfontfamily{\miletra}{MILETRA}[
  NFSSFamily=MiLetra,
  Path=./,
  Extension=.ttf,
  UprightFont=*,
  BoldFont=*,
  BoldFeatures={FakeBold=3},
]

\renewcommand{\familydefault}{MiLetra}

\begin{document}% <<< you can't compile without

% ~~~ the posted problematic code ~~~~~~~
\textbf{Perímetro:} $2\pi r$\\
\textbf{Área:} $r\pi^2$\\+

\end{document}% <<< you can't compile without

Now, I'm done as a reader, because I simply haven't installed the Miletra font on my system.

4 What can you do instead?

Where I have to guess, you have your code. Try copying only those parts, which make it compile again AND shows your problem. Be minimalistic (hence the name), by leaving out. If you are not sure about some code fraction, try compiling with and without said part. If it can compile without, do without.

You can also do it in reverse:

  • save your current file under a new name, say "mweOfMyProblem.tex"
  • delete parts, while ensuring "compiles AND shows my problem".

Whichever route you follow, please make sure your code is ready for copy&compile, i.e. has at least this content:

% ~~~ what we need to see in your MWE ~~~
\documentclass% ...

\usepackage% ...
\newcommand% ...
% ...

\begin{document}
% ~~~ just your relevant code here ~~~~~
\end{document}
4
  • 2
    Why don't you just post this answer to the question I've just been asked to write a minimal working example (MWE), what is that? - TeX - LaTeX Meta Stack Exchange, then every time you link, you post a direct link to your answer? (as an advantage, if someone just link to the question, the OP can hopefully find your answer if they scroll down a bit)
    – user202729
    Commented Jan 16, 2023 at 5:40
  • It‘s a frequent problem, illustrated by one specific case. // Comments with links to MWE-posts are frequent reactions from the community. // So I don‘t see much of a problem here. Answers to similar questions could start with a link to this one and just focus on specifics of the question (e.g. when it‘s not about fonts). The basic steps don‘t change.
    – MS-SPO
    Commented Jan 16, 2023 at 7:56
  • 2
    My point is, now there are two questions on meta about MWE and people may randomly link to one of the two.
    – user202729
    Commented Jan 16, 2023 at 8:38
  • Ok. If you follow the link I cited and you may have in mind, there are even many more: tex.meta.stackexchange.com/q/228/245790 ; see the comments there. // I don't see how to avoid randomness, and it may even not be bad. However, that's one of the reasons I started with "how to".
    – MS-SPO
    Commented Jan 16, 2023 at 8:51
6

ConTeXt

Despite being geared towards LaTeX, the other answers are all still broadly applicable to ConTeXt (so go read those first!). However, there are a few important differences.

Overview

A small, but completely valid ConTeXt document looks something like this:

\starttext
    Hello, world!
\stoptext

Beginning and Ending the Document

With LaTeX, \begin{document}/\end{document} are the only valid ways to start and end the document. With ConTeXt, you have a few more options. Options that are recommended for MWEs are in bold.

Begin End Description
\starttext \stoptext Most common method.
\startdocument \stopdocument Runs document:start/stop setups. Useful for title pages.
\startcomponent \stopcomponent For large, multi-file documents.
\startproduct \stopproduct For large, multi-file documents.
\startTEXpage \stopTEXpage A single page tightly wrapped around its content.
\startMPpage \stopMPpage A single MetaPost page.

Document Classes

ConTeXt does not use document classes. Style modules (\usemodule[<name>]) and environments (\environment <name>) are roughly equivalent to LaTeX document classes; however, there are no “standard” styles or environments—it is expected that every user will define their own. But answerers won't have access to your custom styles, so you should copy any relevant content into your MWE.

Packages

As with LaTeX, it's best to remove any unnecessary packages from your MWE. However, the average ConTeXt document uses zero packages, so this is rarely an issue.

Sample Files

Images

\startTEXpage
    \externalfigure[sys:///cow.pdf]
    \externalfigure[sys:///hacker.jpg]
    \externalfigure[sys:///mill.png]
\stopTEXpage

Text

\starttext
    %%% Short
    \samplefile{jojomayer}

    %%% Long
    \processcommalist[
        bryson, carrol, davis, douglas, greenfield, jojomayer,
        klein, knuth, linden, lorem, montgomery, sapolsky, stork,
        thuan, tufte, ward, weisman, zapf
    ]{\par\samplefile}
\stoptext

Bibliography

If your MWE doesn't depend on the exact contents of the bibliography, you can use one of the built-in bibliographies:

\usebtxdataset[mkiv-publications.bib]
\usebtxdefinitions[aps]

\starttext
    One \cite[article]
    two \cite[phdthesis, book]
    three \cite[authoryear][inbook].

    \placelistofpublications
\stoptext

Otherwise, you can include the contents in a buffer:

\startbuffer[bibliography]
    @Book{texbook,
        author = {Donald Ervin Knuth},
        title = {The {\TeX}book},
        publisher = {Addison--Wesley},
        address = {Reading, MA},
        year = {1984},
    }
\stopbuffer

\usebtxdataset[bibliography.buffer]
\usebtxdefinitions[apa]

\starttext
    \placelistofpublications[method=dataset]
\stoptext

Fonts

ConTeXt documents tend to use non-standard fonts much more frequently than LaTeX documents. Try and stick to the fonts included with ConTeXt or included with TeX Live if your issue isn't about a specific font.

Version

LaTeX has been on the same major version for 30 years, and it almost never makes breaking changes, so the version isn't usually relevant. However, ConTeXt currently has two extant versions—MkIV (LuaTeX) and MkXL (LuaMetaTeX)—and breaking changes occur more frequently, so it's highly recommended to include your ConTeXt version somewhere in your question.

You can get the version by running context --version in a terminal, by placing \contextversionnumber somewhere in your document, or by checking the top of your log file:

system          > ConTeXt  ver: 2024.02.27 09:21 LMTX  fmt: 2024.3.6  int: english/english
[...]
system          > ConTeXt  ver: 2023.05.05 18:36 MKIV  fmt: 2024.1.27  int: english/english
[...]

Testing

To figure out if there's a problem with your ConTeXt installation, you can try running your MWE at ConTeXt on Web (no account or sign-in required). If it works there, then the problem is likely with your installation.

Documentation

With LaTeX, there are tons of tutorials, “how-to” guides, example documents, and previous questions, but there is quite a bit less reference material. ConTeXt is the opposite: the reference material is excellent, but there’s not much beginner material or ready-made examples. This can make “how do I do X” questions very difficult since it’s hard to know where to start, but it makes “why doesn’t this work” questions much easier since nearly every command is documented in detail.

Ordered by my subjective opinion of usefulness, some good reference materials are:

4

I think I could add prof. van Duck's tutorials.

Section 3 Asking effective questions on TeX.SE of his first article in TUGBoat 38:3, 2017 explains how to build an MWE.

Section 3 How to format a post in TeX.SE of his third article in TUGBoat 39:3, 2018 explains how to format your question.

2
  • I really like the way you write in English in the TUGBoat because I understand almost everything without the need for a translation machine. And besides, you make me laugh: -)
    – AndréC
    Commented Dec 28, 2018 at 15:48
  • 2
    @AndréC Thank you! I'm not a native speaker, hence my English is simple.
    – CarLaTeX
    Commented Dec 28, 2018 at 16:07
3

A new user asked for a kind of checklist to turn a short code snippet into a MWE. Here's a starting point, as many new members may face similar problems.

1. Requirements of a MWE

Besides all the details mentioned in this question, a few requirements always need to be fulfilled:

  • [_] the code compiles or reproduces the compilation error, when some member copies it into his/her La/TeX environment
  • [_] it show all, what's needed
  • [_] it removed code, packages etc., which are not needed
  • [_] it shows your problem

2. Assumptions to execute this checklist

  • [_] you opened a new file, best in a new location
  • [_] you repeat the compile-cycles with each and every step mentioned below

3. Checklist

3.1 Minimal syntax

  • [_] you started with a suitable \documentclass{}
  • [_] you placed \begin{document} and ended with \end{document}

3.2 Adding your code snippet

  • [_] it's now at a useful place between \begin{document} and \end{document}
  • [_] you added the relevant package(s) you know your code will need via \usepackage and/or \usetikzlibrary
  • [_] you commented out/removed all packages, code lines etc., which are not needed to demonstrate your problem

3.3 Final steps

  • [_] make sure, it compiles or reproduces the compilation error
  • [_] make sure, you followed syntax from Latex and packages you need to use
  • [_] make sure, it still shows your problem
  • [_] clean-up the code a little (consistent formatting, delete not needed parts etc.)
  • [_] create a screenshot from your codes result, if useful
  • [_] check/rethink what you are going to tell and ask

3.4 Post it

  • [_] you described your problem and attempt(s)
  • [_] you posted the screenshot image, if useful
  • [_] you posted and marked your code from 3.3 as code

Example 1: you can make it compile

X1: as posted

The code is taken as an example for this checklist from this question, which actually doesn't ask anything ...

\begin{tikzpicture}
\draw[thick] (0,0) -- (4,0); % rod
\draw[->,>=stealth] (0,0) -- (-1,0) node[left] {$P$}; % left force
\draw[->,>=stealth] (4,0) -- (5,0) node[right] {$P$}; % right force
\node[below] at (2,0) {Tensile load};
\end{tikzpicture}

A compile results in several errors, where the first one is the relevant message:

error1

Looks like it's a good idea to load the tikz package ...

X2: following aboves checklist 3.1 and 3.2

This one now compiles:

\documentclass[10pt,border=3mm,tikz]{standalone}

\begin{document}
\begin{tikzpicture}
\draw[thick] (0,0) -- (4,0); % rod
\draw[->,>=stealth] (0,0) -- (-1,0) node[left] {$P$}; % left force
\draw[->,>=stealth] (4,0) -- (5,0) node[right] {$P$}; % right force
\node[below] at (2,0) {Tensile load};
\end{tikzpicture}
\end{document}

result2

However, the code may need some clean-up, both for better read-ability and improving the result.

If, as a novice, THIS is your problem ("I'd like to show ... but don't know the syntax for it"), that's a good thing to ask in your question:

  • you provided a MWE
  • we see your attempt
  • you stated a goal, which you can't reach at the moment

X3: step 3.3 almost finished

What you present here depends on your experience with Latex. Something you can always do is introducing consistent formatting (indents, way of commenting etc.).

If you are experienced enough with the package, which is tikz in this case, try using its features to clean-up code. This is my result, after asking myself: "what does the member want to show?" Probably he/she wanted:

  • a thick rod
  • two forces
  • that's what I tried to emphasize
\documentclass[10pt,border=3mm,tikz]{standalone}
\usetikzlibrary{arrows.meta}

\begin{document}
 \begin{tikzpicture}[
    arr/.style={->,red},
    >={Stealth},
    ]
    \draw[line width=3pt]   (0,0) -- (4,0); % rod
    \draw[arr]      (0,0) -- (-1,0) node[left] {$P$}; % left force
    \draw[arr]      (4,0) -- (5,0) node[right] {$P$}; % right force
    \node[below] at (2,0) {Tensile load};
 \end{tikzpicture}
\end{document}

result3

Example 2: you can't make it compile at all

This forest-code is used as an example to show, what you can prepare, when compilation continues producing errors.

Y1: as posted

The following code was created somehow and posted, which obviously doesn't pass the syntax check in 3.1. It doesn't compile and complains about "missing forest":

    \begin{forest}
        for tree=draw,
        [Main(), [Level Setup],[Game], [Win_Game()]]
    \end{forest}

errorA

Y2: following the checklist

Though the code starts looking more like a MWE, it still doesn't compile:

\documentclass[10pt,border=3mm,tikz]{standalone}
\usepackage{forest}

\begin{document}
    \begin{forest}
        for tree=draw,
        [Main(), [Level Setup],[Game], [Win_Game()]]
    \end{forest}
\end{document}

errorB

At this point you may decide to post after completing steps 3.3 and 3.4 as good as possible, and ask for help.

As it turns out, the forest code still has some errors in itself. The difference to the code snippet is that you removed almost all guessworking about your code before you post.

To verify, you might e.g. replace the forest-environment by some code from the forest manual. If it compiles, you know the MWE status is fine. You can mention that together with posting the problematic code above.

3
  • @CarLaTeX, thanks for the hint: I'll introduce a change.
    – MS-SPO
    Commented Dec 4, 2023 at 14:05
  • @CarLaTeX, FYI, I did some rework now.
    – MS-SPO
    Commented Dec 4, 2023 at 16:44
  • 1
    Thank you, looks good now!
    – CarLaTeX
    Commented Dec 4, 2023 at 16:51
2

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.

1
  • 7
    :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. Commented Jul 29, 2010 at 20:26

You must log in to answer this question.

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