Back to the talks Previous by track: Reading and writing emails in GNU Emacs with Gnus Next by track: Basic Calc functionality for engineering or electronics Track: General

LaTeX export in org-mode: the overhaul

Pedro A. Aranda Gutiérrez (he, him) - paaguti@gmail.com, paaguti@gmail.com

Format: 34-min talk ; Q&A: BigBlueButton conference room Etherpad: https://pad.emacsconf.org/2025-latex
Etherpad: https://pad.emacsconf.org/2025-latex
Status: TO_REVIEW_QA

00:00.000 Introduction
00:41.400 Motivation
02:53.360 Evolution
06:02.480 What do you get from the feature branch?
08:47.280 Behind the scenes: .dir-locals.el
11:59.080 When fontspec is not enough
15:21.080 Rationale behind my take at LaTeX font management
18:34.480 Demonstrations
22:57.475 Demo: Emoji
23:33.180 Demo: Letter
25:44.400 Demo: Side by side
28:12.600 Thanks
29:47.120 Q: What about video (mp4) support for ox-latex?
Duration: 33:53 minutes

Description

During the last year, the LaTeX backend in Org mode has received an overhaul. The objectives, while keeping backward compatibility, were:

  • Better integration of the font-management features and packages with lualatex/xelatex
  • Reducing the amount of #+LATEX_HEADER: lines and avoiding to have to include a pure LaTeX file to profit from them
  • Flexibility, while using native Emacs Lisp features, like file/directory local variables

In this talk, I will present the new font management features in the LaTeX backend and show a couple of examples of what can be achieved.

About the speaker:

After 30 years using Emacs, professionally and for my PhD, I'm currently quite involved in org-mode, where I'm revamping the LaTeX backend.

Discussion / notes

  • Not a question but I will start using LaTeX fonts in org now
  • Q: How's about video (mp4) support for ox-latex? I start to give presentations with many videos. This is something that really push me back using ox-latex.
    • A: Experiment with a LaTeX file and then try to include the relevant snippets in #+BEGIN_EXPORT latex
    • https://github.com/pdfpc/pdfpc/ can embed and play videos. For Org, latex fragments work fine.
      • Thank you for all your information, I will try it and see. Thank you.

Transcript

