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
|
<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" 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>The "building up" process 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 occurrs. (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 collapses 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 only works at
all with another package loaded (or only fails in the context of
another package).
<p>The "hacking down" route 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
unneccessary 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), run your minimum file
with <code>\</code><code>listfiles</code> enabled, so as to report which versions of packages
you're using.
<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.latex-einfuehrung.de/mini-en.html">http://www.latex-einfuehrung.de/mini-en.html</a>; source of the
article may be found at <a href="http://www.latex-einfuehrung.de/">http://www.latex-einfuehrung.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>
|
