Writing academic papers in Org-Roam

Vincent Conus (he/him) - Pronunciation: vɪnsᵊnt koʊnᵊs, IRC: sunoc, Mastodon: @sunoc@social.linux.pizza, vincent.conus@pm.me

The following image shows where the talk is in the schedule for Sat 2024-12-07. Solid lines show talks with Q&A via BigBlueButton. Dashed lines show talks with Q&A via IRC or Etherpad.

Format: 11-min talk ; Q&A: BigBlueButton conference room https://media.emacsconf.org/2024/current/bbb-papers.html Etherpad: https://pad.emacsconf.org/2024-papers
Etherpad: https://pad.emacsconf.org/2024-papers
Discuss on IRC: #emacsconf-gen
Status: Q&A open for participation

00:00.000 Introduction
00:20.130 What?
01:21.377 Why?
02:16.215 Challenges
03:35.320 Basic Org to PDF
04:08.061 How to LaTeX properly, though?
04:32.304 LaTeX-specific headers
04:54.625 Using a formatting class file
05:31.395 Using a different LaTeX command
06:13.138 References links for bibliography
07:09.720 Examples
07:41.240 Tags

Description

Org-mode and more so org-roam are making for a fantastic note-taking system inside Emacs. Combining the note-taking of org-mode, the capability to export a note to LaTeX and PDF directly, the spectacular org-roam-bibtex package and the flexibility of the elisp configuration of Emacs, it become possible to use a org-roam note as the main document for write academic papers, even when exotic templates are provided.

In this presentation, I want to talk about the way I am using org-roam to write LaTeX documents, the benefits of it but also the various pitfalls and difficulties encountered in this journey.

The key benefits being:

• The integration with other org-roam notes.
• Bibliography integration and links directly to PDF.
• Org-mode literate programming capabilities.
• Direct export to PDF.

The main challenges are:

• Dealing with strangely formatted LaTeX templates.
• Related, having to use other LaTeX compilers.
• These two points can make citation of references, in particular, challenging.

About the speaker:

A PhD student in robotics at Nanzan University, Japan. I have been using Linux for around 10 years at that point, eventually moving many of my work and personal stuff to Emacs over the years, including academic writing.

See also:

CategoryOrgMode CategoryRoam

Transcript

[00:00:00.000] Introduction

Okay. Hi, everyone. My name is Vincent. I'm a PhD student in Nanzan University, Japan. Today I'm going to present to you how I'm using Org notes and Org Roam to write academic papers. The slides I'm going to present here are available in the Git repository, so you can check them later if you want to.

[00:00:20.130] What?

Firstly what are we talking about here? So in general, it's possible, if you have any Org nodes, to export them as LaTeX. Given some extra configuration, it's possible, basically, to reproduce any LaTeX setup that you would use to create documents with an Org file. In my case, I'm using that system to take some notes that I have in my org-roam system and to export that into finished academic papers that you can submit eventually to a conference and so on. Actually, before I submit that proposal, after I submit that proposal, I just noticed that Mike Hamrick in last year's EmacsConf made a very extensive presentation about org export. But in here, I just want to showcase my usage of org-roam and to present what are the configuration I'm using to be able to achieve that. Why do that?

[00:01:21.377] Why?

In general, like I said, I'm using that as part of my writing system, so in having org-roam notes that can be exported as a document make for a great workflow in my opinion. It makes Org even more versatile, so if you use that for maybe writing code in the literate programming, now you're going to be also able to export that into any format you want. The Org notes are very clean. In my opinion, it looks better to work in Org rather than editing LaTeX code directly. The centralized bibliography system is also great because it allows to have just a few notes that you can reference everywhere and have links to them. Of course everything is happening inside of Emacs so you have access to all the tools you are used to like Magit or Projectile and whatnot.

[00:02:16.215] Challenges

However, to quote one of the funniest recent video about Emacs: "[With LaTeX,] I used to spend hours trying to get the image on the right page. Now I use Org Mode LaTeX and just accept it's impossible." Like all the jokes in that video, it lands in very well because there is some truth to that in that with that system you are not getting rid of the complexity of LaTeX, so if you have problems, you're going to have to deal with the very long logs. It's a layer on top of LaTeX, so if you need to debug your configuration, if you want to adjust something specific, you would need to be proficient in LaTeX and also in being very at ease with your Emacs configuration. The way to use the Org export is less documented than using LaTeX so if you want to implement something, probably it's going to be described in pure LaTeX, and then you're going to need to adjust that to make it work inside your Org files. I explained before that the bibliography system is great, although it's very picky on the way it works, especially to be exported. Depending on the template you are using, you might run into issues with some packages that are in conflict, so there is that to be taken in mind.

