path: root/2023/info/doc-after.md

<!-- Automatically generated by emacsconf-publish-after-page -->


<a name="doc-mainVideo-transcript"></a>
# Transcript


Introduction

[[!template new="1" text="""Hello, everyone.""" start="00:00:00.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This talk is on literate documentation""" start="00:00:04.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with Emacs and org-mode.""" start="00:00:07.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I'm going to take just a moment here""" start="00:00:10.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to unpack what I just said.""" start="00:00:12.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Emacs, as most of us probably already know,""" start="00:00:14.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is a powerful text editor and list programming environment""" start="00:00:17.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""from the 1970s.""" start="00:00:21.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Chances are, if you're attending this talk,""" start="00:00:23.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you already know a bit about Emacs.""" start="00:00:25.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""org-mode is an Emacs major mode and authoring tool""" start="00:00:28.820" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that helps you write documents in a plain text markup""" start="00:00:32.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""language called Org.""" start="00:00:36.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""These Org documents can be exported""" start="00:00:37.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to a number of different document formats,""" start="00:00:40.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""like HTML, PDF, ODT, Markdown, and more.""" start="00:00:42.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""org-mode has a lot of features.""" start="00:00:48.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It can be an outliner, a to-do list manager,""" start="00:00:51.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""an agenda, organizer, and much more.""" start="00:00:54.240" video="mainVideo-doc" id="subtitle"]]

Org Babel and literate programming

[[!template new="1" text="""Today, we're going to be demonstrating""" start="00:00:57.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""what I consider to be org-mode's killer feature called""" start="00:00:59.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Org Babel.""" start="00:01:03.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Babel allows you to take human language prose,""" start="00:01:04.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""computer language source code blocks, and their outputs""" start="00:01:07.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and weave them together seamlessly""" start="00:01:11.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to form a cohesive document.""" start="00:01:13.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It is seriously cool.""" start="00:01:16.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Literate documentation is a play on the term""" start="00:01:19.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""literate programming, popularized by Donald Knuth""" start="00:01:21.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in the early 1980s.""" start="00:01:25.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Knuth's literate programming idea""" start="00:01:27.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""was that computer programs could be""" start="00:01:29.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""expressed in a natural language and be""" start="00:01:31.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""human-readable documents rather than written exclusively""" start="00:01:34.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""for machines to read.""" start="00:01:38.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""In a traditional program, you might""" start="00:01:40.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""have a bunch of machine-readable source code""" start="00:01:43.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and a handful of human-readable comments,""" start="00:01:45.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which attempt to describe what the program is doing.""" start="00:01:48.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Literate programming flips this on its head.""" start="00:01:51.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""A literate program is a document that""" start="00:01:54.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""describes how the program works with machine-readable source""" start="00:01:56.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""code blocks inside of it.""" start="00:02:01.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""These source code blocks are later""" start="00:02:02.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""tangled out of the document and submitted to the machine""" start="00:02:04.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""either to be compiled or interpreted and ultimately run.""" start="00:02:08.440" video="mainVideo-doc" id="subtitle"]]

This presentation

[[!template new="1" text="""Throughout this presentation, you'll""" start="00:02:14.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""see my browser window here on the left side of the screen.""" start="00:02:15.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And on the right side, I've got a terminal session""" start="00:02:19.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""running tmux.""" start="00:02:22.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This allows us to have a virtual terminal window connected""" start="00:02:23.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to two separate Linux machines, one running Ubuntu Server 2204""" start="00:02:28.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and another running Fedora Server 38.""" start="00:02:35.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I've specifically chosen these two distributions for my demo""" start="00:02:39.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because they are representative of the two dominant flavors""" start="00:02:43.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of GNU Linux, Debian and RedHat.""" start="00:02:46.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""In both cases, these are bare-bones server additions""" start="00:02:49.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with the stock packages installed.""" start="00:02:53.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I've manually installed a few packages like Git, emacs-noex""" start="00:02:55.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to get the terminal version of emacs, and tmux.""" start="00:03:00.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""But otherwise, these Linux installs""" start="00:03:04.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""are what you'd get right out of the box.""" start="00:03:06.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""For this demo, I've created a literate org-mode document""" start="00:03:08.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that describes how to build GNU Emacs from its source code""" start="00:03:12.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on both Debian and RedHat-based systems.""" start="00:03:16.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""While both operating systems are very similar,""" start="00:03:19.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""they differ substantially on which packages""" start="00:03:22.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""are installed out of the box, how optional packages are""" start="00:03:25.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""named, searched, and installed, and of course,""" start="00:03:29.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the distributions have different names,""" start="00:03:32.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""like Ubuntu or Fedora.""" start="00:03:34.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I chose building Emacs from source""" start="00:03:36.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""as a topic for this demonstration""" start="00:03:39.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because while the process is largely""" start="00:03:41.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the same on both RedHat and Debian,""" start="00:03:43.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""there are a lot of minor little differences""" start="00:03:46.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that need to be accounted for, which really prohibits you""" start="00:03:49.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""from hard coding names of packages and package management""" start="00:03:52.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""tools and distributions into your document.""" start="00:03:57.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I suppose you could create two versions of the same document,""" start="00:04:01.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""one specifically for RedHat and one specifically for Debian,""" start="00:04:05.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but that would be really tedious to maintain.""" start="00:04:09.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Like if, for example, you updated some prose""" start="00:04:13.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in one document, you'd have to remember""" start="00:04:16.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to do it in the other one too.""" start="00:04:18.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And if you weren't careful, the two documents""" start="00:04:20.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""could drift out of sync.""" start="00:04:22.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""In this demo, I'll show you techniques""" start="00:04:25.260" video="mainVideo-doc" id="subtitle"]]
[[!template text="""for creating dynamic, literate documents that""" start="00:04:27.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""can change based on parameters and constants embedded""" start="00:04:30.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""into the non-exported regions of the document.""" start="00:04:34.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I'll show how with a single org-mode source document,""" start="00:04:38.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you can press a couple of keys to configure""" start="00:04:41.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it to export a RedHat-specific version of my building""" start="00:04:44.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Emacs from source essay or a Debian-specific version.""" start="00:04:48.720" video="mainVideo-doc" id="subtitle"]]

Getting started

[[!template new="1" text="""All right, let's get started.""" start="00:04:53.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll begin by firing up a new terminal Emacs session""" start="00:04:55.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on my Ubuntu machine.""" start="00:04:58.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now, I installed Emacs on this machine using apt-get.""" start="00:05:00.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And doing that, you get version 27.1,""" start="00:05:04.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is, hey, only two major versions""" start="00:05:07.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""behind the current version of Emacs.""" start="00:05:10.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This is another reason why I thought""" start="00:05:13.011" video="mainVideo-doc" id="subtitle"]]
[[!template text="""writing a guide on how to build Emacs from source code""" start="00:05:15.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""might be a good idea.""" start="00:05:18.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""You can get a much newer version of Emacs on Ubuntu""" start="00:05:19.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""if you install it via Snap, but, uh, Snaps.""" start="00:05:22.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Don't get me started.""" start="00:05:25.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now, I wanted to use a completely vanilla""" start="00:05:28.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""terminal mode install of Emacs for this demonstration""" start="00:05:30.922" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because my personal Emacs config has a ton of packages""" start="00:05:34.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""installed and is heavily modified.""" start="00:05:38.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I want folks to be able to follow along""" start="00:05:41.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with a bog-standard, out-of-the-box Emacs config.""" start="00:05:43.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The Emacs config on this Ubuntu machine""" start="00:05:47.580" video="mainVideo-doc" id="subtitle"]]
[[!template text="""has just two settings.""" start="00:05:49.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I require org-tempo because my fingers are hardwired""" start="00:05:51.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to use some of the handy shortcuts that it provides.""" start="00:05:55.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And I also turn off the menu bar""" start="00:05:58.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because I just can't stand to look at it.""" start="00:06:00.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's begin by opening a file called buildemacs.org,""" start="00:06:03.140" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which will be the source code""" start="00:06:07.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""for our literate org-mode document.""" start="00:06:08.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now, in preparation for this talk,""" start="00:06:11.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I've already written this document,""" start="00:06:12.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we'll take a look at the finished product""" start="00:06:14.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""here in a bit, but let's first take a look""" start="00:06:17.980" video="mainVideo-doc" id="subtitle"]]
[[!template text="""at how we might approach this task.""" start="00:06:19.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll start at the top of the document""" start="00:06:22.409" video="mainVideo-doc" id="subtitle"]]
[[!template text="""by filling out some export keywords.""" start="00:06:24.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""These keywords are something that every backend exporter,""" start="00:06:27.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""be it LaTeX or plain text or ODT or whatever, understands,""" start="00:06:30.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and they're essentially document metadata.""" start="00:06:35.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""As you can see, I'm typing `#+`""" start="00:06:38.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""followed by a couple characters""" start="00:06:42.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then `M-TAB` to auto-complete.""" start="00:06:43.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If you hit #+ by itself and then M-TAB,""" start="00:06:45.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you can see all the possible completions.""" start="00:06:50.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And as you can see, there's a lot.""" start="00:06:53.120" video="mainVideo-doc" id="subtitle"]]

