Enough reledmac to be dangerous: Scholarly Editing with LaTeX & XSLT

Today’s post is my long-awaited take on typesetting scholarly editons using the reledmac package. Not only does it introduce the package but most importantly, it attempts to answer the even more pressing question “How does one get from a digital edition in TEI-XML to a nicely typeset LaTeX-based print version of one’s Digital Scholarly Edition?” In this post, you will learn how to generate the LaTeX code for a critical appartus via XSLT using the reledmac pacakge.


It’s not like there aren’t any resources out there on how to use the reledmac package. Yet those resources are either extremely detailed (way too detailed for a beginner or anybody really who doesn’t need all the details) or extremely brief and maybe lacking the sort of transfer knowledge so that a digital editing audience could make it applicable to their needs. Because most people nowadays (or at least so I assume), in fact, don’t want to just typeset their edition using LaTeX and reledmac. They want to provide a print version for a digital edition based in TEI-XML and thus, need to get the reledmac-LaTeX code via XSLT transformation. And that’s the more tricky part because here it gets complicated. But feasible. So hang on!

What skills do I need to follow this post? If you don’t have XSLT skills yet, either peruse First ever LaTeX Ninja workshop at Harvard: “Beyond TEI: Digital Editions with XPath and XSLT for the Web and in LaTeX” to learn the basics or consider if you are happy with the output generated by the TEI-to-reledmac web tool provided by the TEI Critical Apparatus Toolbox. You don’t need to know XSLT or even LaTeX to use that.

Context

This post is based on the very short intro to LaTeX and reledmac from the First ever LaTeX Ninja workshop at Harvard: “Beyond TEI: Digital Editions with XPath and XSLT for the Web and in LaTeX”. You can find the slides on LaTeX here – and the rest of the workshop is in the same github repo too.

As of now, I think typesetting textcritical editions with reledmac is the single most (and probably, sadly really the single) well-known and appreciated usecase of LaTeX for which there is any considerable awareness in the Digital Humanities. All the more reason that I finally write a post about it!

There are already a few tutorials available, so the only way for me to really add to them is to be more accessible. After all, it’s a known issue that many tutorials written by experts are written in a way which correctly explains everything but is only understandable if you’re already an expert or at least somewhat familiar with what’s going on. So I’ll try to provide a really low entrance barrier tutorial for actionable reledmac usage for the DH, that being an XSL transformation scenario directly from XML.

Below this post, you may also find a list of resources which contains all the other introductory blogposts, documentation, etc on using reledmac that I could find.

The reledmac package

Unlike some other resources on this topic, I won’t explain here what a critical edition is. My Harvard workshop slides (as linked above) also contain an intro to digital scholarly editing, so please consult that if you need or want to. Otherwise, I assume that most people who find this post and have an inner compulsion to learn reledmac already have an idea what a critical apparatus is. In fact, they likely came here just because they realized those things are not that trivial to typeset and have fun doing that with MS Word. (If relevant: How to quit MS Word for good. Also, since I will be teaching a class on Digital Scholarly Editions in the fall term, I might actually write a post about digital scholarly editing in the near future.)

Since you’re reading this post on this blog, you have probably already assumed that reledmac is a LaTeX package to tackle just that problem I just described above. In the – very useful – Overleaf template with a minimal example of using reledmac, the authors define reledmac as follows:

reledmac is a pack­age for type­set­ting schol­arly crit­i­cal edi­tions, re­plac­ing the es­tab­lished led­mac and eled­mac pack­ages. The pack­age sup­ports in­dex­ing by page and by line num­bers, and sim­ple tab­u­lar- and ar­ray-style en­vi­ron­ments.

Maïeul Rou­quette (uploaded by LianTze Lim), Type­set­ting schol­arly crit­i­cal edi­tions with reledmac
This is a preview what working with that Overleaf template looks like. On the left, you see some reledmac code, on the right an example of what the resulting apparatus would look like.

As a package, reledmac has some issues and might be a bit weird to use at first. This is due to it being part of what is essentially a pretty old project of developing and maintaining a means of typesetting critical editions using LaTeX. There are 500 pages of package documentation and the package will do pretty much anything and everything you might want to do. This is where I and the above mentioned – very useful – Overleaf template come in. Like it is the case with many LaTeX packages and their ample documentation, these resources usually aren’t tailored to teaching the basics. That’s why you need an entry point with a lower entrance barrier and my very short intro slides to reledmac provide just that.

Essentially, you need to load the package and define what you apparatus should look like.
Then you start a piece of text with apparatus. Within that piece of text declared as a text critical edition in reledmac terms, you put the text and whenever you wish to add a note, you mark something as a lemma in which the notes will then be nested. Apart from the fact that this, like it is the case with almost all markup when it starts getting complicated and has a lot of nesting, is an utter mess to work with, it shouldn’t be particularly hard to grasp on a conceptual level. (If it still is, feel free to pause here until you feel ready to continue).

