diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-minxampl.html')
-rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-minxampl.html | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-minxampl.html b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-minxampl.html new file mode 100644 index 00000000000..75e9c7b1b0f --- /dev/null +++ b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-minxampl.html @@ -0,0 +1,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> |