README

[[!template new="1" text="""The next thing we're gonna do is make a README section""" start="00:06:55.780" video="mainVideo-doc" id="subtitle"]]
[[!template text="""at the top of this document.""" start="00:06:58.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This section is intended for folks""" start="00:06:59.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""who are looking at the org-mode document,""" start="00:07:02.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""trying to figure out what it's for.""" start="00:07:04.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We don't want to actually export the section heading,""" start="00:07:06.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""so we're gonna tag it with the :noexport: tag.""" start="00:07:09.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then here, we just write something quick""" start="00:07:13.860" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to let folks know that this document""" start="00:07:15.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""can potentially execute code""" start="00:07:17.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and just a little something about what the document is for.""" start="00:07:19.800" video="mainVideo-doc" id="subtitle"]]

Writing a code block

[[!template new="1" text="""Okay, so now that we've written some text,""" start="00:07:23.500" video="mainVideo-doc" id="subtitle"]]
[[!template text="""let's try our hand at writing a code block.""" start="00:07:26.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I'm getting pretty sick of looking at""" start="00:07:29.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the default Emacs theme.""" start="00:07:31.289" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All that blue and purple in the document""" start="00:07:32.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""makes it look bruised.""" start="00:07:35.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's make an Emacs Lisp code block""" start="00:07:37.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that switches the theme""" start="00:07:40.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to one of my favorite built-in themes, Leuven.""" start="00:07:41.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Leuven was created by my man, Fabrice Niessen,""" start="00:07:44.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""who I personally have learned a ton of org-mode stuff about""" start="00:07:48.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""just by studying his work.""" start="00:07:52.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now, if we cruise back up to the code block,""" start="00:07:54.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we should be able to hit `C-c C-c`,""" start="00:07:56.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and have it execute.""" start="00:07:58.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And there you have it, a high-contrast color theme""" start="00:08:00.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that was designed to look great in org-mode.""" start="00:08:03.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So that's great and all,""" start="00:08:06.980" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but there are a couple of things I don't like.""" start="00:08:08.080" video="mainVideo-doc" id="subtitle"]]

:results none

[[!template new="1" text="""First of all, we don't need to see a #+RESULTS block here,""" start="00:08:10.460" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and that's because we're not really interested""" start="00:08:13.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in what the Emacs Lisp function `load-theme` returns.""" start="00:08:15.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I mean, it's great it returned t and all to indicate success,""" start="00:08:18.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we just don't need to see it.""" start="00:08:22.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We can slap a `:results none` header arg""" start="00:08:23.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on the code block to keep things nice and clean.""" start="00:08:26.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""There are a lot of different header args,""" start="00:08:30.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and I often confuse and misremember them.""" start="00:08:32.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So I'll always refer back to the org-mode manual""" start="00:08:35.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""when working with them.""" start="00:08:38.920" video="mainVideo-doc" id="subtitle"]]

Confirmation

[[!template new="1" text="""The second thing I don't like is that""" start="00:08:40.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""when we hit C-c C-c to execute the block,""" start="00:08:42.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Emacs prompted us if we really wanted to run the block.""" start="00:08:46.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Emacs Lisp is Emacs' mother tongue,""" start="00:08:49.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and I don't wanna be hassled when speaking""" start="00:08:52.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""my native language.""" start="00:08:53.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""There's a variable that controls this""" start="00:08:55.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""called `org-confirm-babel-evaluate`.""" start="00:08:57.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And this can be either set to t or nil""" start="00:09:00.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to either always confirm or never confirm.""" start="00:09:03.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If however, you provided a lambda, an anonymous function,""" start="00:09:06.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Org will call your function with the name of the language""" start="00:09:10.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and the source block that it's about to run.""" start="00:09:14.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And your function can make the decision""" start="00:09:16.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""about if Emacs should ask you for confirmation or not.""" start="00:09:19.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""What I'm doing here is setting `org-confirm-babel-evaluate`""" start="00:09:24.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""as a &quot;file local variable&quot;.""" start="00:09:27.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This means whenever the file is opened by Emacs,""" start="00:09:30.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it'll set this variable to be a lambda that returns nil,""" start="00:09:33.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""meaning don't confirm, on Elisp code blocks.""" start="00:09:38.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""As you can see, the variable is currently set""" start="00:09:42.860" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to its default value of t, meaning always confirm.""" start="00:09:45.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now if we save the buffer, exit Emacs,""" start="00:09:50.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and pop back in again,""" start="00:09:53.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""`org-confirm-babel-evaluate` should be set how we like it.""" start="00:09:55.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We were however prompted for confirmation""" start="00:10:00.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on setting the file-local variable,""" start="00:10:02.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which controls if we're prompted""" start="00:10:04.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""for Elisp source code block evaluation.""" start="00:10:06.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I feel like there's a Yo Dawg joke here somewhere.""" start="00:10:09.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""When we were prompted, we hit the exclamation mark,""" start="00:10:12.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which automatically marks this variable as being safe.""" start="00:10:15.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So you won't be bothered the next time you open this file.""" start="00:10:18.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This variable is called `safe-local-variable-values`""" start="00:10:21.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and if we pop over to our .emacs file,""" start="00:10:26.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you can see that Emacs' customize tooling""" start="00:10:29.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""helpfully updated this variable in our config file for us.""" start="00:10:32.520" video="mainVideo-doc" id="subtitle"]]

Running blocks automatically

[[!template new="1" text="""Now that's great and all,""" start="00:10:36.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but I really don't like having to hit `C-c C-c`""" start="00:10:38.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on that source block every time I open this document""" start="00:10:42.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""just to bring up the Leuven theme.""" start="00:10:45.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's have this source block run automatically""" start="00:10:47.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""every time the document is opened.""" start="00:10:50.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now I know what you're thinking.""" start="00:10:53.180" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Shouldn't you just put all of this configuration stuff""" start="00:10:55.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in your .emacs file and keep it out of the document?""" start="00:10:57.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Well, that's what I've done with my personal Emacs config,""" start="00:11:01.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but we want this document to be able to be used by folks""" start="00:11:04.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with a completely vanilla Emacs setup,""" start="00:11:08.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or even a completely tricked out Emacs setup,""" start="00:11:11.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""so we can't assume anything.""" start="00:11:13.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The idea is if the Emacs user who opens the document""" start="00:11:16.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""agrees to setting all of the variables""" start="00:11:19.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and running all of the code within,""" start="00:11:22.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""they'll be able to export the document""" start="00:11:24.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""as well as run all of the code blocks inside of it""" start="00:11:26.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""just as we intended.""" start="00:11:28.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And the differences in base Emacs configuration""" start="00:11:30.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""will be completely minimized.""" start="00:11:33.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now it's worth pointing out that the file-local variables""" start="00:11:35.980" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we're setting here are local, in this case, buffer-local.""" start="00:11:39.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The configuration we use in this document""" start="00:11:43.024" video="mainVideo-doc" id="subtitle"]]
[[!template text="""won't override someone's carefully constructed""" start="00:11:45.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""org-mode setup.""" start="00:11:48.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The first thing we're gonna wanna do""" start="00:11:49.500" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in order to make this block execute""" start="00:11:51.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""when the document is loaded is to give it a name.""" start="00:11:53.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It's always a good idea to give every source block""" start="00:11:55.989" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you create in your document a unique name,""" start="00:11:58.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""even if you don't refer to it elsewhere.""" start="00:12:01.338" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I do this because when I'm debugging my documents,""" start="00:12:03.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Emacs will prompt me about running a block.""" start="00:12:07.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If the block has a name, Emacs mentions it,""" start="00:12:10.020" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and I know there's a problem with the result caching""" start="00:12:12.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or something with the &quot;foo&quot; block.""" start="00:12:15.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""But if the block doesn't have a name,""" start="00:12:17.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it can be really hard to figure out""" start="00:12:20.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which block Emacs is complaining about.""" start="00:12:22.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So I always name my blocks.""" start="00:12:24.580" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now we're gonna add another file local variable,""" start="00:12:27.460" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but this one is special.""" start="00:12:30.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If your &quot;variable&quot;""" start="00:12:32.116" video="mainVideo-doc" id="subtitle"]]
[[!template text="""just happens to be named &quot;eval&quot;,""" start="00:12:34.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it means that Emacs should evaluate""" start="00:12:36.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the Lisp expression that follows.""" start="00:12:38.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Here we'll use the progn function""" start="00:12:40.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to sequentially run two elisp functions""" start="00:12:43.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and return the value of the last one executed.""" start="00:12:46.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The first function is `org-babel-goto-named-source-block`,""" start="00:12:48.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which jumps us to the startup block.""" start="00:12:53.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The second one is `org-babel-execute-src-block`,""" start="00:12:55.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which executes the current source block.""" start="00:12:59.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""That should get the job done.""" start="00:13:02.093" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now all we have to do is save the document,""" start="00:13:03.631" video="mainVideo-doc" id="subtitle"]]
[[!template text="""exit Emacs, jump back in,""" start="00:13:05.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and once we've confirmed that we're willing""" start="00:13:08.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to run the new &quot;eval&quot; line in our file local variables,""" start="00:13:10.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we're good to go.""" start="00:13:14.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now if we want to add new configuration stuff""" start="00:13:15.860" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to the document, we can just add it to the startup block""" start="00:13:18.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and not have to muck about with confirmations""" start="00:13:21.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or adding new file-local variables or whatever.""" start="00:13:24.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And just like before, we'll let Emacs' customize system""" start="00:13:28.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""save this decision to our .emacs file.""" start="00:13:31.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now that all that business with confirmations,""" start="00:13:34.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""file-local variables, and the startup block""" start="00:13:37.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""are out of the way,""" start="00:13:40.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can get on with writing our introduction.""" start="00:13:41.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll create a new top level headline called introduction""" start="00:13:44.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and explain to the reader of the exported document""" start="00:13:47.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""what this is all about.""" start="00:13:51.440" video="mainVideo-doc" id="subtitle"]]

Export options

[[!template new="1" text="""Now as you can see, we've actually hard-coded""" start="00:13:53.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the name of the Linux distro in our prose.""" start="00:13:55.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I promised you a single document that could be""" start="00:13:58.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""for either RedHat or Debian distros,""" start="00:14:00.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""so we can't have this.""" start="00:14:03.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Astute members in the audience have probably been uneasy""" start="00:14:05.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""ever since I hard coded the name &quot;Debian&quot;""" start="00:14:08.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in the README section above.""" start="00:14:11.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""One way of solving this problem is by using exclude tags.""" start="00:14:13.860" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's add the `#+EXCLUDE_TAGS` export keyword to our document.""" start="00:14:17.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This keyword tells the exporter,""" start="00:14:21.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""&quot;Hey, if you see a headline tagged with any of these tags,""" start="00:14:24.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""don't export it.&quot;""" start="00:14:27.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""By default, the tag `:noexport:` is excluded.""" start="00:14:29.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And if you'll notice, we tagged our README section""" start="00:14:33.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with that tag, so it doesn't show up""" start="00:14:36.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in the exported document.""" start="00:14:38.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll keep this tag in the list,""" start="00:14:40.340" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but we'll also add the tag `:redhat:` as a tag to exclude.""" start="00:14:42.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now it's just a matter of creating two introduction""" start="00:14:47.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""sections, one for Debian, one for RedHat.""" start="00:14:50.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And if you want the RedHat version of the document,""" start="00:14:53.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you can just modify the `#+EXCLUDE_TAGS` line""" start="00:14:56.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""at the top of the document.""" start="00:14:59.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Awesome, right?""" start="00:15:00.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Right?""" start="00:15:02.340" video="mainVideo-doc" id="subtitle"]]
[[!template text="""OK, this is not that great.""" start="00:15:03.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Well, it does work.""" start="00:15:05.545" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And you can see if we export the document,""" start="00:15:07.388" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we'll get something that only references Debian,""" start="00:15:10.082" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and the `:noexport:` and `:redhat:`""" start="00:15:12.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""tagged headlines are omitted.""" start="00:15:15.189" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This strategy would work great""" start="00:15:17.451" video="mainVideo-doc" id="subtitle"]]
[[!template text="""when the RedHat- and Debian-specific sections""" start="00:15:19.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""are substantially different, but that's not""" start="00:15:22.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the case with the introduction.""" start="00:15:24.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We definitely don't want to have to maintain""" start="00:15:26.199" video="mainVideo-doc" id="subtitle"]]
[[!template text="""two distinct introductions.""" start="00:15:28.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I also noticed that the export tags are included""" start="00:15:30.825" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in the exported document.""" start="00:15:34.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""That's a terrible default. We'll fix that,""" start="00:15:36.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we'll also ensure that my email address appears""" start="00:15:38.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""at the top of the document.""" start="00:15:42.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's also take this opportunity to get rid""" start="00:15:43.372" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of the table of contents.""" start="00:15:45.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We don't need it.""" start="00:15:47.355" video="mainVideo-doc" id="subtitle"]]
[[!template text="""These are all export option settings""" start="00:15:48.868" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and can be modified using the options keyword""" start="00:15:51.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""at the top of the doc.""" start="00:15:53.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The manual is really your friend here,""" start="00:15:55.509" video="mainVideo-doc" id="subtitle"]]
[[!template text="""as there are a ton of export options.""" start="00:15:57.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now when we export the document again,""" start="00:16:00.980" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it should look a lot better.""" start="00:16:03.120" video="mainVideo-doc" id="subtitle"]]

Substituting constants

[[!template new="1" text="""Now that we've cleaned up the look of the exported document,""" start="00:16:05.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we'll take a look at a better way""" start="00:16:09.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of solving the problem with the introduction.""" start="00:16:10.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Thinking like a programmer for a moment,""" start="00:16:13.378" video="mainVideo-doc" id="subtitle"]]
[[!template text="""what I really want here is a way of specifying a constant.""" start="00:16:15.519" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Rather than hard-coding the name &quot;Debian&quot; or &quot;RedHat&quot;""" start="00:16:19.735" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or whatever into my document,""" start="00:16:22.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I want to substitute that text with a symbolic constant,""" start="00:16:24.570" video="mainVideo-doc" id="subtitle"]]
[[!template text="""named something like &quot;distro&quot;, that can dynamically change""" start="00:16:28.235" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to &quot;Debian&quot; or &quot;RedHat&quot; or &quot;Slackware&quot; or whatever,""" start="00:16:31.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""depending on how the document is configured.""" start="00:16:36.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""In the past, I've come up with some pretty cumbersome ways""" start="00:16:38.690" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of doing this, but eventually I stumbled upon the idea""" start="00:16:41.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of using Org-mode properties""" start="00:16:44.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""as a way of storing these constants.""" start="00:16:46.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Like it says in the docs, properties are key-value pairs""" start="00:16:49.410" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that are associated with an entry""" start="00:16:53.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and they live in a collapsible properties drawer.""" start="00:16:55.170" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's do a bit of cleanup on our document""" start="00:16:58.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we'll put things into sections.""" start="00:17:00.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll also add a section for document constants.""" start="00:17:02.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And that's where we'll put the properties drawer""" start="00:17:14.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with the &quot;distro&quot; property.""" start="00:17:19.560" video="mainVideo-doc" id="subtitle"]]

Getting the properties

[[!template new="1" text="""Now the question is,""" start="00:17:25.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""how do we reference these properties in the document?""" start="00:17:27.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It turns out there's an Elisp function""" start="00:17:30.100" video="mainVideo-doc" id="subtitle"]]
[[!template text="""called `org-property-values`, which does what we want.""" start="00:17:32.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If we run it and give it the name of our property,""" start="00:17:35.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it returns a list with the string &quot;Debian&quot; in it.""" start="00:17:38.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It's worth noting that this function is named""" start="00:17:42.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""`org-property-values` with values being plural.""" start="00:17:45.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""In org-mode, there could be a property named &quot;foo&quot;""" start="00:17:49.990" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that has different values depending on which heading level""" start="00:17:52.890" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you're at in the document,""" start="00:17:55.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is why the function returns a list.""" start="00:17:57.610" video="mainVideo-doc" id="subtitle"]]
[[!template text="""For our purposes though,""" start="00:17:59.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can just pull off the first value in the list with car""" start="00:18:01.290" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we're good to go.""" start="00:18:04.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now we'll make an Emacs Lisp list function called `get_prop`""" start="00:18:05.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that does just that.""" start="00:18:10.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This function takes one argument called `prop`,""" start="00:18:11.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is the property to look up""" start="00:18:14.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we'll give it a default value of &quot;distro&quot;.""" start="00:18:15.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we can hit `C-c C-c` on the block""" start="00:18:18.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to verify that it works.""" start="00:18:20.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now we just have to make an inline call""" start="00:18:23.150" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to our `get_prop` function""" start="00:18:25.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""within the prose of the introduction section.""" start="00:18:26.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And that should get us much closer""" start="00:18:29.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to not hard coding distro names into our document.""" start="00:18:31.660" video="mainVideo-doc" id="subtitle"]]
[[!template text="""But before we do that,""" start="00:18:35.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I need to clean up something that's been bothering me.""" start="00:18:36.870" video="mainVideo-doc" id="subtitle"]]
[[!template text="""By default, Emacs' `fill-column` variable""" start="00:18:39.850" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is set to 70 characters,""" start="00:18:42.910" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which may have been appropriate for 1970,""" start="00:18:44.990" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but it's not great for 2023.""" start="00:18:47.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll just cruise up to our startup block""" start="00:18:51.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and set the variable there.""" start="00:18:53.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll hit `C-c C-c`,""" start="00:18:56.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and now our document will wrap at 100 columns,""" start="00:18:58.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which for our purposes, I think is much more reasonable.""" start="00:19:02.290" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The org-mode syntax for making an inline function call""" start="00:19:05.830" video="mainVideo-doc" id="subtitle"]]
[[!template text="""within the prose of your document is `call_`,""" start="00:19:09.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""followed by the name of the function,""" start="00:19:13.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""some optional header arguments,""" start="00:19:15.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then the function arguments.""" start="00:19:17.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now, when we export the document,""" start="00:19:19.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we see that it's replaced our previously hard coded &quot;Debian&quot;""" start="00:19:21.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with the value from the property. Huzzah!""" start="00:19:26.050" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now this is close to, but not exactly what we want.""" start="00:19:29.410" video="mainVideo-doc" id="subtitle"]]
[[!template text="""You can see that &quot;Debian&quot; is surrounded by a backtick""" start="00:19:32.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and a single quote,""" start="00:19:36.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is the plain text exporters way""" start="00:19:37.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of showing you verbatim text.""" start="00:19:40.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""In more sophisticated document backends,""" start="00:19:43.030" video="mainVideo-doc" id="subtitle"]]
[[!template text="""verbatim text is rendered in monospace.""" start="00:19:45.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We can fix that by adding a &quot;:results raw&quot; header argument""" start="00:19:49.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to the inline call.""" start="00:19:54.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now, when we export the document,""" start="00:19:56.460" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it looks like what we'd expect.""" start="00:19:58.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now this is getting better, but it's still not great.""" start="00:20:00.290" video="mainVideo-doc" id="subtitle"]]

Macros

[[!template new="1" text="""The `call_` syntax is pretty cumbersome,""" start="00:20:03.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and it's a lot to type every time we want""" start="00:20:05.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to reference a constant""" start="00:20:08.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and not have it be marked up as verbatim.""" start="00:20:09.850" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This is where org-mode macros come to our rescue.""" start="00:20:13.220" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If we head to the top of the document,""" start="00:20:17.170" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can create a couple of macros""" start="00:20:19.470" video="mainVideo-doc" id="subtitle"]]
[[!template text="""using the `#+MACRO:` export keyword.""" start="00:20:21.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll define two macros with short names.""" start="00:20:24.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""One named &quot;p&quot; for &quot;property&quot;,""" start="00:20:27.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and the other one named &quot;pr&quot; for &quot;property raw&quot;.""" start="00:20:30.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Org-mode macros are expanded when the document is exported,""" start="00:20:34.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and any positional arguments provided""" start="00:20:39.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""are referenced by their number.""" start="00:20:41.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now in the introduction,""" start="00:20:43.860" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can use the macro replacement syntax,""" start="00:20:45.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is three curly braces,""" start="00:20:47.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""followed by the macro name and any arguments,""" start="00:20:49.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then three ending curly braces.""" start="00:20:52.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""You see why I kept the macro name short.""" start="00:20:55.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""That's six curly braces in total we're typing,""" start="00:20:58.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which still takes up a fair amount of space.""" start="00:21:01.280" video="mainVideo-doc" id="subtitle"]]

Properties in practice

[[!template new="1" text="""Now let's take a look at how we might use""" start="00:21:05.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""these properties in practice.""" start="00:21:07.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Debian and RedHat distros differ""" start="00:21:09.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on how they install packages.""" start="00:21:11.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we're gonna want an &quot;install&quot; property,""" start="00:21:12.930" video="mainVideo-doc" id="subtitle"]]
[[!template text="""where in Debian we use `sudo apt-get install -qq`,""" start="00:21:16.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and on RedHat we'll use something like""" start="00:21:24.580" video="mainVideo-doc" id="subtitle"]]
[[!template text="""`sudo dnf install -y`.""" start="00:21:26.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now development packages""" start="00:21:33.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""also have a different naming convention.""" start="00:21:35.330" video="mainVideo-doc" id="subtitle"]]
[[!template text="""For example, the `ncurses` library on Debian""" start="00:21:38.050" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is called `libncurses-dev`,""" start="00:21:40.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""where on RedHat it's called `ncurses-devel`.""" start="00:21:43.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""There are likely going to be""" start="00:21:48.260" video="mainVideo-doc" id="subtitle"]]
[[!template text="""many more little differences like this""" start="00:21:49.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that we'll need to solve with properties.""" start="00:21:52.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now I already don't like where this is going.""" start="00:21:55.340" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Switching between the Debian and RedHat""" start="00:21:58.610" video="mainVideo-doc" id="subtitle"]]
[[!template text="""versions of the document is gonna mean""" start="00:22:00.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""commenting and uncommenting out""" start="00:22:03.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""a bunch of different properties,""" start="00:22:05.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is pretty janky.""" start="00:22:06.990" video="mainVideo-doc" id="subtitle"]]

Using a prefix

[[!template new="1" text="""Luckily we can solve this problem""" start="00:22:09.020" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with a little bit of Emacs Lisp.""" start="00:22:11.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll start by modifying our properties,""" start="00:22:14.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""so their property names are prefixed""" start="00:22:16.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""with either `deb_` or `rh_`""" start="00:22:19.141" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to signify which distro the property applies to.`""" start="00:22:23.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll also create a single property called &quot;prefix&quot;,""" start="00:22:27.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which will be prepended to the property name""" start="00:22:31.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""by the `get_prop` function""" start="00:22:34.590" video="mainVideo-doc" id="subtitle"]]
[[!template text="""if the requested property is not found.""" start="00:22:36.530" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This way, when we want to switch between""" start="00:22:39.510" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the Debian and RedHat versions of the document,""" start="00:22:42.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we just need to change the prefix property.""" start="00:22:45.350" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So now we'll change the Elisp code.""" start="00:22:49.030" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we'll use a let expression with two bound variables.""" start="00:22:51.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The first one is called ret,""" start="00:22:55.210" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which determines if the initial call""" start="00:22:56.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to `org-property-values` succeeds.""" start="00:22:59.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The second variable is called prefix,""" start="00:23:01.950" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is the prefix property.""" start="00:23:04.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If the first call to `org-property-values` succeeds,""" start="00:23:06.220" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we return it as normal.""" start="00:23:09.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If not, we concatenate the property value""" start="00:23:11.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that was passed into the function""" start="00:23:14.250" video="mainVideo-doc" id="subtitle"]]
[[!template text="""onto the prefix and try again.""" start="00:23:15.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now when we call the `get_prop` function with &quot;distro&quot;""" start="00:23:18.970" video="mainVideo-doc" id="subtitle"]]
[[!template text="""as the prop argument, it won't be found.""" start="00:23:23.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So the code will slap our prefix tag on the front,""" start="00:23:26.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""making it something like `rh_distro`,""" start="00:23:29.690" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and it will be found and returned.""" start="00:23:33.250" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's see that in action.""" start="00:23:35.330" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All right, now we're talking.""" start="00:23:40.000" video="mainVideo-doc" id="subtitle"]]

Switching distributions

[[!template new="1" text="""This setup is starting to look pretty good,""" start="00:23:42.010" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but there are just a few things""" start="00:23:44.420" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that I want to add before we move on.""" start="00:23:46.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""First of all, I think the document should have a subtitle,""" start="00:23:48.660" video="mainVideo-doc" id="subtitle"]]
[[!template text="""something that tells you if you're looking at the RedHat""" start="00:23:51.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or the Debian version of the document.""" start="00:23:53.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I also think it would be great""" start="00:23:56.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""if the file name of the exported document""" start="00:23:57.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""reflected the distribution as well.""" start="00:24:00.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I also want to add a quick Debian only section""" start="00:24:05.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to the document that explains how it got its name.""" start="00:24:08.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now let's see what happens when we export the document.""" start="00:24:11.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This did not work out as we wanted.""" start="00:24:17.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""As you can see, the macro we used in the subtitles""" start="00:24:20.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""didn't expand properly,""" start="00:24:23.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and as a result, our subtitle didn't render right.""" start="00:24:24.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Sadly, you can't use macros""" start="00:24:28.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or inline function calls everywhere.""" start="00:24:30.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And one place where they don't work""" start="00:24:32.910" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is inside of certain export keywords.""" start="00:24:34.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we're gonna have to hard code them here.""" start="00:24:37.190" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Another mistake that we made is we forgot to update""" start="00:24:43.220" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the `#+EXCLUDE_TAGS` export keyword,""" start="00:24:46.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because with the RedHat version of the document,""" start="00:24:49.100" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we want to exclude the Debian tag.""" start="00:24:51.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now when we export the document,""" start="00:24:54.510" video="mainVideo-doc" id="subtitle"]]
[[!template text="""everything should be correct.""" start="00:24:56.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The word RedHat should appear in the subtitle,""" start="00:24:57.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and the Debian fun fact section should not be present.""" start="00:25:00.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now we just need to add a section to the README""" start="00:25:04.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that explains the steps you need to take""" start="00:25:06.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in order to switch the document""" start="00:25:09.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""from RedHat to Debian.""" start="00:25:11.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Okay, let's see here.""" start="00:25:12.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We have to change `#+SUBTITLE`, change the `#+EXCLUDE_TAGS`,""" start="00:25:14.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""change the `#+EXPORT_FILE_NAME`,""" start="00:25:18.310" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and change the `prefix` property.""" start="00:25:20.430" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This is OK, but it's not great.""" start="00:25:23.290" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Emacs Lisp can once again come to our rescue.""" start="00:25:26.290" video="mainVideo-doc" id="subtitle"]]
[[!template text="""What we'll do is make an Elisp code block""" start="00:25:29.430" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that will invite the user to hit `C-c C-c` on.""" start="00:25:32.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And the code block will essentially make all these changes""" start="00:25:35.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in the document for them.""" start="00:25:39.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This code block, which we'll call `switch_distro`,""" start="00:25:40.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""takes one argument called `os`,""" start="00:25:43.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which by default is set to &quot;Debian&quot;.""" start="00:25:45.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It starts out with a let expression""" start="00:25:48.690" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that defines three bound variables.""" start="00:25:50.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The `debian` variable is a boolean that is true""" start="00:25:53.030" video="mainVideo-doc" id="subtitle"]]
[[!template text="""if the distro we're switching to is Debian.""" start="00:25:55.970" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Based on the value of this boolean,""" start="00:25:58.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we'll set the `noexport` and `prefix` variables accordingly.""" start="00:26:00.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The `save-excursion` block tells Emacs""" start="00:26:04.170" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that we're going to be moving around in the document""" start="00:26:06.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and to remember to put our point back where we started""" start="00:26:09.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""when the block finishes.""" start="00:26:11.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""After that, we essentially go to the top of the document""" start="00:26:13.430" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and search and replace the subtitle, `exclude_tags`,""" start="00:26:16.250" video="mainVideo-doc" id="subtitle"]]
[[!template text="""`export_file_name`, and the `prefix`.""" start="00:26:19.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Pretty cool.""" start="00:26:22.500" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's see this in action.""" start="00:26:23.390" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If we hit `C-c C-c` on this block,""" start="00:26:25.030" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we should see the document automatically change a bit.""" start="00:26:27.870" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And now when we export it,""" start="00:26:30.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we get the Debian version of the doc.""" start="00:26:32.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If we want to change it back,""" start="00:26:36.090" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can just head back over to the code block""" start="00:26:37.630" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and change the default value for the os variable""" start="00:26:39.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""from &quot;Debian&quot; to &quot;RedHat&quot; and hit `C-c C-c` again.""" start="00:26:43.150" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And now when we re-export,""" start="00:26:47.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we're looking at the RedHat version of the document.""" start="00:26:49.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Just as an aside, if you ever thought to yourself,""" start="00:26:52.910" video="mainVideo-doc" id="subtitle"]]
[[!template text="""&quot;I should learn Emacs Lisp someday&quot;""" start="00:26:55.860" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Make it someday soon. You'll be happy you did.""" start="00:26:58.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Not only is it a fun programming language,""" start="00:27:01.290" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but you can do powerful things with it in Emacs,""" start="00:27:03.770" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which I hope is a point that folks take away from this talk.""" start="00:27:06.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All right, that was a lot.""" start="00:27:12.150" video="mainVideo-doc" id="subtitle"]]

A tour

[[!template new="1" text="""Now that we've spent the past 20 minutes or so""" start="00:27:14.150" video="mainVideo-doc" id="subtitle"]]
[[!template text="""digging into some of the tips and tricks I used""" start="00:27:16.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""when creating my build Emacs from source document,""" start="00:27:19.410" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we'll say goodbye to this document we've been working on""" start="00:27:22.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we'll start a tour""" start="00:27:26.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of the actual literate document I wrote.""" start="00:27:27.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""A document that I'll demonstrate actually downloading""" start="00:27:29.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and building a new Emacs when I export it""" start="00:27:33.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on both my Ubuntu and RedHat virtual machines.""" start="00:27:35.660" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I'll also show you how org-mode can generate""" start="00:27:38.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""slick professional looking PDF files""" start="00:27:41.690" video="mainVideo-doc" id="subtitle"]]
[[!template text="""through the power of LaTeX.""" start="00:27:44.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll start here at the orgdemo2 directory,""" start="00:27:46.580" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which I've cloned from GitLab.""" start="00:27:49.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This repository has all the source materials for this talk.""" start="00:27:51.230" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The buildemacs.org file is where most of the good stuff is.""" start="00:27:55.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So that's where we'll start.""" start="00:27:59.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""There's a lot of file-local variables""" start="00:28:01.480" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that we'll need to confirm.""" start="00:28:03.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we'll do that too.""" start="00:28:04.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So the first thing we're gonna do""" start="00:28:06.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is hit `C-u TAB` twice,""" start="00:28:07.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which will give us a top-level overview""" start="00:28:10.780" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of all of our headings.""" start="00:28:13.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""As you can see, we've got a lot""" start="00:28:15.140" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of the same familiar export keywords we had before.""" start="00:28:16.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""`#+TITLE`, `#+SUBTITLE`, `#+AUTHOR`, `#+EMAIL`,""" start="00:28:20.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""plus a few we haven't seen before.""" start="00:28:23.100" video="mainVideo-doc" id="subtitle"]]
[[!template text="""For example, I've squirreled away""" start="00:28:25.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""a lot of the `#+LATEX_HEADER` export keywords""" start="00:28:27.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in this file called latex.setup.""" start="00:28:30.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And I did this just so they don't clutter up the document.""" start="00:28:33.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Much of the LaTeX magic""" start="00:28:36.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that makes the exported document look good""" start="00:28:38.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is in these headers.""" start="00:28:40.910" video="mainVideo-doc" id="subtitle"]]
[[!template text="""LaTeX commands begin with a backslash.""" start="00:28:42.590" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And a common one we use a lot here is `\usepackage`.""" start="00:28:45.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This lets us bring in packages like geometry,""" start="00:28:49.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""svg for the cool SeaGL SVG logo,""" start="00:28:52.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""`fancyhdr` and fancy verbatim [`fancyvrb`]""" start="00:28:56.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to keep things looking pretty fancy.""" start="00:28:58.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Using a scalable vector image format""" start="00:29:00.690" video="mainVideo-doc" id="subtitle"]]
[[!template text="""makes it possible for us to do really cool things""" start="00:29:03.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""like having a scaled-down version of the SeaGL logo""" start="00:29:05.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""appear in the fancy footer below.""" start="00:29:09.270" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I also include some macros in a separate file""" start="00:29:11.980" video="mainVideo-doc" id="subtitle"]]
[[!template text="""just to help keep things tidy in the main document.""" start="00:29:15.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Here I've got the familiar macros""" start="00:29:18.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we've seen before for `get_prop`.""" start="00:29:20.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""But here I use different permutations""" start="00:29:23.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""depending on if I want results raw""" start="00:29:25.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or raw verbatim or just verbatim.""" start="00:29:28.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I also have a couple of macros here at the top of the file""" start="00:29:31.870" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that are for pulling strings out of results blocks""" start="00:29:35.070" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then trimming them""" start="00:29:40.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""so there's no white space on either side.""" start="00:29:41.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Like in the version of the document""" start="00:29:44.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we worked on at the start of this talk,""" start="00:29:46.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the real document also has a README section""" start="00:29:48.430" video="mainVideo-doc" id="subtitle"]]
[[!template text="""marked with the `:noexport:` tag.""" start="00:29:51.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It also has a section about choosing""" start="00:29:53.470" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which version of the document to export""" start="00:29:55.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and a code block on how to switch between them.""" start="00:29:57.910" video="mainVideo-doc" id="subtitle"]]
[[!template text="""It's also got a lot of helpful information in it""" start="00:30:00.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""like what OS and Emacs versions""" start="00:30:03.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the document has been tested to &quot;run&quot; on,""" start="00:30:05.820" video="mainVideo-doc" id="subtitle"]]
[[!template text="""a section on the LaTeX prerequisites""" start="00:30:09.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and the section on executing""" start="00:30:12.330" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the document's various code blocks.""" start="00:30:14.080" video="mainVideo-doc" id="subtitle"]]

TeX and LaTeX

[[!template new="1" text="""The latter two sections we'll take a look at now.""" start="00:30:16.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Out of the box on Fedora and Ubuntu server distros,""" start="00:30:19.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the TeX typesetting system""" start="00:30:22.580" video="mainVideo-doc" id="subtitle"]]
[[!template text="""also by noted computer scientist Donald Knuth""" start="00:30:24.710" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is not installed.""" start="00:30:27.670" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we'll need to install some packages.""" start="00:30:28.860" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Starting out we'll need the `texlive` package""" start="00:30:31.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which gets you a fully featured TeX setup.""" start="00:30:34.450" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This also gets you LaTeX""" start="00:30:37.460" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which can be viewed as a distribution of TeX macros.""" start="00:30:39.290" video="mainVideo-doc" id="subtitle"]]
[[!template text="""You'll also need XeTeX.""" start="00:30:42.790" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This gets you Unicode support and lets you use modern fonts.""" start="00:30:44.900" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll also want to install pdfTeX.""" start="00:30:49.780" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This gets us the ability to generate PDFs from TeX sources.""" start="00:30:52.810" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And finally, we're gonna need to install latexmk""" start="00:30:57.210" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which is a Perl script""" start="00:31:01.300" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that knows how to run LaTeX multiple times""" start="00:31:02.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in order to properly deal with intra-document links.""" start="00:31:05.140" video="mainVideo-doc" id="subtitle"]]

Other prerequisites

[[!template new="1" text="""But wait, there's more.""" start="00:31:09.250" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We're also gonna need Inkscape""" start="00:31:11.070" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to rasterize our SeaGL vector logo""" start="00:31:12.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""at different resolutions.""" start="00:31:15.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And we're gonna need the JetBrains Mono font""" start="00:31:17.340" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to make our source code look snazzy.""" start="00:31:20.360" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll also need the Inter font""" start="00:31:23.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to make our prose look snazzy as well.""" start="00:31:24.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I've helpfully added a bash code block in the README""" start="00:31:28.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that you can hit C-c C-c on to install.""" start="00:31:31.300" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This really does lock up Emacs for a few minutes""" start="00:31:35.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and it's sort of annoying.""" start="00:31:38.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""When we export the document and turn off all caching""" start="00:31:40.330" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and it actually builds Emacs for real,""" start="00:31:43.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Emacs can be locked up for tens of minutes.""" start="00:31:45.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""There's a package called ob-async""" start="00:31:48.770" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that I've been meaning to check out that might help here.""" start="00:31:50.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""But since I wanted this document""" start="00:31:54.260" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to work on bog-standard Emacs setups,""" start="00:31:55.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I didn't get around to it.""" start="00:31:58.000" video="mainVideo-doc" id="subtitle"]]

Caching

[[!template new="1" text="""Before we get into talking about running the document,""" start="00:32:00.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""let's talk briefly about results caching.""" start="00:32:03.140" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll take a look at the section of the document""" start="00:32:06.450" video="mainVideo-doc" id="subtitle"]]
[[!template text="""where we talk about Git tags for an example.""" start="00:32:08.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The `num_tags` bash code block determines""" start="00:32:13.140" video="mainVideo-doc" id="subtitle"]]
[[!template text="""how many tags there are in the Emacs Git repo.""" start="00:32:15.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And when I hit C-c C-c on that block""" start="00:32:19.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""several days ago, when I was first creating the document,""" start="00:32:21.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that number was 183.""" start="00:32:25.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""That result has remained cached in the document since then.""" start="00:32:28.020" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And you can see a snippet of the SHA1 hash""" start="00:32:32.170" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of the contents of the source block below.""" start="00:32:34.900" video="mainVideo-doc" id="subtitle"]]
[[!template text="""You can see where I referenced the result""" start="00:32:38.390" video="mainVideo-doc" id="subtitle"]]
[[!template text="""using the `sr` for string raw macro in the prose below,""" start="00:32:40.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and how it gets rendered in the exported PDF document.""" start="00:32:44.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All the source blocks in the exported sections""" start="00:32:50.510" video="mainVideo-doc" id="subtitle"]]
[[!template text="""of the document include cached results like this.""" start="00:32:52.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If I export the document now, it won't take that long to do""" start="00:32:56.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because while there are a ton of code blocks""" start="00:33:01.390" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in the exported sections, they're all cached.""" start="00:33:03.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now let's get back to the section of the README""" start="00:33:09.070" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that explains how to execute the code in the document.""" start="00:33:11.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Here I explain that if you want to build Emacs""" start="00:33:14.910" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on your computer using this document,""" start="00:33:17.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you've got a couple of options.""" start="00:33:20.190" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The first option is to manually invalidate the caches""" start="00:33:22.020" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and take C-c C-c on every code block""" start="00:33:25.650" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in the main document.""" start="00:33:28.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This lets you supervise the entire process,""" start="00:33:30.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and it also creates new cached result blocks,""" start="00:33:33.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but it's time consuming.""" start="00:33:36.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""There is also an internal link to the main document here,""" start="00:33:39.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and you can jump to it with C-c C-o.""" start="00:33:43.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This is one of those intra-document links""" start="00:33:47.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that is really tricky to get right with LaTeX,""" start="00:33:50.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and is why we opted to use the latexmk Perl script""" start="00:33:53.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to build the PDF version of the document.""" start="00:33:56.990" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I'm mentioning it specifically here""" start="00:34:00.050" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because it took me forever to figure this out.""" start="00:34:01.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The second option you've got""" start="00:34:05.630" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is to change the default header arg""" start="00:34:07.270" video="mainVideo-doc" id="subtitle"]]
[[!template text="""from `:cache yes` to `:cache no` at the top of the document.""" start="00:34:09.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If we cruise up to the top of the document,""" start="00:34:13.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you can see that this header argument property""" start="00:34:16.270" video="mainVideo-doc" id="subtitle"]]
[[!template text="""basically says that unless a code block""" start="00:34:19.130" video="mainVideo-doc" id="subtitle"]]
[[!template text="""explicitly says otherwise,""" start="00:34:22.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""it's by default supposed to be cached.""" start="00:34:24.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""That's how we were able to export the document""" start="00:34:27.119" video="mainVideo-doc" id="subtitle"]]
[[!template text="""before so quickly.""" start="00:34:29.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""The code block named `no_cache_no_confirm`""" start="00:34:31.559" video="mainVideo-doc" id="subtitle"]]
[[!template text="""uses the `save-excursion` and regex replace trick""" start="00:34:34.820" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that I demonstrated earlier""" start="00:34:38.619" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to munch the default cache header arg""" start="00:34:40.349" video="mainVideo-doc" id="subtitle"]]
[[!template text="""from &quot;cache yes&quot; to &quot;cache no&quot;.""" start="00:34:42.820" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And it also turns off confirmations on bash code blocks.""" start="00:34:45.410" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Let's do that now.""" start="00:34:49.300" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now we'll export the document to PDF,""" start="00:34:51.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""which will ignore the cache result blocks""" start="00:34:54.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and clone the Git repository on Savannah,""" start="00:34:57.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""create a branch that points""" start="00:35:00.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to the most recently tagged version of Emacs 29,""" start="00:35:01.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""run configure a handful of times,""" start="00:35:05.460" video="mainVideo-doc" id="subtitle"]]
[[!template text="""installing packages to fix missing dependencies""" start="00:35:07.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""along the way,""" start="00:35:10.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""build Emacs, install Emacs in our home directory,""" start="00:35:12.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""verify that it has successfully built a binary,""" start="00:35:16.100" video="mainVideo-doc" id="subtitle"]]
[[!template text="""run it in batch mode with some sample Elisp""" start="00:35:19.340" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and show the file sizes and dates of the generated files.""" start="00:35:22.550" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This is gonna take a while.""" start="00:35:26.870" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And while it's running, we'll pop over to our Fedora box.""" start="00:35:28.340" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All right, now we'll fire up Emacs,""" start="00:35:32.830" video="mainVideo-doc" id="subtitle"]]
[[!template text="""hit `C-c C-c` on the `configure_document` code block""" start="00:35:34.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to configure the document for RedHat""" start="00:35:39.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""since Fedora here is a RedHat based distro.""" start="00:35:41.850" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Then what we'll do is we'll pop down""" start="00:35:45.710" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and hit `C-c C-c`""" start="00:35:47.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on the `rh_install_latex` code block""" start="00:35:49.590" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to install the LaTeX prerequisites""" start="00:35:53.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""for this Fedora virtual machine.""" start="00:35:56.230" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Finally, we'll execute the `no_cache_no_confirm` block""" start="00:35:58.460" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then kick off the export.""" start="00:36:02.590" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Then we'll go and check back on what's happening""" start="00:36:05.050" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on the Ubuntu box.""" start="00:36:07.280" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Ooh, top looks pretty quiet.""" start="00:36:09.530" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I think the export is complete.""" start="00:36:11.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Ooh, those are the words I love to see in the status area,""" start="00:36:14.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""PDF file produced!""" start="00:36:17.560" video="mainVideo-doc" id="subtitle"]]

Looking at the PDF

[[!template new="1" text="""Now I can't use my web browser""" start="00:36:20.610" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to take a look at this PDF file""" start="00:36:22.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because I haven't set up a web server""" start="00:36:24.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or anything like that on the Ubuntu virtual machine.""" start="00:36:27.080" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I can, however, use TRAMP with the ssh method""" start="00:36:30.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to poke around on the ubuntu host""" start="00:36:34.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""on my personal version of Emacs.""" start="00:36:36.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So let's do that.""" start="00:36:39.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Okay, so now if we go into the source directory""" start="00:36:40.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then we hop into the orgdemo2 directory""" start="00:36:44.810" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then we look at the deb version of the PDF,""" start="00:36:48.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""there she blows.""" start="00:36:51.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now, if we go down to the Building Emacs section,""" start="00:36:54.150" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can see that it built.""" start="00:36:58.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And if we look in the bin directory,""" start="00:37:00.130" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can see that at 17:01,""" start="00:37:03.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that's when all of those files got created.""" start="00:37:06.780" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Also the file creation date on the PDF is 17:01.""" start="00:37:11.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So all of this code executed roughly the same time""" start="00:37:15.590" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the PDF was created.""" start="00:37:18.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All right, so now let's head back over to the Fedora box""" start="00:37:21.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then we'll navigate to the source directory,""" start="00:37:25.340" video="mainVideo-doc" id="subtitle"]]
[[!template text="""the orgdemo2 directory,""" start="00:37:27.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and there is our RedHat version of the built Emacs PDF.""" start="00:37:30.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And Bob's your uncle.""" start="00:37:35.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And you can see it is the RedHat version of the document""" start="00:37:38.220" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because this is a RedHat box.""" start="00:37:42.550" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And if we go over to the What did we install? section,""" start="00:37:44.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you can see that these binaries were built at 17:35.""" start="00:37:51.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And now if we pop open dired""" start="00:37:56.050" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we take a look at the PDF,""" start="00:37:58.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we can see it also was created at 17:35.""" start="00:38:00.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All right, in the couple minutes remaining,""" start="00:38:07.330" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I thought it would be a good idea""" start="00:38:10.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""just to take a look at the document""" start="00:38:11.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and maybe just go through some of what it actually does""" start="00:38:15.740" video="mainVideo-doc" id="subtitle"]]
[[!template text="""in explaining how to build Emacs from source.""" start="00:38:19.000" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We'll look at the RedHat version since we're here.""" start="00:38:22.580" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And the first thing you do is""" start="00:38:27.140" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you have to get access to the source code.""" start="00:38:28.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And before you can do anything,""" start="00:38:31.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""this is a RedHat-specific section""" start="00:38:32.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""where you need to install some development tools.""" start="00:38:35.420" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And this development tools group actually has Git.""" start="00:38:38.300" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Now I installed Git earlier, but if you didn't do that,""" start="00:38:41.540" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that would be the first thing that you need to do.""" start="00:38:44.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We create a source directory, we cd into it,""" start="00:38:46.940" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we clone the repo from Savannah.""" start="00:38:50.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we start to take a look at some of the Git tags.""" start="00:38:53.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And we showed this before where we check out""" start="00:38:56.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""how many different tags there are.""" start="00:38:58.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we run this kind of funky Git command""" start="00:39:00.370" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to sort of list all the tags that begin with 'emacs-29',""" start="00:39:02.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and we sort them by when they were tagged.""" start="00:39:06.040" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we can see that Emacs 29.1.pretest""" start="00:39:08.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""is the most recent version.""" start="00:39:12.400" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So that's the one we grab""" start="00:39:14.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and that's the one we decide to build.""" start="00:39:15.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we create a branch that is based on this tag.""" start="00:39:18.660" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And this is dynamically generated based on what we saw here.""" start="00:39:22.780" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So that's what we use here.""" start="00:39:27.480" video="mainVideo-doc" id="subtitle"]]

Errors

[[!template new="1" text="""In this case, we're piping standard error""" start="00:39:29.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to where standard out goes.""" start="00:39:32.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""That's another trick.""" start="00:39:35.100" video="mainVideo-doc" id="subtitle"]]
[[!template text="""If you want to actually see an error get created,""" start="00:39:36.070" video="mainVideo-doc" id="subtitle"]]
[[!template text="""org-mode will capture any errors that code blocks produce,""" start="00:39:39.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and it will show you the error message in a buffer.""" start="00:39:44.120" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So if you actually wanna show what it looks like""" start="00:39:46.820" video="mainVideo-doc" id="subtitle"]]
[[!template text="""when something errors out, this is the trick you have to use.""" start="00:39:49.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then what we do is we look for a configure script""" start="00:39:53.060" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and there isn't one.""" start="00:39:56.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we realize,""" start="00:39:57.420" video="mainVideo-doc" id="subtitle"]]
[[!template text="""uh-oh, we're gonna have to deal with autotools.""" start="00:39:58.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So, you know, we run the autogen script and it complains""" start="00:40:00.910" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because we're missing some prerequisites.""" start="00:40:05.560" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we have to install autoconf,""" start="00:40:08.680" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then we run it again,""" start="00:40:11.350" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and finally it generates a configure script.""" start="00:40:13.020" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And this is another case where I pull this number""" start="00:40:15.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""right here into the actual prose.""" start="00:40:19.020" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And I can see it's, oh, it's, you know, this how many bytes.""" start="00:40:21.980" video="mainVideo-doc" id="subtitle"]]
[[!template text="""When was the last time you wrote a shell script""" start="00:40:24.840" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that was this many bytes long?""" start="00:40:26.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we configure the build process.""" start="00:40:29.580" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And, you know, it's not gonna work right away""" start="00:40:31.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""because we don't have GNU Texinfo installed.""" start="00:40:33.760" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So we gotta do that, which we do with `dnf install` here.""" start="00:40:36.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then there's this section that is either RedHat-""" start="00:40:41.440" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or Debian-specific that talks about, like,""" start="00:40:44.320" video="mainVideo-doc" id="subtitle"]]
[[!template text="""if you don't know the name of a package""" start="00:40:48.920" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that contains a given file name, how do you query it?""" start="00:40:51.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And in the RedHat world, you use `dnf provides makeinfo`.""" start="00:40:55.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""In the Debian world, you do something entirely different.""" start="00:40:59.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we have to install the `ncurses` binary.""" start="00:41:02.290" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And finally we get like a minimal configuration""" start="00:41:06.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and you can see that there's a whole bunch of nos here.""" start="00:41:10.300" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So, you know, we don't have cairo,""" start="00:41:13.700" video="mainVideo-doc" id="subtitle"]]
[[!template text="""we don't have imagemagick, we don't have dbus,""" start="00:41:15.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""you know, there's a whole bunch of stuff we don't have.""" start="00:41:18.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""We don't have X, we don't have libjansson, no tree-sitter.""" start="00:41:20.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This is really a bare-bones Emacs""" start="00:41:23.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""that is strictly terminal mode.""" start="00:41:25.960" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Then we actually build Emacs, which is, you know,""" start="00:41:28.640" video="mainVideo-doc" id="subtitle"]]
[[!template text="""kind of boring, we're just gonna type make""" start="00:41:30.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then make is gonna run successfully.""" start="00:41:33.260" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And make is gonna spew a ton of output, right?""" start="00:41:35.260" video="mainVideo-doc" id="subtitle"]]
[[!template text="""So here's where I do that /dev/null trick,""" start="00:41:37.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""where I pipe everything to /dev/null""" start="00:41:41.100" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then I, or I pipe standard output to /dev/null""" start="00:41:42.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and then I pipe standard error""" start="00:41:45.820" video="mainVideo-doc" id="subtitle"]]
[[!template text="""to wherever standard output's going.""" start="00:41:47.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then at the end to say that it ran successfully,""" start="00:41:50.240" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I say &quot;Make ran successfully!&quot;""" start="00:41:52.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Then we take a look at the Emacs binary""" start="00:41:55.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and you know, it's an elf binary.""" start="00:41:57.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And, you know, because this is running on my Mac,""" start="00:41:59.880" video="mainVideo-doc" id="subtitle"]]
[[!template text="""this is an ARM-based machine, this virtual machine is.""" start="00:42:01.720" video="mainVideo-doc" id="subtitle"]]
[[!template text="""Oops, and this is a bug.""" start="00:42:06.620" video="mainVideo-doc" id="subtitle"]]
[[!template text="""This really should be a macro call,""" start="00:42:10.520" video="mainVideo-doc" id="subtitle"]]
[[!template text="""but I think I have the wrong number of curly braces""" start="00:42:12.200" video="mainVideo-doc" id="subtitle"]]
[[!template text="""or something in there.""" start="00:42:14.800" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I need to figure out why that's not right.""" start="00:42:16.160" video="mainVideo-doc" id="subtitle"]]
[[!template text="""I'll look into that later.""" start="00:42:19.130" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we install Emacs and then we kind of show""" start="00:42:21.110" video="mainVideo-doc" id="subtitle"]]
[[!template text="""like the file sizes of everything in the home directory.""" start="00:42:23.980" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And then we, you know, show the binaries that got installed.""" start="00:42:27.720" video="mainVideo-doc" id="subtitle"]]

Final thoughts

[[!template new="1" text="""Anyway, so this is the final thoughts section.""" start="00:42:31.990" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And my final thoughts are, is I hope you enjoyed this talk""" start="00:42:35.600" video="mainVideo-doc" id="subtitle"]]
[[!template text="""and I hope you actually learned a thing or two.""" start="00:42:39.220" video="mainVideo-doc" id="subtitle"]]
[[!template text="""All right, thanks everybody.""" start="00:42:42.380" video="mainVideo-doc" id="subtitle"]]
[[!template text="""And I'll see you all next time.""" start="00:42:43.360" video="mainVideo-doc" id="subtitle"]]



Captioner: jc

Questions or comments? Please e-mail [emacsconf-org-private@gnu.org](mailto:emacsconf-org-private@gnu.org?subject=Comment%20for%20EmacsConf%202023%20doc%3A%20Literate%20Documentation%20with%20Emacs%20and%20Org%20Mode)


<!-- End of emacsconf-publish-after-page -->