<< | Page list | >>
How to create a minimal working example (MWE) for LyX.
In a nutshell
A minimal example is a
.lyx file that is as small as possible while still showing the behavior that you are asking about. It should include as few dependencies as possible -- remove any unnecessary pictures and external files. It should be possible for someone to download your
.lyx file and without modification see the same behavior that you are seeing.
Below is more information on how and why to create minimal examples.
Why create a minimal example?
- Minimal examples make it easier for people to see the problem you are talking about and thus easier for them to propose solutions.
- They save time. If 5 people download your
.lyx file trying to help and spend 5 minutes removing the graphics you included and cleaning the LaTeX preamble that is not necessary, then that's 25 minutes of wasted time instead of the 5 minutes that you could spend doing that. By sending a minimal example, you can make it as easy as possible for someone to help you.
- They take time. How is this a good thing? If you show that you are willing to spend time to solve your own problem, this makes it more likely that someone else will want to spend his/her time to help you with your problem.
- Often, once you've removed everything extraneous, the root cause becomes obvious and the problem solves itself.
- While continually removing material in the making of your minimal example, you might run across material that toggles the symptom off when removed, and toggles it back on when put back. Once you get that toggling material down to a few lines, the root cause often becomes obvious, either to you or to those you're asking for help.
How to create a minimal example
- Remove as much as possible from your
.lyx file while still making sure it shows the behavior you are reporting.
- The preamble (top menu bar > Document > Settings... > LaTeX Preamble) should not have anything except what's needed to reproduce the bug (further, it's helpful if you specify that without something in the preamble the problem in question goes away).
- Document settings should not have anything special unless it's needed to reproduce the bug. For example, if you can reproduce the behavior by using the document class
Article (Standard Class) instead of a less common document class, please do so.
- There should be no ERT in the example unless absolutely necessary to reproduce the bug (in which case say this explicitly).
- If the example requires external files, make sure they're included in your email or trac bug report.
- Use relative paths if you need to include external files. Further, relative paths should work when all files are put in the same folder. That is,
../../Dropbox/MyLyXstuff/picture.jpg is relative but bad;
./picture.jpg is relative and good.
- Test your minimal example. Just before you send it, copy the example files to a different folder. See if things compile fine. Make sure that the output still shows the problem you're seeing.
In addition to a minimal example
- It is useful if you attach more files in addition to the example, such as your pdf output (or your log from your attempt to produce a PDF output). Sometimes it's not obvious if the output shows the problem or not (e.g. if it requires a foreign language that the person trying to help does not know how to read). Similarly, it is useful to provide the
.tex file that you export from LyX. This is useful in particular to see if a difference in PDF is due to different LyX versions or different versions of TeX files. For similar reasons, it is useful if you provide the corresponding
- If your question is about LyX's display (and not PDF output), then please provide screenshots.
- It is always a good idea to specify your OS (and its version) and your LyX version (and if Windows, which installer version you used).
Minimal example FAQ
But the error happens for every document. Why should I post an example?
- Many of the reasons here still apply (e.g. to make it perfectly clear what you're talking about, to save the person helping you time, and to show that you're willing to spend time to make and post the example). Further, it is possible that a new document for you is different from a new document for me. The reason for this could be different versions in LyX, or you could have (possibly accidentally) clicked on the "Save as Document Defaults" button, which saves your current document settings as the template for when you create a new document.
Whenever I remove something, my problem goes away. What should I do?
- Knowing that you cannot reduce your
.lyx file is useful information. It not only gives information about the possible bug that you are seeing but it also shows that you made an effort.
What if my
.lyx file contains material that I don't want made public?
- After removing as much as you can, if your
.lyx file still contains private information, state in your email if you would be willing to send this file privately. Usually, however, it's possible to anonymize your minimal example.
How do I post a .lyx file on a forum or a Q&A post without attachments (e.g. tex.stackexchange.com)?
- Although some forums allow you to attach files, some encourage text-only posts (and possibly images). In this case, it is important to recognize that a
.lyx file is just a text file. You can insert the file by opening it in a text editor, copying the entire contents, and pasting as text into your post. Please format the text as "code" or something similar. This way, the viewer can copy your pasted "code", paste into an empty text file, and then open the file with LyX.
- The above method of "attaching" a
.lyx file is preferred to putting a URL to a third-party site where the file was uploaded (e.g. Dropbox), because forums like to preserve posts as long as possible so others with similar problems can see the entire post; and often, links to third-party uploads break over time.
What are other relevant resources for a minimal example?
<< | FAQ.PageList | >>