44

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.

10
  • 2
    Since this applies to both BibTeX and biblatex, maybe it should be called something like "minimal working example with bibliography"?
    – Sverre
    May 10, 2014 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, 2014 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? May 11, 2014 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, 2014 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, 2014 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 :) May 12, 2014 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, 2014 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, 2014 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, 2014 at 16:15
  • Side note: this does not work with the current standard MikTex environment. tex.stackexchange.com/questions/416818/…
    – J. Doe
    Feb 23, 2018 at 10:56

1 Answer 1

38

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.

13
  • 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, 2014 at 15:41
  • 1
    @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, 2014 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, 2014 at 16:25
  • 5
    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, 2014 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, 2014 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, 2014 at 11:16
  • Some more thought about point 1: who drafts answers to stackexchange in a "production" directory?
    – T. Verron
    Sep 19, 2014 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. Sep 19, 2014 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, 2014 at 18:21
  • I tried with two keys, like this: \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}, } @book{key2, author = {Author, A.}, year = {2010}, title = {Title}, publisher = {Publisher}, } \end{filecontents} \begin{document} \cite{key,key2} \printbibliography \end{document} But I get the following entry could not be found in the database: key2
    – NCH32
    Jul 24, 2020 at 9:27
  • 1
    @NCH32 The example works for me (at least when I add a few line breaks that I assume are there in your real document, but were mangled by the formatting in the comments). I explained the most likely reason for the issue in my comment under your question tex.stackexchange.com/q/554240/35864. In a current version of LaTeX filecontents won't overwrite existing files even if you load \usepackage{filecontents}. You can use \begin{filecontents}[force]{\jobname.bib} to allow overwriting existing files.
    – moewe
    Jul 24, 2020 at 19:41
  • 1
    @NCH32 I edited the answer to take into account the changes in current LaTeX versions. Let me know if things are clearer now.
    – moewe
    Jul 24, 2020 at 19:54
  • @moewe: you're right about the line breaks and the underlying issue. [force] solved the problem. I had browsed the documentation but was looking for what I thought was bib-specific, so I overlooked this. Thanks so much! Big aha moment :)
    – NCH32
    Jul 25, 2020 at 6:54

You must log in to answer this question.

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