How to write a MWEB (Minimal working example with Bibliography)?

Question

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.

Answer 1

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}

\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}

\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. By default the filecontents environment does not overwrite existing files. This minimises the risk of data loss, but can be annoying while you create your MWEB, because new entries in the .bib file don't show up.

   • If you are using a new version of LaTeX you can use \begin{filecontents}[force]{\jobname.bib} instead of \begin{filecontents}{\jobname.bib} to allow filecontents to overwrite an existing \jobname.bib file.
   • If you are using an older version of LaTeX, load \usepackage{filecontents} to allow overwriting of files.

   In any case, double check before you run LaTeX that this won't overwrite important files. It is always a good precaution to work in a new, empty test directory.

2. 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).

3. In older LaTeX versions the original filecontents environment could not be used before the \documentclass declaration. If one wanted to remove this limitation, one would load \usepackage{filecontents}, which would also allow the filecontents environment to overwrite existing files.

   This is no longer necessary in newer LaTeX versions and the filecontents package no longer has any functionality with those newer LaTeX versions. So in new versions \usepackage{filecontents} can safely be dropped (which gets rid of a warning).

4. 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.