[00:00:00.140] Introduction
Okay. Good afternoon, morning or evening, whatever it is in your time zone. I'm Pedro Aranda and I'm going to be talking about what I've been doing with the latest backend in Org Mode and the different... Sorry... and the way it treats fonts. Just a couple of words before I am going to go through motivation, the evolution and get you an idea of what you can get from the feature branch that I have started and give a couple of demos.
[00:00:41.400] Motivation
Actually, my motivation is I was using ox-latex currently and ox-beamer for as a foundation for my activities, mainly for lecture notes and lecture slides so I came from pure LaTeX and beamers and for me the real cool use case, or I would say this was the killer use case for me was I have a programming lecture, which is sort of a Python 101, and when I'm live in the lecture, I can go, and if the pupils ask me, I can modify code, show modified code and results on the fly, and that's something that really impresses the kids and makes them understand what we are talking about. From my pro... subjective point of view, in some, mainly in ox-beamer, some of the things that I was missing is that emojis would really break the monotony and I missed the support for emojis and stock Beamer themes. And some fonts I also found were suboptimal or difficult to adapt in case they need an adaptation. So, for example, people who need special fonts because of their special capabilities, it's difficult to get those fonts from the stock themes and from the stock font implementations you have there. So, requirements from the Emacs side to do this is none, because basically, okay, the only thing I want is to work on a vanilla Emacs, which is more or less recent, because yes, I'm a bit of a freak and I compile it every two, three... I get it from master and compile it every two, three days. And yahoo, I had to change to a new Mac, and I'm able now to get my vanilla Emacs within four. So that was a big accomplishment in these last days.
[00:02:53.360] Evolution
What is the evolution? I mean my personal evolution and my take of ox-latex was I put everything in a in a LaTeX file and I input it through the LaTeX header, and that's it. But that was not very beginner-friendly, and once I had some people interested in this, "oh wow, I can modify the code on the fly and see the results on the fly," it was more difficult for them to give it a go. So I just... Because they, there are people who have not that big, that much experience with LaTeX and it can even be a bridge to introduce people into LaTeX. So, in any case, it was not very beginner-friendly and I had complaints on that. So, what I think was, we can do better. My first attempt was something that was completely neutral to Babel or Polyglossia. and it was made basically for font LaTeX although some of the things can... for lualatex and some of the things can also be used with xelatex. So overriding template fonts and taking into account fallback fonts was something that I learned when we started this conversation, and the only problem with this is that fallback fonts only work for lualatex because xelatex doesn't support them. Actually, fallback fonts is a lua feature. There was already something in the list regarding script detection which helped me a lot. So big recognition to Juan M. Macias for that, and for his publishing the algorithm or the script in the org mode mailing list. And then came my sort of little nightmare, which was when we started talking about internationalization or localization. Looking back, I have a very strange feeling about a blurring target there. Because the reality, being very, very frank, did I need it? Really no, because I just needed to add Spanish with Babel and that was it. Well actually for me it still is and you can put the British, German or Italian it continues to be true for me, so I had personally, I had little interest in doing that, but I took it as a challenge which has shown to be really tough.
[00:06:02.480] What do you get from the feature branch?
What do you get from the feature branch? The feature branch adds font management for fontspec, which is not strictly needed when you are on Latin, Cyrillic, and Greek scripts as long as the fonts in your template support them. But again, it's a nice way to get better support here. You don't need it if you're happy with the fonts you get from the templates that you use both for Beamer and the document classes in LaTeX. If you don't want to use alternative fonts, you don't need it, but you would need it. Of course, if you don't want things like, for example, emojis or need emojis, you really don't need fallback fonts. So my idea is that the next thing that you can add is Babel and Polyglossia here for enhanced localization and multilingual documents there. And at the end, my vision was that the keywords involved would be language, the main language. And then a nice idea from Ihor was to put all the secondary languages there too. Then specify the LaTeX compiler. Then what I've added is a keyword which is #+LATEX_MULTI_LANG: which can be fontspec or babel or polyglossia for localized documents. By default, this thing is nil and when it is nil, you get the behavior from Org Mode that you already are used to if you don't want to switch. Jing Huang was there and I was really, was chirped into the conversation and really helpful and a big thanks to him because he also had an easy idea to support Chinese and Japanese documents, so that the only thing that you need is to add the language that you're going to write your document in. Very, very big thank you for that, because that was really a challenge not being able to decipher what I was what I was coding there in terms of: I have a document, I copy and paste it from some place, and from there, I get my answer, I get my PDF, and I compare whether it is correct or not.
[00:08:47.280] Behind the scenes: .dir-locals.el
So what is behind the scenes? I've always suggested that in order to use the feature branch efficiently, you create a file with the default values you need for your variables, and that's this famous .dir-locals.el files. What I do is, I have a generic one in my home documents directory, and this is used for all the org documents that are in subdirectories from there. Why? Because normally you will not be changing your fonts that often, and if you need, you can always go and have your configuration locally. So it's this point where I'm collecting my font configuration and for me, this gives me a very, very nice quick start for new documents and presentations. And there you can even configure a lot of compiler and font language management too, so you have everything in a file. And the other nice thing for that is that you can also include that in a subdirectory. And if this subdirectory is something that you're sharing in a project with other people, you are already configuring the, say, quote, unquote, corporate look and feel for your documents in that project for everyone and no one else has to care about how this document has to be configured. One of the things that I really like in this approach is that it is a grow-as-you-go. So, for example, you can start with something like that, which is I have my fonts, my basic fonts for main, which is the serif font, for sans, which is the sans serif font, for maths, and for the mono, with some features like to make them scale. This is something that is provided by you through the fontspec package, and you're happy with it, and you work with it, and in a given moment, you go and you have your own problems or your own challenge, and you need to have, for example, emojis for one of the fonts, and what you do is, in this case, you just add the emojis as a fallback font in the font that where you want to replace this. This is what I'm doing right now for this presentation, and you will see... You can always, as I've said, you can always have your dir-locals, and you can copy that into a working directory which needs special adaptations or has special needs, and from there, you have that directory with your modified or customized dir-locals.el file.
[00:11:59.080] When fontspec is not enough
So, fontspec is normally enough, but sometimes, you can't control all the fonts with fontspec only, and there you have a polyglot here and babel coming to your help. This may also be the case that you are working in an intended language, I don't know which, but an intended language, and you found, and you wanted to see how that was configured, and you found the latest example that used Babel or Polyglossia. The exporter provides you variables to configure both fontspec, Polyglossia and Babel. So just as an example of how I picture this is, uh, you find it in the Internet, something like that, uh, something like this, because you have your document and you need Thai. So, and I found an example in the internet that tells me that I'm going to be using Babel. Main is going to be English. And I'm also going to have Thai. And then they tell me that, for English, I'm going to be using Noto Serif for the main, for the main of the serif font, Noto Sans for the sans font, and then when I'm writing things in Thai, I'm going to be using Noto Serif Thai and Noto Sans Thai. That's what I see in the Internet. So what you can always do, what you would do in this case, is I'm going to get and map the font configurations from the latest into this variable. Things that you have to take into account here is, for example, the language. The language here is Thai. You have the language that you're intending this font for is Thai. So this appears here. In case you don't have any language, like in the first two lines, you just say that the language is nil, which is the language for the default language. The other thing is in my example, in this example that I found in the Internet, I have my properties for the fonts in this part in LaTeX, and I put them as properties here. That's the whole idea behind the feature branch. The babelprovide part is generated or is also integrated from the Org header, mainly from the language line. We have a variable in case you need to tweak it, but normally the defaults provided by Org are good enough.
[00:15:21.080] Rationale behind my take at LaTeX font management
So what is the rationale behind my take at LaTeX font management? That's something that might be something very personal. When am I using fontspec? I'm using fontspec when I'm with Lua- or xelatex, and I want fonts that are different from those specified in the LaTeX class. That's point number one. I will also go for fontspec when I need to support scripts, but I'm missing in the fonts I use, and I can use fallback fonts for that. I have two. The only limitation I have here is the following: all languages must be left to right. And if you don't say anything at all, the LaTeX backend assumes that you want the dates, standard names for the abstract and so on in American English, if you're using them. In many cases, you're not using any sort of abstract, table of contents, and so on, and you don't need that. The important thing is maybe date management. If you need dates, headings or anything in any other language or locale, then yes, then you need to use Babel or Polyglossia. Choice, Depends. Can use polyglossia here, or you can use Babel, whatever you want. Also, in some cases, it will depend if you've been researching a bit of how this is done with pure LaTeX, it will be also depending on, uh, on the examples that you get. So, what can you, when you are using Babel or Polyglossia here, what do you have? You have your dates, your headings, and so on. You might need to control the text in the sense that what passage is written in what language. For example, for things like hyphenation and some ways of writing the hyphens in a and direct speech and things like that. And the other place where you need other Babel or Polyglossia here, and you will see that, because all examples that you can get for later, in this case, is when you have a language that uses right to left alignment like Arabic, Hebrew and others. So one note of, I would say, care is you always use the, if you use Unicode fonts that includes the scripts as you need, you will have done, that will be a great leap for you because that simplifies the configuration a lot.
[00:18:34.480] Demonstrations
Now, a couple of demos. I don't know if you've noticed first demo is that I'm using fonts that are not the official fonts in this Beamer template, which is by the way Boadilla. This would be the first thing. So I've been using other fonts, and they are, at least from what I get in class, they are more readable than the official... than the default fonts in Polyglossia, that you get in Babel for the Boadilla theme. Another thing is what I've told you, I have my own things like emojis. Now, if you allow me for a second, I'm going to switch to the Emacs which is running behind the scenes to show you what. Okay, fine. So, this is the presentation. that I have here, and as you see, I'm using Lua LaTeX and just fontspec, given I don't know why I would need this, this is an English presentation, but just to show you what you can do, if I go back here, and I go to the beginning of the presentation, and now what... Okay, this is the presentation, right? So what I'm going to do is, I'm going to go back and I'm going to show the full screen. And in this full screen, you see the presentation on one side and you see Emacs on the other side. Oh, still nothing. Yeah, we're not seeing your screen at the moment, sorry. Oh, thank you. Thank you for that. Now it's starting to come. Okay. Yay! Fine. So this presentation, I've done it with Lua LaTeX, and what I add here is fontspec and English language. Just to show you, but with the same configuration, with the same fontspec configuration, but adding Polyglossia. I just have enough with adding Polyglossia with the Spanish language to get my dates correctly, and this is something... I'm going to see the date in English, and if I now go and recompile it, in a couple of seconds, you will see that the date is in Spanish. We are using the same... Which I can show, by the way. I see just by adding polyglossia here, I can get my dates in Spanish. What... I have included the dir-locals in these lines, but just to discuss it a bit more. I have it for all the presentations. I think it was here. No. For the demo, for the presentations I use for Emacs conferences, I have it, and it's something like this. Actually, you don't need a fallback for the main font here because the presentations are done with the sans font, so the only thing that I would really need would be something like this. This can be commented, and the same happens here with the mono. This can be also commented.
[00:22:57.475] Demo: Emoji
The only thing where I would really need a fallback font is here, and what this is telling me is that you have a fallback for the emoji, for the emoji script, and you need to use the Apple Color Emoji font with a modifier, which in this case is that you need to have the Harfbuzz renderer. That's the only thing that you really need. Where do I get all these things from? All these things I get from the different parts and from different scripts in the Internet.
[00:23:33.180] Demo: Letter
I also have a couple of other things to show. For example, first of all, I do not need this. This is a letter that I've been writing this morning and I'm not using the feature branches at all, because I just needed a sans font, and it's going to be a letter that I'm writing in with the sans font, and the only thing I need was Spanish polyglossia for the date. Anyhow, how did... What was my first thing that I did with the back end? Back in I think it was April, we had a... this comes from the mailing list, we had someone who had this problem right, and he wanted to add emojis, and he had problems with the verbatim font, and that's how everything got started. If you now go and I get my LaTeX for that running. Well, I actually, all my LaTeX is supported for that. And this was what I showed in one of the Emacs, Org Mode meetups. And there you see that we have the emojis. We had the fonts for the different things. We had maps. And you could even go and add scripts and little passages and different scripts. And this was done with the same principles that I want. I have my main font. I have the emojis. and I want, I have my son's phone and I have the emojis, the Han for Japanese and the Kana for Japanese, so that these characters here, both in the sons and in the serif passages are included correctly in the PDF.
[00:25:44.400] Demo: Side by side
And a third thing of what you can do... I've also shown this, so this is more for people who have not seen it. This is a side-by-side passage of... well, actually, the beginning of the analysis by Xenophon both in in Greek and in German, with some comments. And if I go... This is done with Polyglossia. If I go once again and produce the PDF for this... Just a second... Come on. There you are. You get this. And there you see different fonts. Which fonts am I using for this? I'm using for the main font for me is FreeSerif. This listing is produced with DejaVu Sans Mono. And using Polyglossia here, I'm able to go and define the Greek polyton for the variant, for the serif variant with the Noto Serif font, just to differentiate it from the German text. And nice thing is that both in the German text you see for example here, and with the Greek text, everything is scaled to match the lower case of the main font, which is FreeSerif. So that everything looks extremely uniform and nice to read. So that's what you want to do. That's what you can do with this. Just a couple of final words on this.
[00:28:12.600] Thanks
I want to thank once again Juan Manuel Macias and Jing Huang for what they have shared. And I also want to thank everybody for productive contributions to the discussion. I'm saying this because I think I need a longer rest and I'm going to be leaving the feature font untouched for a couple of months so that people can take... the feature branch untouched for a couple of months to see if people want to use it, and how they want to use it, and then maybe in the future, we can discuss if we want to integrate it or not, or if people need it and all that. Now questions, comments?
[00:29:47.120] Q: What about video (mp4) support for ox-latex?
Someone is asking what about how is about video mainly MP4 support on ox-latex. "I started the presentations with many videos. This is something that really pushed me back using ox-latex." What I would say to this is, I mean this goes beyond what we're discussing here with fonts. I would advise you to go and get the same or have the same thing that I did, which was, first of all, try to write it in LaTeX, and then, once you have the minimal working examples, you can get the LaTeX parts integrated into your own presentation. That's what I've been doing. By the way, I still do it, for example, not in this, but for my lectures, I have a lot of... I'm using a lot of ticks to do graphs and animated graphs. And that's #+begin_export latex #+end_export LaTeX. That's what I'm doing. Not every viewer will play them. so I think there is something called pdfpc that can, this provides a LaTeX package where you can include videos, and then they can be played through that specific program. And JavaScript embedding, that can only be done through Acrobat Reader, which is like also finicky. Sure, yes. But I mean it's always a thing of taking it and trying to see what you can do and what the specifics are. Maybe this can be done with Acrobat and with a couple of extra packages and who knows. And you can always keep it as as LaTeX as fragments inside Org, I think. Any other questions?

Questions or comments? Please e-mail paaguti@gmail.com

Back to the talks Previous by track: Reading and writing emails in GNU Emacs with Gnus Next by track: Basic Calc functionality for engineering or electronics Track: General