Now it gets a little more complicated because I’m assuming that nowadays, most people don’t actually want to typeset their edition manually. They want to use LaTeX because it allows them to create both a digital edition as well as a LaTeX-based print output from their TEI-XML data (which is a pretty neat format to be long-term archived) using the single source principle. (Read more about that in the Beyond TEI workshop slides).

This means that you want to create LaTeX code from TEI-XML using XSLT that also happens to use the commands of the reledmac package. This isn’t that trivial because it requires a lot of skills actually (TEI-XML, XPath, XSLT, LaTeX, reledmac package) and apart from that, there is a certain complexity to the critical apparatus itself. This will show both in the TEI as well as in the resulting reledmac code. And, of course, the intermediary XSLT template creating said code from the TEI. Now where to begin?

I think for most people, learning to do a critical apparatus in TEI or learning to typeset it in reledmac isn’t that difficult. After all, both are markup and consist of nesting critical notes below a lemma. If you have a general understanding of critical editing, this shouldn’t pose an insurmountable obstacle. The XSLT itself is feasible, too, once you’ve familiarized with some of the knacks involved in generating LaTeX code from XSLT (how to set up the transformation scenario correctly, how to use <xsl:text> to ‘escape’ LaTeX code, how to not end up with unnecessary paragraphs and empty lines in the LaTeX output using xsl:output, etc.). None of this is rocket science but what makes it a little hard is the complexity. And there’s a lot of complexity added up here. So be kind to yourself and take your time. You can do it!

Below are a few ideas on how to get started in a step-by-step learning progression.

Setting up a transformation scenario can be daunting at first, so in case you had forgotten, this image shows how to do it (it’s from the slides to go with the First ever LaTeX Ninja workshop at Harvard: “Beyond TEI: Digital Editions with XPath and XSLT for the Web and in LaTeX”). In 4.1., you need to use a .tex file ending instead of the .xml (here you also needn’t be afraid to overwrite your original XML because the new file you’re creating has a different file ending). The result will be LaTeX code. To render this as a PDF, you need to compile it – using LaTeX on your machine or, for example, in Overleaf (learn more about those basics here: Jumpstarting: Learn LaTeX in 3 minutes).

How to get started (step-by-step learning progression)

  1. Familiarize yourself with LaTeX for Humanities: If you haven’t done LaTeX before, you might want to start by perusing A Humanities’ seminar paper with LaTeX – in 10 minutes (the blog post and the Overleaf template it is about). That will allow you to get a grasp on how LaTeX works first. Then, you need to understand reledmac for which you may use the above mentioned template or maybe best write your own minimal example of what it is you want to do.
  2. Try (and play around with) the Overleaf reledmac template: Maïeul Rou­quette (uploaded by LianTze Lim), Type­set­ting schol­arly crit­i­cal edi­tions with reledmac
  3. Try a simple “To LaTeX” transformation using XSLT (90 lines of code): If you haven’t created LaTeX output using XSLT before, try the Simple XML to LaTeX Transformation Tutorial using the mini-latex.xsl template. There is an XML file in the folder with it that you may use for testing purposes. Make sure you learn how to set up the transformation scenario correctly and compile a PDF from the LaTeX code. Note how to create a ‘simple’ LaTeX command (\emph{test}) and how to achieve an environment (\begin{quote}...\end{quote}) via XSLT transformation.
  4. Look at my simplified XSLT “to reledmac” template (850 lines of code): This template is an adapted version of the three resources I found and used on reledmac. They are: code examples from the RIDE reledmac review, the reledmac XSLT transformation underlying the web tool from the TEI Critical Apparatus Toolbox (very complicated, especially as the options passed on via the web form make the code harder to understand) and, of course, our trusted Overleaf template. The idea was to learn how the basic constructs work (make sure you really understand the basics from step 3 before doing this because the complexity is much higher here!) but to also have a template which can realistically transform an actual TEI-XML document with a critical apparatus. This already requires a good number of things, thus the code is relatively long and complicated. But I hope it’s understandable enough that you can slowly work your way through it! Some long template rules come from the Critical Apparatus toolbox – just leave them as they are unless you really understand their purpose. I even made comments in some places that you should just ignore this code 😉
  5. Adapt the code from the example template to fit you own data. Congratulations on your critical edition! I’d love to see it or even promote it here if you want to share!

So I hope you have fun typesetting your critical editions using reledmac. Or at least you have somewhere to get started. I’m not pretending that it’s going to be easy, especially if you master neither XSLT nor LaTeX before setting out on this journey. But both can be learned and those famed workshop slides (and materials) should theoretically have all you need to get started if you really wanted to. In the blogpost to go with the workshop, I also share some other resources – in case you need to brush up on your XML, TEI, XSLT skills or any of the like.

Let me know if there’s any important info I might have missed and feel free to ask in the comments if you have any questions!

Ok, that’s it for now.
Thanks for all the fish!
Best,

the Ninja

Resources

Buy me coffee!

If my content has helped you, donate 3€ to buy me coffee. Thanks a lot, I appreciate it!

€3.00

I like LaTeX, the Humanities and the Digital Humanities. Here I post tutorials and other adventures.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.