In this post, I will explain how you can use the filecontents package to create an ‘inline’ .bib file inside your main document.tex . This can, for example, be useful if your LaTeX gets compiled on a server and your method only allows you to pass one single document. If you wanted to pass a .bib file with it, this wouldn’t work out.

Also, for LaTeX releases past fall 2019, the package is no longer required for this functionality, you can use it directly as an environment. I’ll still keep this the way I wrote it. See the documentation here.

Premlinaries: How I ended up writing this

That’s what I initially wrote this little method for: Our publication system archives data following the single source principle: This means that all representations you want, such as a web site or an output PDF, will be generated from one single document. In our content management system, my data are encoded in TEI XML. That means the bibliography is included in the file, unlike in LaTeX where you normally have two separate documents for that. Consequently, we need to do some additional translating between the two formats, apart from the normal XML to LaTeX transformation. And since our content management system generates the aforementioned data representations on-the-fly, they are just dynamic. You can’t stricly speaking access the same compiled document or .tex source after the method was run and the output generated. So first generating the two required files (.bib and .tex) and then running some complex stuff on them will not work. The routine will chuck out some output PDF directly and not much else. And the method is only configured to take this one document, not a .bib file and a .tex file. But thanks to filecontents, we can still get our compiled output PDF with nice automated literature references. I’ll show you how. You can get the XSL transformation snippets from my github.

 

More ramblings to entertain you

So our method only takes one XML file and one XSLT transformation, meaning that the transformation needs to generate one single .tex file which contains the actual .tex file and the .bib file. I am sharing this method with you guys now because I spent a lot of time researching and thinking how to achieve this only to realize that the current version of our system does not support the filecontents package for some reason.

That realization was quite a blow, I can assure you. So basically, all my efforts wasted on a feature which was somewhat of an unnecessary fancy gadget in the first place which nobody really needed anyway 😉 Maybe some of you will find it useful, so my precious work hours spent on this are not totally wasted and will serve to benefit the community. Actually, I wrote this thing sufficiently long ago that I am proud to admit that I have just spent over half an hour trying to unearth it from my backups. I warmly suggest you don’t act like me and only use version control once you’ve successfully lost something. Happens to me in every single project. It takes a data loss for me to accept one really should use VCS (=version control systems).

Get going with filecontents

I have, in fact, created this stylesheet for a scenario where it could have actually been pretty useful, though it wouldn’t strictly have been necessary to generate the output just using one single file: The use case was a scientific paper in TEI-XML where I read the bibliography from the <biblStruct>s, transformed them into four different citation categories (@book, @inproceedings, @online and @article) and had them cited automatically using Biblatex.

Things to know

So all you really need to know is

1. how the filecontents functionality works: It’s basically writing a .bib section at the start of the document and then loading the filecontents package (or not because it’s not required since fall 2019).
2. how to write XSLT rules to transform a <biblStruct> into .bib style references, which is quite some work depending how detailled you want it (do you really need different types of citations? If yes, you’ll need to define conditions for your transformation to know which <biblStruct> is an @book or @article)
3. Self-reflection: Is all of this really necessary and the amount of work in some relation to the effectiveness of the output? As we have seen in my case, it was completely unnecessary labor. So maybe you can get away without an auto-generated bibliography and just value-of-select the unstructured citation. I would have labeled this post in the ‘productivity’ category but really, this is one of the very dangerous types of things you think are a great idea but really just cost you lots of time even though you didn’t actually need the feature. So be warned 😉

Now that I have added enough tales of caution, you can download a minimal working example from this github (XSL file). I won’t bother showing the XSL code in this post. Those interested can always direct themselves to the aforementioned github. The WordPress editor doesn’t like XML much, it often breaks the markup because WordPress tries to interpret it as HTML… So I’ll spare us this nightmare.

Alternatively: thebibliography

The simple, but potentially more laborious alternative if you are using automated XSLT transformations, would be using thebibliography. Here, you would have to work out the sorting mechanism by yourself and wouldn’t be able to change the citation style with ‘one click’ / change (or whatever it is you use to communicate with your computer 😉 ). However, if you want more or less nice references and don’t have tons of structured data – or you realize your content management system somehow just won’t do filecontents, then this might be for you.

So, I thought this was a really cool feature even though I ended up not needing it. It was too complicated – we could also call it fancy – to actually work for the intended use case. So basically, one of those projects you should just stay away from. But since it was so much work I thought I’d share it. Maybe some of you have more senisble use for this.

Cheers,

the Ninja