1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
<head>
<title>UK TeX FAQ -- question label minxampl</title>
</head><body>
<h3>How to make a “minimum example”</h3>
<p/><a href="FAQ-askquestion.html">Our advice on asking questions</a>
suggests that you prepare a “minimum example” (also commonly known
as a “<em>minimal</em> example”) of failing behaviour,
as a sample to post with your question. If you have a problem in a
two hundred page document, it may be unclear how to proceed from this
problem to a succinct demonstration of your problem.
<p/>There are two valid approaches to this task: building up, and hacking
down.
<p/>
<b><em>Building up</em></b> starts
with a basic document structure
(for LaTeX, this would have <code>\</code><code>documentclass</code>,
<code>\</code><code>begin{document}</code>, <code>\</code><code>end{document}</code>) and adds
things. First to add is a paragraph or so around the actual point
where the problem occurs. (It may prove difficult to find the actual
line that’s provoking the problem. If the original problem is an
error, reviewing
<a href="FAQ-errstruct.html">“the structure of TeX errors”</a>
may help.)
<p/>Note that there are things that can go wrong in one part of the
document as a result of something in another part: the commonest is
problems in the table of contents (from something in a section title,
or whatever), or the list of <<i>something</i>> (from something in a
<code>\</code><code>caption</code>). In such a case, include the section title or caption
(the caption probably needs the <code>figure</code> or
<code>table</code> environment around it, but it <em>doesn’t</em> need
the figure or table itself).
<p/>If this file you’ve built up shows the problem already, then you’re done.
Otherwise, try adding packages; the optimum is a file with only one
package in it, but you may find that the guilty package won’t even load
properly unless another package has been loaded. (Another common case
is that package <i>A</i> only fails when package <i>B</i> has been
loaded.)
<p/>
<b><em>Hacking down</em></b> starts
with your entire document, and
removes bits until the file no longer fails (and then of course
restores the last thing removed). Don’t forget to hack out any
unnecessary packages, but mostly, the difficulty is choosing what to
hack out of the body of the document; this is the mirror of the
problem above, in the “building up” route.
<p/>If you’ve added a package (or more than one), add <code>\</code><code>listfiles</code> to
the preamble too: that way, LaTeX will produce a list of the
packages you’ve used and their version numbers. This information may
be useful evidence for people trying to help you.
<p/>What if your document simply doesn’t fail in any of these cut-down
scenarios? Whatever you do, don’t post the whole of the document: if
you can, it may be useful to make a copy available on the web
somewhere: people will probably understand if it’s impossible ...
or inadvisable, in the case of something confidential.
<p/>If the whole document is necessary, it could be that it’s an overflow
of some sort; the best you can do is to post the code “around” the
error, and (of course) the full text of the error.
<p/>It may seem that all this work is rather excessive for preparing a
simple post. There are two responses to that, both based on the
relative inefficiency of asking a question on the internet.
<p/>First, preparing a minimum document very often leads <em>you</em> to the
answer, without all the fuss of posting and looking for responses.
<p/>Second, your prime aim is to get an answer as quickly as possible; a
well-prepared example stands a good chance of attracting an answer
“in a single pass”: if the person replying to your post finds she
needs more information, you have to find that request, post again, and
wait for your benefactor to produce a second response.
<p/>All things considered, a good example file can save you a day, for
perhaps half an hour’s effort invested.
<p/>The above advice, differently phrased, may also be read on the web at
<a href="http://www.minimalbeispiel.de/mini-en.html">http://www.minimalbeispiel.de/mini-en.html</a>; source of that
article may be found at <a href="http://www.minimalbeispiel.de/">http://www.minimalbeispiel.de/</a>, in
both German and English.
<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl</a>
</body>
|
