28

Someone asks me to write a MWEB.

How can I produce such thing?


Explanation of the question's purpose:

This question aims to complete the very useful other question "I've just been asked to write a minimal example, what is that?" for the cases concerning bibliography files.

I see a lot of MWE which call a .bib file. In most cases, the content of this bibliography file is pasted inside a separated code block (when the .bib is not forgotten...). This (bad) practice creates a loss of time. Indeed, the reader have to copy and create two different files to test the code. The filecontents package fixes this issue. Therefore, in my opinion, the use of filecontents should be generalized to all MWE calling a bibtex file.

I created this question to be able to refer to it when someone forget to add the .bib file to his example or when the question is about bib* and there is no MWE at all. Of course, this question aims to be community wiki. Please improve by all means the answer I will post below.

  • 2
    Since this applies to both BibTeX and biblatex, maybe it should be called something like "minimal working example with bibliography"? – Sverre May 10 '14 at 14:18
  • @Sverre Good point! And I will also remove in my answer any mention of bibtex file to avoid the possible misunderstanding. – ppr May 10 '14 at 15:13
  • 3
    Though I think this is a useful question, I've never heard the expression MWEB used before. Do we not have enough obscure acronyms already? – Paul Stanley May 11 '14 at 11:46
  • @PaulStanley I introduced this expression. Instead of asking people to upload/paste their .bib files (they often forget to do it), we can now ask them to write a MWEB (and, luckily, they will do it using in only one file by using filecontents. When you just ask for the .bib, you will have the bib separated from the .tex... MWEB is here to mean "I want both in the same file". – ppr May 11 '14 at 12:35
  • @PaulStanley I don't have the feeling we have a lot of acronyms in TeX.SE. We have MWE but I couldn't find another one right now. – ppr May 11 '14 at 12:40
  • This bibliography tutorial by andy-roberts provides good start for beginners with bib.tex and sample.bib to test pdflatex bibtex pdflatex pdflatex sequence and automation tools(latexmk,arara), BTW good meta Q on MWEB :) – texenthusiast May 12 '14 at 2:26
  • 1
    Fwiw, there’s a mini-bib-MWE in my answer to the MWE question meta.tex.stackexchange.com/a/3225/4012 under “Bibliography Files”, but it might be worthwhile having a separate question. However, I agree with @Paul about not needing another acronym to confuse unexperienced users, who are probably struggling enough with all the *TeX* words they’re confronted with. – doncherry Sep 20 '14 at 8:36
  • @doncherry I created this question/answer just to be able to refer to it when helping someone. I prefer to say "could you give me a MWEB ?" than other things. But if you think there are too many acronyms, don't use this one! Using it or not is a personal matter and I don't ask the community to approve it. – ppr Sep 20 '14 at 18:15
  • MWEB also has the potential to be confused with both the web and web2c. I agree with @doncherry and Paul Stanley. – cfr Sep 21 '14 at 16:15
  • Side note: this does not work with the current standard MikTex environment. tex.stackexchange.com/questions/416818/… – J. Doe Feb 23 '18 at 10:56
23

A MWEB is a MWE (Minimal Working Example) which include a bibliography file (.bib). MWEB stands for "Minimal Working Example with Bibliography".

The bibliography file contains your bibliographical references. If your question is about Bibtex/Biber/Natbib/Biblatex/..., this file may contain valuable information useful to answer it.

You should use the filecontents environment in order to produce only one file which contains both your latex document and your bibliography file. This file should be copy-and-pasted inside a code block. Having only one file allows us to copy and paste the example to test it in a single action.

Example of MWEB (for BibLaTeX):

\documentclass{article}
\usepackage[style=authoryear-comp]{biblatex}
\addbibresource{\jobname.bib}
\usepackage{filecontents}

\begin{filecontents}{\jobname.bib}
@book{key,
  author = {Author, A.},
  year = {2001},
  title = {Title},
  publisher = {Publisher},
}
\end{filecontents}

\begin{document}

\cite{key}

\printbibliography

\end{document}

Example of MWEB (for BibTeX):

\documentclass{article}

\usepackage{filecontents}

\begin{filecontents}{\jobname.bib}
@book{key,
  author = {Author, A.},
  year = {2001},
  title = {Title},
  publisher = {Publisher},
}
\end{filecontents}

\begin{document}

\cite{key}

\bibliographystyle{plain}
\bibliography{\jobname}

\end{document}

Some important points:

  1. You should use \jobname instead of a specific .bib file name. In this way, the filecontents environment will take the name of the .tex file in order to generate the related .bib file. This practice avoids the accidental overwriting of a named .bib file (people often used to call their bibliographies "bibliography"; a dangerous practice).

  2. The original filecontents environment could not be used before the \documentclass declaration. This environment is now allowed anywhere in the document’s preamble; it must be preceded by \usepackage{filecontents}, which explicitly removes the original limitation.

  3. Unlike another common thought, you shouldn't use filecontents* (note the star) environment. filecontents* does not aim to overwrite the file but is designed to remove the mention "[...]generated by the ‘filecontents’ environment[...]" at the top of the file. The new implementation of filecontents (which you use when you call the filecontents package) automatically overwrites the file if it exists (so that point 1 is important).

Warning

Do not paste your entire bibliography inside a filecontents environment! You should paste only the problematic references that will demonstrate the problem when the MWEB is processed. Keep in mind to be as minimalistic as possible.

  • I don't think 3. and 4. are worth mentioning in this context. Also, I've never heard about the "common thought" you mentioned in 3., nor have I ever seen anyone put filecontents before documentclass. – Sverre May 10 '14 at 15:41
  • @Sverre 3. and 4. are common mistakes about filecontents. These ideas was (wrongly for 3.) defended in the first implementation of filecontents. There are today not true but people (old users) sometimes still defend them (I saw it few times in TeX.SE). I think a little reminder does not hurt anybody. – ppr May 10 '14 at 15:48
  • 1
    Well, I suspect very few (i.e. none) of those who need a detailed explanation on how to include a .bib file into a MWE are experienced users who know about the traditional implementations of the filecontents package. Don't forget who this text is for, and who it's not for. – Sverre May 10 '14 at 16:25
  • 3
    I think the focus should be on writing an MWE that uses a bibliography, and that there are two ways of doing that. 1. Use an already existing bib source, like xampl.bib, or biblatex-examples.bib for Biblatex; or 2. If the problem only manifests with your own bib file, use filecontents. – pst May 12 '14 at 10:27
  • @pst Good point. Like the answer is community wiki, you could add the existing bib source solution to it. – ppr May 12 '14 at 13:27
  • About point 1., it seems more dangerous to me than hardcoding a filename. Someone with a similar file in the directory will more easily notice the risk than if the duplicate name comes from \jobname. The best solution may be to generate a random string (or derivate it from the question/answer id), so that it is very unlikely that anybody ever named his bibliography this way? – T. Verron Sep 19 '14 at 11:16
  • Some more thought about point 1: who drafts answers to stackexchange in a "production" directory? – T. Verron Sep 19 '14 at 11:17
  • 1
    i've tidied up the english and streamlined some of the text, without (intentionally) changing the meaning. some of the earlier comments have merit, but i didn't address them in my edit. if you have better ideas, please apply them. – barbara beeton Sep 19 '14 at 16:53
  • @barbarabeeton thanks a lot. I'm no native English speaker and you did a great job improving my English ! – ppr Sep 20 '14 at 18:21

You must log in to answer this question.

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