[00:03:35.320] Basic Org to PDF

In general, if you have a Org note, you can simply export it with a C-c C-e and l o with the menu that appears. I can show that briefly: C-e, then you have the menu. You can select l and o to export. That works very well. In general, with that, you are able to deal with everything that you have in your normal Org notes. If you have images, tables, links, it's going to be exported in a way that looks decent. That's what we are starting with.

[00:04:08.061] How to LaTeX properly, though?

However, if you want to make a publication, if you have a template that you receive from a conference or whatnot, you want to be able to adapt your Org notes to be able to export it exactly the way you want. I'm going to present the four points that I'm showing here that are, for me, the elements that you need to be careful with when you try to work with templates and exporting to LaTeX.

[00:04:32.304] LaTeX-specific headers

Firstly, you have headers. So basically, this allows to add LaTeX elements that are going to be at the top of the file. You're going to have the title. You're going to have your extra packages here. You're going to have your class. I'm going to present that later. That's the part that you're going to adjust to make it look like the .tex template that you receive.

[00:04:54.625] Using a formatting class file

Then you have the formatting class file. That's a .cls file that you would receive as a part of the template. This one is used instead of the typical doc class like article. The way I'm using them is to add an entry, like add an element to the list or get a class in my Emacs init. This way I can use the CLS file directly and also give the parameters that I want. In that case, I'm going to have a apris.cls next to my Org note, and it's going to be able to to use it.

[00:05:31.395] Using a different LaTeX command

A third element is, in some cases, you might want to use a different LaTeX compiler to build your project, to build your notes. That can be done per file, per note, in my opinion, that's the most flexible way, by editing, by adding this line as the very first line of your file and thus changing the LaTeX PDF process variable. And in there, you can put multiple commands in a row. For example you can have the shell escape to have the minted note block, the BibTeX element, so that works very well. When you add that, you need to reload your file, though. Something to keep in mind.

[00:06:13.138] References links for bibliography

Lastly, you have the bibliography. When you have a reference, when you want to put a reference, you can use the org-roam-bibtex package that needs to be installed. Then you have some configuration to to be set so you have the bibtex compilation bibliography, where you explain where is your your reference file, your bib file. You can also give a path for where to search for PDFs. If you have matching names with your BibTeX entries and some PDF files in there, they're going to be linked. I'm going to show that later. So that's something that's going to be part of your init configuration as part of the org-roam-bibtex package configuration. Then in the node you are exporting, you want to add a section called reference. Here you can set a style for the bibliography. Again you put which of the reference file you want to use.

[00:07:09.720] Examples

With all of that, I'm going to show some examples. Here I have an Org note that I used as the file to be exported into a publication. You can see up front, I set all my headers package. I have some extra package I put. I have the class that is something that is next to it. You can see in the files, I have the apris.cls just here.

[00:07:41.240] Tags

Also, with all of that, you can also add tags. I didn't explain that, but you can also ignore some sections. That's quite convenient as well. Here we have some section, and if you want to add a bibliography, you're going to do c l cite:, you can put some cite entry, put any file in there, no description, and you're going to put some link like that. It's very convenient because, firstly, it's going to be exported as a reference like I'm going to show later, but also it gives you access to it directly from the note. If I click the thing here, I have some menu, I can open the bibliography page. I can also open the PDF that was linked to it. If I do that, here is the file that pops up that was linked to the bibliography. That's great. Otherwise, within that document, you're going to have other things you can have. Figures with parameters set on top, footnotes as well if that's something that you need. For example, here it's a section that's not exported, but you can have your normal footnotes. We can go back and forth. If they are in the exported section, they're going to be managed. So with that, you can export the notes. You're going to C-c C-e so you have that menu for exporting Org files. You do l for LaTeX and then o for running directly as PDF and opening it. It takes a little while to build. Here we are. The templates have been used, so there is a two-column situation happening, we have a specific header format and figures and the citation that we put. It's happening, it's shown here, and it's also going to be visible at the end in the reference section. Like I said, a fully ready, finished paper can be produced this way. That's all that I had for today. Thank you very much for your attention. I am available for questions on IRC or in the video chat. Thank you.

Captioner: sachac

Questions or comments? Please e-mail vincent.conus@pm.me