diff options
Diffstat (limited to '2023/captions/emacsconf-2023-doc--literate-documentation-with-emacs-and-org-mode--mike-hamrick--main.vtt')
| -rw-r--r-- | 2023/captions/emacsconf-2023-doc--literate-documentation-with-emacs-and-org-mode--mike-hamrick--main.vtt | 2759 |
1 files changed, 2759 insertions, 0 deletions
diff --git a/2023/captions/emacsconf-2023-doc--literate-documentation-with-emacs-and-org-mode--mike-hamrick--main.vtt b/2023/captions/emacsconf-2023-doc--literate-documentation-with-emacs-and-org-mode--mike-hamrick--main.vtt new file mode 100644 index 00000000..71fa30f7 --- /dev/null +++ b/2023/captions/emacsconf-2023-doc--literate-documentation-with-emacs-and-org-mode--mike-hamrick--main.vtt @@ -0,0 +1,2759 @@ +WEBVTT captioned by jc, checked by sachac + +NOTE Introduction + +00:00:00.000 --> 00:00:04.320 +Hello, everyone. + +00:00:04.320 --> 00:00:07.280 +This talk is on literate documentation + +00:00:07.280 --> 00:00:10.320 +with Emacs and org-mode. + +00:00:10.320 --> 00:00:12.080 +I'm going to take just a moment here + +00:00:12.080 --> 00:00:14.279 +to unpack what I just said. + +00:00:14.280 --> 00:00:17.800 +Emacs, as most of us probably already know, + +00:00:17.800 --> 00:00:21.360 +is a powerful text editor and list programming environment + +00:00:21.360 --> 00:00:23.480 +from the 1970s. + +00:00:23.480 --> 00:00:25.800 +Chances are, if you're attending this talk, + +00:00:25.800 --> 00:00:28.819 +you already know a bit about Emacs. + +00:00:28.820 --> 00:00:32.640 +org-mode is an Emacs major mode and authoring tool + +00:00:32.640 --> 00:00:36.360 +that helps you write documents in a plain text markup + +00:00:36.360 --> 00:00:37.739 +language called Org. + +00:00:37.740 --> 00:00:40.200 +These Org documents can be exported + +00:00:40.200 --> 00:00:42.520 +to a number of different document formats, + +00:00:42.520 --> 00:00:48.520 +like HTML, PDF, ODT, Markdown, and more. + +00:00:48.520 --> 00:00:51.160 +org-mode has a lot of features. + +00:00:51.160 --> 00:00:54.240 +It can be an outliner, a to-do list manager, + +00:00:54.240 --> 00:00:57.760 +an agenda, organizer, and much more. + +NOTE Org Babel and literate programming + +00:00:57.760 --> 00:00:59.600 +Today, we're going to be demonstrating + +00:00:59.600 --> 00:01:03.360 +what I consider to be org-mode's killer feature called + +00:01:03.360 --> 00:01:04.840 +Org Babel. + +00:01:04.840 --> 00:01:07.879 +Babel allows you to take human language prose, + +00:01:07.880 --> 00:01:11.400 +computer language source code blocks, and their outputs + +00:01:11.400 --> 00:01:13.840 +and weave them together seamlessly + +00:01:13.840 --> 00:01:16.160 +to form a cohesive document. + +00:01:16.160 --> 00:01:19.080 +It is seriously cool. + +00:01:19.080 --> 00:01:21.880 +Literate documentation is a play on the term + +00:01:21.880 --> 00:01:25.280 +literate programming, popularized by Donald Knuth + +00:01:25.280 --> 00:01:27.379 +in the early 1980s. + +00:01:27.380 --> 00:01:29.280 +Knuth's literate programming idea + +00:01:29.280 --> 00:01:31.920 +was that computer programs could be + +00:01:31.920 --> 00:01:34.880 +expressed in a natural language and be + +00:01:34.880 --> 00:01:38.800 +human-readable documents rather than written exclusively + +00:01:38.800 --> 00:01:40.799 +for machines to read. + +00:01:40.800 --> 00:01:43.000 +In a traditional program, you might + +00:01:43.000 --> 00:01:45.680 +have a bunch of machine-readable source code + +00:01:45.680 --> 00:01:48.560 +and a handful of human-readable comments, + +00:01:48.560 --> 00:01:51.600 +which attempt to describe what the program is doing. + +00:01:51.600 --> 00:01:54.360 +Literate programming flips this on its head. + +00:01:54.360 --> 00:01:56.680 +A literate program is a document that + +00:01:56.680 --> 00:02:01.160 +describes how the program works with machine-readable source + +00:02:01.160 --> 00:02:02.880 +code blocks inside of it. + +00:02:02.880 --> 00:02:04.800 +These source code blocks are later + +00:02:04.800 --> 00:02:08.440 +tangled out of the document and submitted to the machine + +00:02:08.440 --> 00:02:14.080 +either to be compiled or interpreted and ultimately run. + +NOTE This presentation + +00:02:14.080 --> 00:02:15.600 +Throughout this presentation, you'll + +00:02:15.600 --> 00:02:19.400 +see my browser window here on the left side of the screen. + +00:02:19.400 --> 00:02:22.240 +And on the right side, I've got a terminal session + +00:02:22.240 --> 00:02:23.960 +running tmux. + +00:02:23.960 --> 00:02:28.039 +This allows us to have a virtual terminal window connected + +00:02:28.040 --> 00:02:35.040 +to two separate Linux machines, one running Ubuntu Server 2204 + +00:02:35.040 --> 00:02:39.720 +and another running Fedora Server 38. + +00:02:39.720 --> 00:02:43.240 +I've specifically chosen these two distributions for my demo + +00:02:43.440 --> 00:02:46.720 +because they are representative of the two dominant flavors + +00:02:46.720 --> 00:02:49.880 +of GNU Linux, Debian and RedHat. + +00:02:49.880 --> 00:02:53.120 +In both cases, these are bare-bones server additions + +00:02:53.120 --> 00:02:55.440 +with the stock packages installed. + +00:02:55.440 --> 00:03:00.200 +I've manually installed a few packages like Git, emacs-noex + +00:03:00.200 --> 00:03:04.000 +to get the terminal version of emacs, and tmux. + +00:03:04.000 --> 00:03:06.000 +But otherwise, these Linux installs + +00:03:06.000 --> 00:03:08.719 +are what you'd get right out of the box. + +00:03:08.720 --> 00:03:12.480 +For this demo, I've created a literate org-mode document + +00:03:12.480 --> 00:03:16.360 +that describes how to build GNU Emacs from its source code + +00:03:16.360 --> 00:03:19.939 +on both Debian and RedHat-based systems. + +00:03:19.940 --> 00:03:22.920 +While both operating systems are very similar, + +00:03:22.920 --> 00:03:25.440 +they differ substantially on which packages + +00:03:25.440 --> 00:03:29.080 +are installed out of the box, how optional packages are + +00:03:29.080 --> 00:03:32.600 +named, searched, and installed, and of course, + +00:03:32.600 --> 00:03:34.240 +the distributions have different names, + +00:03:34.240 --> 00:03:36.800 +like Ubuntu or Fedora. + +00:03:36.800 --> 00:03:39.200 +I chose building Emacs from source + +00:03:39.200 --> 00:03:41.640 +as a topic for this demonstration + +00:03:41.640 --> 00:03:43.800 +because while the process is largely + +00:03:43.800 --> 00:03:46.880 +the same on both RedHat and Debian, + +00:03:46.880 --> 00:03:49.360 +there are a lot of minor little differences + +00:03:49.360 --> 00:03:52.680 +that need to be accounted for, which really prohibits you + +00:03:52.680 --> 00:03:57.120 +from hard coding names of packages and package management + +00:03:57.120 --> 00:04:01.200 +tools and distributions into your document. + +00:04:01.200 --> 00:04:05.320 +I suppose you could create two versions of the same document, + +00:04:05.320 --> 00:04:09.960 +one specifically for RedHat and one specifically for Debian, + +00:04:09.960 --> 00:04:13.280 +but that would be really tedious to maintain. + +00:04:13.280 --> 00:04:16.280 +Like if, for example, you updated some prose + +00:04:16.280 --> 00:04:18.720 +in one document, you'd have to remember + +00:04:18.720 --> 00:04:20.280 +to do it in the other one too. + +00:04:20.280 --> 00:04:22.920 +And if you weren't careful, the two documents + +00:04:22.920 --> 00:04:25.259 +could drift out of sync. + +00:04:25.260 --> 00:04:27.720 +In this demo, I'll show you techniques + +00:04:27.720 --> 00:04:30.960 +for creating dynamic, literate documents that + +00:04:30.960 --> 00:04:34.619 +can change based on parameters and constants embedded + +00:04:34.620 --> 00:04:38.439 +into the non-exported regions of the document. + +00:04:38.440 --> 00:04:41.800 +I'll show how with a single org-mode source document, + +00:04:41.800 --> 00:04:44.800 +you can press a couple of keys to configure + +00:04:44.800 --> 00:04:48.720 +it to export a RedHat-specific version of my building + +00:04:48.720 --> 00:04:53.479 +Emacs from source essay or a Debian-specific version. + +NOTE Getting started + +00:04:53.480 --> 00:04:55.320 +All right, let's get started. + +00:04:55.320 --> 00:04:58.720 +We'll begin by firing up a new terminal Emacs session + +00:04:58.720 --> 00:05:00.639 +on my Ubuntu machine. + +00:05:00.640 --> 00:05:04.600 +Now, I installed Emacs on this machine using apt-get. + +00:05:04.600 --> 00:05:07.960 +And doing that, you get version 27.1, + +00:05:07.960 --> 00:05:10.640 +which is, hey, only two major versions + +00:05:10.640 --> 00:05:13.010 +behind the current version of Emacs. + +00:05:13.011 --> 00:05:15.000 +This is another reason why I thought + +00:05:15.000 --> 00:05:18.080 +writing a guide on how to build Emacs from source code + +00:05:18.080 --> 00:05:19.719 +might be a good idea. + +00:05:19.720 --> 00:05:22.720 +You can get a much newer version of Emacs on Ubuntu + +00:05:22.720 --> 00:05:25.800 +if you install it via Snap, but, uh, Snaps. + +00:05:25.800 --> 00:05:28.239 +Don't get me started. + +00:05:28.240 --> 00:05:30.921 +Now, I wanted to use a completely vanilla + +00:05:30.922 --> 00:05:34.619 +terminal mode install of Emacs for this demonstration + +00:05:34.620 --> 00:05:38.040 +because my personal Emacs config has a ton of packages + +00:05:38.040 --> 00:05:41.199 +installed and is heavily modified. + +00:05:41.200 --> 00:05:43.640 +I want folks to be able to follow along + +00:05:43.640 --> 00:05:47.579 +with a bog-standard, out-of-the-box Emacs config. + +00:05:47.580 --> 00:05:49.520 +The Emacs config on this Ubuntu machine + +00:05:49.520 --> 00:05:51.200 +has just two settings. + +00:05:51.200 --> 00:05:55.240 +I require org-tempo because my fingers are hardwired + +00:05:55.240 --> 00:05:58.719 +to use some of the handy shortcuts that it provides. + +00:05:58.720 --> 00:06:00.520 +And I also turn off the menu bar + +00:06:00.520 --> 00:06:03.139 +because I just can't stand to look at it. + +00:06:03.140 --> 00:06:07.040 +Let's begin by opening a file called buildemacs.org, + +00:06:07.040 --> 00:06:08.480 +which will be the source code + +00:06:08.480 --> 00:06:11.079 +for our literate org-mode document. + +00:06:11.080 --> 00:06:12.840 +Now, in preparation for this talk, + +00:06:12.840 --> 00:06:14.960 +I've already written this document, + +00:06:14.960 --> 00:06:17.979 +and we'll take a look at the finished product + +00:06:17.980 --> 00:06:19.160 +here in a bit, but let's first take a look + +00:06:19.160 --> 00:06:22.408 +at how we might approach this task. + +00:06:22.409 --> 00:06:24.400 +We'll start at the top of the document + +00:06:24.400 --> 00:06:27.119 +by filling out some export keywords. + +00:06:27.120 --> 00:06:30.520 +These keywords are something that every backend exporter, + +00:06:30.520 --> 00:06:35.000 +be it LaTeX or plain text or ODT or whatever, understands, + +00:06:35.000 --> 00:06:38.120 +and they're essentially document metadata. + +00:06:38.120 --> 00:06:42.120 +As you can see, I'm typing `#+` + +00:06:42.120 --> 00:06:43.760 +followed by a couple characters + +00:06:43.760 --> 00:06:45.880 +and then `M-TAB` to auto-complete. + +00:06:45.880 --> 00:06:50.360 +If you hit #+ by itself and then M-TAB, + +00:06:50.360 --> 00:06:53.119 +you can see all the possible completions. + +00:06:53.120 --> 00:06:55.779 +And as you can see, there's a lot. + +NOTE README + +00:06:55.780 --> 00:06:58.520 +The next thing we're gonna do is make a README section + +00:06:58.520 --> 00:06:59.760 +at the top of this document. + +00:06:59.760 --> 00:07:02.240 +This section is intended for folks + +00:07:02.240 --> 00:07:04.280 +who are looking at the org-mode document, + +00:07:04.280 --> 00:07:06.679 +trying to figure out what it's for. + +00:07:06.680 --> 00:07:09.600 +We don't want to actually export the section heading, + +00:07:09.600 --> 00:07:13.859 +so we're gonna tag it with the :noexport: tag. + +00:07:13.860 --> 00:07:15.640 +And then here, we just write something quick + +00:07:15.640 --> 00:07:17.760 +to let folks know that this document + +00:07:17.760 --> 00:07:19.800 +can potentially execute code + +00:07:19.800 --> 00:07:23.499 +and just a little something about what the document is for. + +NOTE Writing a code block + +00:07:23.500 --> 00:07:26.059 +Okay, so now that we've written some text, + +00:07:26.060 --> 00:07:29.599 +let's try our hand at writing a code block. + +00:07:29.600 --> 00:07:31.288 +I'm getting pretty sick of looking at + +00:07:31.289 --> 00:07:32.939 +the default Emacs theme. + +00:07:32.940 --> 00:07:35.440 +All that blue and purple in the document + +00:07:35.440 --> 00:07:37.879 +makes it look bruised. + +00:07:37.880 --> 00:07:40.320 +Let's make an Emacs Lisp code block + +00:07:40.320 --> 00:07:41.400 +that switches the theme + +00:07:41.400 --> 00:07:44.560 +to one of my favorite built-in themes, Leuven. + +00:07:44.560 --> 00:07:48.400 +Leuven was created by my man, Fabrice Niessen, + +00:07:48.400 --> 00:07:52.120 +who I personally have learned a ton of org-mode stuff about + +00:07:52.120 --> 00:07:54.039 +just by studying his work. + +00:07:54.040 --> 00:07:56.360 +Now, if we cruise back up to the code block, + +00:07:56.360 --> 00:07:58.840 +we should be able to hit `C-c C-c`, + +00:07:58.840 --> 00:08:00.379 +and have it execute. + +00:08:00.380 --> 00:08:03.880 +And there you have it, a high-contrast color theme + +00:08:03.880 --> 00:08:06.979 +that was designed to look great in org-mode. + +00:08:06.980 --> 00:08:08.080 +So that's great and all, + +00:08:08.080 --> 00:08:10.459 +but there are a couple of things I don't like. + +NOTE :results none + +00:08:10.460 --> 00:08:13.599 +First of all, we don't need to see a #+RESULTS block here, + +00:08:13.600 --> 00:08:15.280 +and that's because we're not really interested + +00:08:15.280 --> 00:08:18.720 +in what the Emacs Lisp function `load-theme` returns. + +00:08:18.720 --> 00:08:22.200 +I mean, it's great it returned t and all to indicate success, + +00:08:22.200 --> 00:08:23.720 +we just don't need to see it. + +00:08:23.720 --> 00:08:26.560 +We can slap a `:results none` header arg + +00:08:26.560 --> 00:08:30.039 +on the code block to keep things nice and clean. + +00:08:30.040 --> 00:08:32.560 +There are a lot of different header args, + +00:08:32.560 --> 00:08:35.360 +and I often confuse and misremember them. + +00:08:35.360 --> 00:08:38.920 +So I'll always refer back to the org-mode manual + +00:08:38.920 --> 00:08:40.319 +when working with them. + +NOTE Confirmation + +00:08:40.320 --> 00:08:42.160 +The second thing I don't like is that + +00:08:42.160 --> 00:08:45.999 +when we hit C-c C-c to execute the block, + +00:08:46.000 --> 00:08:49.600 +Emacs prompted us if we really wanted to run the block. + +00:08:49.600 --> 00:08:52.040 +Emacs Lisp is Emacs' mother tongue, + +00:08:52.040 --> 00:08:53.920 +and I don't wanna be hassled when speaking + +00:08:53.920 --> 00:08:55.379 +my native language. + +00:08:55.380 --> 00:08:57.520 +There's a variable that controls this + +00:08:57.520 --> 00:09:00.680 +called `org-confirm-babel-evaluate`. + +00:09:00.680 --> 00:09:03.960 +And this can be either set to t or nil + +00:09:03.960 --> 00:09:06.840 +to either always confirm or never confirm. + +00:09:06.840 --> 00:09:10.920 +If however, you provided a lambda, an anonymous function, + +00:09:10.920 --> 00:09:14.560 +Org will call your function with the name of the language + +00:09:14.560 --> 00:09:16.840 +and the source block that it's about to run. + +00:09:16.840 --> 00:09:19.080 +And your function can make the decision + +00:09:19.080 --> 00:09:24.200 +about if Emacs should ask you for confirmation or not. + +00:09:24.200 --> 00:09:27.840 +What I'm doing here is setting `org-confirm-babel-evaluate` + +00:09:27.840 --> 00:09:30.539 +as a "file local variable". + +00:09:30.540 --> 00:09:33.320 +This means whenever the file is opened by Emacs, + +00:09:33.320 --> 00:09:38.059 +it'll set this variable to be a lambda that returns nil, + +00:09:38.060 --> 00:09:42.859 +meaning don't confirm, on Elisp code blocks. + +00:09:42.860 --> 00:09:45.920 +As you can see, the variable is currently set + +00:09:45.920 --> 00:09:50.879 +to its default value of t, meaning always confirm. + +00:09:50.880 --> 00:09:53.640 +Now if we save the buffer, exit Emacs, + +00:09:53.640 --> 00:09:55.040 +and pop back in again, + +00:09:55.040 --> 00:10:00.120 +`org-confirm-babel-evaluate` should be set how we like it. + +00:10:00.120 --> 00:10:02.640 +We were however prompted for confirmation + +00:10:02.640 --> 00:10:04.400 +on setting the file-local variable, + +00:10:04.400 --> 00:10:06.280 +which controls if we're prompted + +00:10:06.280 --> 00:10:09.699 +for Elisp source code block evaluation. + +00:10:09.700 --> 00:10:12.679 +I feel like there's a Yo Dawg joke here somewhere. + +00:10:12.680 --> 00:10:15.240 +When we were prompted, we hit the exclamation mark, + +00:10:15.240 --> 00:10:18.400 +which automatically marks this variable as being safe. + +00:10:18.400 --> 00:10:21.520 +So you won't be bothered the next time you open this file. + +00:10:21.520 --> 00:10:26.760 +This variable is called `safe-local-variable-values` + +00:10:26.760 --> 00:10:29.560 +and if we pop over to our .emacs file, + +00:10:29.560 --> 00:10:32.520 +you can see that Emacs' customize tooling + +00:10:32.520 --> 00:10:36.959 +helpfully updated this variable in our config file for us. + +NOTE Running blocks automatically + +00:10:36.960 --> 00:10:38.120 +Now that's great and all, + +00:10:38.120 --> 00:10:42.120 +but I really don't like having to hit `C-c C-c` + +00:10:42.120 --> 00:10:45.160 +on that source block every time I open this document + +00:10:45.160 --> 00:10:47.739 +just to bring up the Leuven theme. + +00:10:47.740 --> 00:10:50.520 +Let's have this source block run automatically + +00:10:50.520 --> 00:10:53.179 +every time the document is opened. + +00:10:53.180 --> 00:10:54.999 +Now I know what you're thinking. + +00:10:55.000 --> 00:10:57.640 +Shouldn't you just put all of this configuration stuff + +00:10:57.640 --> 00:11:01.159 +in your .emacs file and keep it out of the document? + +00:11:01.160 --> 00:11:04.760 +Well, that's what I've done with my personal Emacs config, + +00:11:04.760 --> 00:11:08.160 +but we want this document to be able to be used by folks + +00:11:08.160 --> 00:11:11.040 +with a completely vanilla Emacs setup, + +00:11:11.040 --> 00:11:13.440 +or even a completely tricked out Emacs setup, + +00:11:13.440 --> 00:11:16.059 +so we can't assume anything. + +00:11:16.060 --> 00:11:19.800 +The idea is if the Emacs user who opens the document + +00:11:19.800 --> 00:11:22.400 +agrees to setting all of the variables + +00:11:22.400 --> 00:11:24.359 +and running all of the code within, + +00:11:24.360 --> 00:11:26.560 +they'll be able to export the document + +00:11:26.560 --> 00:11:28.840 +as well as run all of the code blocks inside of it + +00:11:28.840 --> 00:11:30.799 +just as we intended. + +00:11:30.800 --> 00:11:33.880 +And the differences in base Emacs configuration + +00:11:33.880 --> 00:11:35.979 +will be completely minimized. + +00:11:35.980 --> 00:11:39.080 +Now it's worth pointing out that the file-local variables + +00:11:39.080 --> 00:11:43.023 +we're setting here are local, in this case, buffer-local. + +00:11:43.024 --> 00:11:45.280 +The configuration we use in this document + +00:11:45.280 --> 00:11:48.280 +won't override someone's carefully constructed + +00:11:48.280 --> 00:11:49.499 +org-mode setup. + +00:11:49.500 --> 00:11:50.800 +The first thing we're gonna wanna do + +00:11:51.000 --> 00:11:53.080 +in order to make this block execute + +00:11:53.080 --> 00:11:55.988 +when the document is loaded is to give it a name. + +00:11:55.989 --> 00:11:58.800 +It's always a good idea to give every source block + +00:11:58.800 --> 00:12:01.337 +you create in your document a unique name, + +00:12:01.338 --> 00:12:03.400 +even if you don't refer to it elsewhere. + +00:12:03.700 --> 00:12:06.960 +I do this because when I'm debugging my documents, + +00:12:07.160 --> 00:12:10.019 +Emacs will prompt me about running a block. + +00:12:10.020 --> 00:12:12.960 +If the block has a name, Emacs mentions it, + +00:12:12.960 --> 00:12:15.960 +and I know there's a problem with the result caching + +00:12:15.960 --> 00:12:17.840 +or something with the "foo" block. + +00:12:17.840 --> 00:12:20.280 +But if the block doesn't have a name, + +00:12:20.280 --> 00:12:22.160 +it can be really hard to figure out + +00:12:22.160 --> 00:12:24.579 +which block Emacs is complaining about. + +00:12:24.580 --> 00:12:27.459 +So I always name my blocks. + +00:12:27.460 --> 00:12:30.360 +Now we're gonna add another file local variable, + +00:12:30.360 --> 00:12:32.115 +but this one is special. + +00:12:32.116 --> 00:12:34.360 +If your "variable" + +00:12:34.360 --> 00:12:36.320 +just happens to be named "eval", + +00:12:36.320 --> 00:12:38.760 +it means that Emacs should evaluate + +00:12:38.760 --> 00:12:40.800 +the Lisp expression that follows. + +00:12:40.800 --> 00:12:43.240 +Here we'll use the progn function + +00:12:43.240 --> 00:12:46.040 +to sequentially run two elisp functions + +00:12:46.040 --> 00:12:48.760 +and return the value of the last one executed. + +00:12:48.760 --> 00:12:53.320 +The first function is `org-babel-goto-named-source-block`, + +00:12:53.320 --> 00:12:55.440 +which jumps us to the startup block. + +00:12:55.440 --> 00:12:59.280 +The second one is `org-babel-execute-src-block`, + +00:12:59.280 --> 00:13:02.092 +which executes the current source block. + +00:13:02.093 --> 00:13:03.630 +That should get the job done. + +00:13:03.631 --> 00:13:05.840 +Now all we have to do is save the document, + +00:13:05.840 --> 00:13:08.199 +exit Emacs, jump back in, + +00:13:08.200 --> 00:13:10.280 +and once we've confirmed that we're willing + +00:13:10.280 --> 00:13:14.239 +to run the new "eval" line in our file local variables, + +00:13:14.240 --> 00:13:15.859 +we're good to go. + +00:13:15.860 --> 00:13:18.480 +Now if we want to add new configuration stuff + +00:13:18.480 --> 00:13:21.839 +to the document, we can just add it to the startup block + +00:13:21.840 --> 00:13:24.880 +and not have to muck about with confirmations + +00:13:24.880 --> 00:13:28.679 +or adding new file-local variables or whatever. + +00:13:28.680 --> 00:13:31.960 +And just like before, we'll let Emacs' customize system + +00:13:31.960 --> 00:13:34.939 +save this decision to our .emacs file. + +00:13:34.940 --> 00:13:37.760 +Now that all that business with confirmations, + +00:13:37.760 --> 00:13:40.080 +file-local variables, and the startup block + +00:13:40.080 --> 00:13:41.120 +are out of the way, + +00:13:41.120 --> 00:13:44.120 +we can get on with writing our introduction. + +00:13:44.120 --> 00:13:47.880 +We'll create a new top level headline called introduction + +00:13:47.880 --> 00:13:51.440 +and explain to the reader of the exported document + +00:13:51.440 --> 00:13:52.600 +what this is all about. + +NOTE Export options + +00:13:53.000 --> 00:13:55.640 +Now as you can see, we've actually hard-coded + +00:13:55.640 --> 00:13:58.280 +the name of the Linux distro in our prose. + +00:13:58.280 --> 00:14:00.880 +I promised you a single document that could be + +00:14:00.880 --> 00:14:03.720 +for either RedHat or Debian distros, + +00:14:03.720 --> 00:14:05.319 +so we can't have this. + +00:14:05.320 --> 00:14:08.840 +Astute members in the audience have probably been uneasy + +00:14:08.840 --> 00:14:11.280 +ever since I hard coded the name "Debian" + +00:14:11.280 --> 00:14:13.859 +in the README section above. + +00:14:13.860 --> 00:14:17.520 +One way of solving this problem is by using exclude tags. + +00:14:17.520 --> 00:14:21.960 +Let's add the `#+EXCLUDE_TAGS` export keyword to our document. + +00:14:21.960 --> 00:14:24.200 +This keyword tells the exporter, + +00:14:24.200 --> 00:14:27.959 +"Hey, if you see a headline tagged with any of these tags, + +00:14:27.960 --> 00:14:29.600 +don't export it." + +00:14:29.600 --> 00:14:33.559 +By default, the tag `:noexport:` is excluded. + +00:14:33.560 --> 00:14:36.480 +And if you'll notice, we tagged our README section + +00:14:36.480 --> 00:14:38.360 +with that tag, so it doesn't show up + +00:14:38.360 --> 00:14:40.339 +in the exported document. + +00:14:40.340 --> 00:14:42.280 +We'll keep this tag in the list, + +00:14:42.280 --> 00:14:47.080 +but we'll also add the tag `:redhat:` as a tag to exclude. + +00:14:47.080 --> 00:14:50.400 +Now it's just a matter of creating two introduction + +00:14:50.400 --> 00:14:53.960 +sections, one for Debian, one for RedHat. + +00:14:53.960 --> 00:14:56.520 +And if you want the RedHat version of the document, + +00:14:56.520 --> 00:14:59.200 +you can just modify the `#+EXCLUDE_TAGS` line + +00:14:59.200 --> 00:15:00.440 +at the top of the document. + +00:15:00.440 --> 00:15:02.339 +Awesome, right? + +00:15:02.340 --> 00:15:03.539 +Right? + +00:15:03.540 --> 00:15:05.544 +OK, this is not that great. + +00:15:05.545 --> 00:15:07.387 +Well, it does work. + +00:15:07.388 --> 00:15:10.081 +And you can see if we export the document, + +00:15:10.082 --> 00:15:12.840 +we'll get something that only references Debian, + +00:15:12.840 --> 00:15:15.188 +and the `:noexport:` and `:redhat:` + +00:15:15.189 --> 00:15:17.450 +tagged headlines are omitted. + +00:15:17.451 --> 00:15:19.319 +This strategy would work great + +00:15:19.320 --> 00:15:22.120 +when the RedHat- and Debian-specific sections + +00:15:22.120 --> 00:15:24.400 +are substantially different, but that's not + +00:15:24.400 --> 00:15:26.198 +the case with the introduction. + +00:15:26.199 --> 00:15:28.640 +We definitely don't want to have to maintain + +00:15:28.640 --> 00:15:30.824 +two distinct introductions. + +00:15:30.825 --> 00:15:34.080 +I also noticed that the export tags are included + +00:15:34.080 --> 00:15:36.519 +in the exported document. + +00:15:36.520 --> 00:15:38.720 +That's a terrible default. We'll fix that, + +00:15:38.720 --> 00:15:42.040 +and we'll also ensure that my email address appears + +00:15:42.040 --> 00:15:43.371 +at the top of the document. + +00:15:43.372 --> 00:15:45.440 +Let's also take this opportunity to get rid + +00:15:45.440 --> 00:15:47.354 +of the table of contents. + +00:15:47.355 --> 00:15:48.867 +We don't need it. + +00:15:48.868 --> 00:15:51.120 +These are all export option settings + +00:15:51.120 --> 00:15:53.800 +and can be modified using the options keyword + +00:15:53.800 --> 00:15:55.508 +at the top of the doc. + +00:15:55.509 --> 00:15:57.480 +The manual is really your friend here, + +00:15:57.480 --> 00:16:00.979 +as there are a ton of export options. + +00:16:00.980 --> 00:16:03.120 +Now when we export the document again, + +00:16:03.120 --> 00:16:05.699 +it should look a lot better. + +NOTE Substituting constants + +00:16:05.700 --> 00:16:09.059 +Now that we've cleaned up the look of the exported document, + +00:16:09.060 --> 00:16:10.640 +we'll take a look at a better way + +00:16:10.640 --> 00:16:13.377 +of solving the problem with the introduction. + +00:16:13.378 --> 00:16:15.518 +Thinking like a programmer for a moment, + +00:16:15.519 --> 00:16:19.734 +what I really want here is a way of specifying a constant. + +00:16:19.735 --> 00:16:22.640 +Rather than hard-coding the name "Debian" or "RedHat" + +00:16:22.640 --> 00:16:24.569 +or whatever into my document, + +00:16:24.570 --> 00:16:28.234 +I want to substitute that text with a symbolic constant, + +00:16:28.235 --> 00:16:31.960 +named something like "distro", that can dynamically change + +00:16:31.960 --> 00:16:36.120 +to "Debian" or "RedHat" or "Slackware" or whatever, + +00:16:36.120 --> 00:16:38.689 +depending on how the document is configured. + +00:16:38.690 --> 00:16:41.640 +In the past, I've come up with some pretty cumbersome ways + +00:16:41.640 --> 00:16:44.640 +of doing this, but eventually I stumbled upon the idea + +00:16:44.640 --> 00:16:46.639 +of using Org-mode properties + +00:16:46.640 --> 00:16:49.409 +as a way of storing these constants. + +00:16:49.410 --> 00:16:53.059 +Like it says in the docs, properties are key-value pairs + +00:16:53.060 --> 00:16:55.169 +that are associated with an entry + +00:16:55.170 --> 00:16:58.379 +and they live in a collapsible properties drawer. + +00:16:58.380 --> 00:17:00.699 +Let's do a bit of cleanup on our document + +00:17:00.700 --> 00:17:02.600 +and we'll put things into sections. + +00:17:02.600 --> 00:17:14.000 +We'll also add a section for document constants. + +00:17:14.000 --> 00:17:19.560 +And that's where we'll put the properties drawer + +00:17:19.560 --> 00:17:25.739 +with the "distro" property. + +NOTE Getting the properties + +00:17:25.740 --> 00:17:27.120 +Now the question is, + +00:17:27.120 --> 00:17:30.099 +how do we reference these properties in the document? + +00:17:30.100 --> 00:17:32.520 +It turns out there's an Elisp function + +00:17:32.520 --> 00:17:35.440 +called `org-property-values`, which does what we want. + +00:17:35.440 --> 00:17:38.840 +If we run it and give it the name of our property, + +00:17:38.840 --> 00:17:42.679 +it returns a list with the string "Debian" in it. + +00:17:42.680 --> 00:17:45.919 +It's worth noting that this function is named + +00:17:45.920 --> 00:17:49.989 +`org-property-values` with values being plural. + +00:17:49.990 --> 00:17:52.889 +In org-mode, there could be a property named "foo" + +00:17:52.890 --> 00:17:55.880 +that has different values depending on which heading level + +00:17:55.880 --> 00:17:57.609 +you're at in the document, + +00:17:57.610 --> 00:17:59.720 +which is why the function returns a list. + +00:17:59.720 --> 00:18:01.289 +For our purposes though, + +00:18:01.290 --> 00:18:04.480 +we can just pull off the first value in the list with car + +00:18:04.480 --> 00:18:05.680 +and we're good to go. + +00:18:05.680 --> 00:18:10.040 +Now we'll make an Emacs Lisp list function called `get_prop` + +00:18:10.040 --> 00:18:11.440 +that does just that. + +00:18:11.440 --> 00:18:14.160 +This function takes one argument called `prop`, + +00:18:14.160 --> 00:18:15.920 +which is the property to look up + +00:18:15.920 --> 00:18:18.519 +and we'll give it a default value of "distro". + +00:18:18.520 --> 00:18:20.960 +So we can hit `C-c C-c` on the block + +00:18:20.960 --> 00:18:23.149 +to verify that it works. + +00:18:23.150 --> 00:18:25.480 +Now we just have to make an inline call + +00:18:25.480 --> 00:18:26.920 +to our `get_prop` function + +00:18:26.920 --> 00:18:29.559 +within the prose of the introduction section. + +00:18:29.560 --> 00:18:31.659 +And that should get us much closer + +00:18:31.660 --> 00:18:35.619 +to not hard coding distro names into our document. + +00:18:35.620 --> 00:18:36.869 +But before we do that, + +00:18:36.870 --> 00:18:39.849 +I need to clean up something that's been bothering me. + +00:18:39.850 --> 00:18:42.909 +By default, Emacs' `fill-column` variable + +00:18:42.910 --> 00:18:44.989 +is set to 70 characters, + +00:18:44.990 --> 00:18:47.720 +which may have been appropriate for 1970, + +00:18:47.720 --> 00:18:51.319 +but it's not great for 2023. + +00:18:51.320 --> 00:18:53.920 +We'll just cruise up to our startup block + +00:18:53.920 --> 00:18:56.539 +and set the variable there. + +00:18:56.540 --> 00:18:58.800 +We'll hit `C-c C-c`, + +00:18:58.800 --> 00:19:02.289 +and now our document will wrap at 100 columns, + +00:19:02.290 --> 00:19:05.829 +which for our purposes, I think is much more reasonable. + +00:19:05.830 --> 00:19:09.320 +The org-mode syntax for making an inline function call + +00:19:09.320 --> 00:19:13.059 +within the prose of your document is `call_`, + +00:19:13.060 --> 00:19:15.000 +followed by the name of the function, + +00:19:15.000 --> 00:19:17.040 +some optional header arguments, + +00:19:17.040 --> 00:19:19.719 +and then the function arguments. + +00:19:19.720 --> 00:19:21.680 +Now, when we export the document, + +00:19:21.680 --> 00:19:26.049 +we see that it's replaced our previously hard coded "Debian" + +00:19:26.050 --> 00:19:29.409 +with the value from the property. Huzzah! + +00:19:29.410 --> 00:19:32.959 +Now this is close to, but not exactly what we want. + +00:19:32.960 --> 00:19:36.720 +You can see that "Debian" is surrounded by a backtick + +00:19:36.720 --> 00:19:37.800 +and a single quote, + +00:19:37.800 --> 00:19:40.320 +which is the plain text exporters way + +00:19:40.320 --> 00:19:43.029 +of showing you verbatim text. + +00:19:43.030 --> 00:19:45.600 +In more sophisticated document backends, + +00:19:45.600 --> 00:19:49.379 +verbatim text is rendered in monospace. + +00:19:49.380 --> 00:19:54.080 +We can fix that by adding a ":results raw" header argument + +00:19:54.080 --> 00:19:56.459 +to the inline call. + +00:19:56.460 --> 00:19:58.239 +Now, when we export the document, + +00:19:58.240 --> 00:20:00.289 +it looks like what we'd expect. + +00:20:00.290 --> 00:20:02.960 +Now this is getting better, but it's still not great. + +NOTE Macros + +00:20:03.060 --> 00:20:05.840 +The `call_` syntax is pretty cumbersome, + +00:20:05.840 --> 00:20:08.560 +and it's a lot to type every time we want + +00:20:08.560 --> 00:20:09.849 +to reference a constant + +00:20:09.850 --> 00:20:13.219 +and not have it be marked up as verbatim. + +00:20:13.220 --> 00:20:17.169 +This is where org-mode macros come to our rescue. + +00:20:17.170 --> 00:20:19.469 +If we head to the top of the document, + +00:20:19.470 --> 00:20:21.480 +we can create a couple of macros + +00:20:21.480 --> 00:20:24.699 +using the `#+MACRO:` export keyword. + +00:20:24.700 --> 00:20:27.600 +We'll define two macros with short names. + +00:20:27.600 --> 00:20:30.240 +One named "p" for "property", + +00:20:30.240 --> 00:20:34.640 +and the other one named "pr" for "property raw". + +00:20:34.640 --> 00:20:39.160 +Org-mode macros are expanded when the document is exported, + +00:20:39.160 --> 00:20:41.640 +and any positional arguments provided + +00:20:41.640 --> 00:20:43.559 +are referenced by their number. + +00:20:43.860 --> 00:20:45.160 +Now in the introduction, + +00:20:45.160 --> 00:20:47.880 +we can use the macro replacement syntax, + +00:20:47.880 --> 00:20:49.800 +which is three curly braces, + +00:20:49.800 --> 00:20:52.760 +followed by the macro name and any arguments, + +00:20:52.760 --> 00:20:55.559 +and then three ending curly braces. + +00:20:55.560 --> 00:20:58.699 +You see why I kept the macro name short. + +00:20:58.700 --> 00:21:01.280 +That's six curly braces in total we're typing, + +00:21:01.280 --> 00:21:05.239 +which still takes up a fair amount of space. + +NOTE Properties in practice + +00:21:05.240 --> 00:21:07.120 +Now let's take a look at how we might use + +00:21:07.120 --> 00:21:09.159 +these properties in practice. + +00:21:09.160 --> 00:21:10.920 +Debian and RedHat distros differ + +00:21:11.120 --> 00:21:12.929 +on how they install packages. + +00:21:12.930 --> 00:21:16.120 +So we're gonna want an "install" property, + +00:21:16.120 --> 00:21:24.579 +where in Debian we use `sudo apt-get install -qq`, + +00:21:24.580 --> 00:21:26.939 +and on RedHat we'll use something like + +00:21:26.940 --> 00:21:33.119 +`sudo dnf install -y`. + +00:21:33.120 --> 00:21:35.329 +Now development packages + +00:21:35.330 --> 00:21:38.049 +also have a different naming convention. + +00:21:38.050 --> 00:21:40.760 +For example, the `ncurses` library on Debian + +00:21:40.760 --> 00:21:43.520 +is called `libncurses-dev`, + +00:21:43.520 --> 00:21:48.259 +where on RedHat it's called `ncurses-devel`. + +00:21:48.260 --> 00:21:49.640 +There are likely going to be + +00:21:49.640 --> 00:21:52.120 +many more little differences like this + +00:21:52.120 --> 00:21:55.339 +that we'll need to solve with properties. + +00:21:55.340 --> 00:21:58.609 +Now I already don't like where this is going. + +00:21:58.610 --> 00:22:00.880 +Switching between the Debian and RedHat + +00:22:00.880 --> 00:22:03.160 +versions of the document is gonna mean + +00:22:03.160 --> 00:22:05.200 +commenting and uncommenting out + +00:22:05.200 --> 00:22:06.989 +a bunch of different properties, + +00:22:06.990 --> 00:22:09.019 +which is pretty janky. + +NOTE Using a prefix + +00:22:09.020 --> 00:22:11.079 +Luckily we can solve this problem + +00:22:11.080 --> 00:22:14.439 +with a little bit of Emacs Lisp. + +00:22:14.440 --> 00:22:16.879 +We'll start by modifying our properties, + +00:22:16.880 --> 00:22:19.140 +so their property names are prefixed + +00:22:19.141 --> 00:22:23.119 +with either `deb_` or `rh_` + +00:22:23.120 --> 00:22:27.719 +to signify which distro the property applies to.` + +00:22:27.720 --> 00:22:31.160 +We'll also create a single property called "prefix", + +00:22:31.160 --> 00:22:34.589 +which will be prepended to the property name + +00:22:34.590 --> 00:22:36.529 +by the `get_prop` function + +00:22:36.530 --> 00:22:39.509 +if the requested property is not found. + +00:22:39.510 --> 00:22:42.200 +This way, when we want to switch between + +00:22:42.200 --> 00:22:45.349 +the Debian and RedHat versions of the document, + +00:22:45.350 --> 00:22:49.029 +we just need to change the prefix property. + +00:22:49.030 --> 00:22:51.379 +So now we'll change the Elisp code. + +00:22:51.380 --> 00:22:55.209 +So we'll use a let expression with two bound variables. + +00:22:55.210 --> 00:22:56.919 +The first one is called ret, + +00:22:56.920 --> 00:22:59.160 +which determines if the initial call + +00:22:59.160 --> 00:23:01.949 +to `org-property-values` succeeds. + +00:23:01.950 --> 00:23:04.039 +The second variable is called prefix, + +00:23:04.040 --> 00:23:06.219 +which is the prefix property. + +00:23:06.220 --> 00:23:09.120 +If the first call to `org-property-values` succeeds, + +00:23:09.120 --> 00:23:11.159 +we return it as normal. + +00:23:11.160 --> 00:23:14.249 +If not, we concatenate the property value + +00:23:14.250 --> 00:23:15.920 +that was passed into the function + +00:23:15.920 --> 00:23:18.969 +onto the prefix and try again. + +00:23:18.970 --> 00:23:23.800 +Now when we call the `get_prop` function with "distro" + +00:23:23.800 --> 00:23:26.360 +as the prop argument, it won't be found. + +00:23:26.360 --> 00:23:29.689 +So the code will slap our prefix tag on the front, + +00:23:29.690 --> 00:23:33.249 +making it something like `rh_distro`, + +00:23:33.250 --> 00:23:35.329 +and it will be found and returned. + +00:23:35.330 --> 00:23:39.999 +Let's see that in action. + +00:23:40.000 --> 00:23:42.009 +All right, now we're talking. + +NOTE Switching distributions + +00:23:42.010 --> 00:23:44.419 +This setup is starting to look pretty good, + +00:23:44.420 --> 00:23:46.040 +but there are just a few things + +00:23:46.040 --> 00:23:48.659 +that I want to add before we move on. + +00:23:48.660 --> 00:23:51.240 +First of all, I think the document should have a subtitle, + +00:23:51.240 --> 00:23:53.960 +something that tells you if you're looking at the RedHat + +00:23:53.960 --> 00:23:56.160 +or the Debian version of the document. + +00:23:56.160 --> 00:23:57.880 +I also think it would be great + +00:23:57.880 --> 00:24:00.520 +if the file name of the exported document + +00:24:00.520 --> 00:24:04.999 +reflected the distribution as well. + +00:24:05.000 --> 00:24:08.040 +I also want to add a quick Debian only section + +00:24:08.040 --> 00:24:11.799 +to the document that explains how it got its name. + +00:24:11.800 --> 00:24:17.739 +Now let's see what happens when we export the document. + +00:24:17.740 --> 00:24:20.439 +This did not work out as we wanted. + +00:24:20.440 --> 00:24:23.360 +As you can see, the macro we used in the subtitles + +00:24:23.360 --> 00:24:24.959 +didn't expand properly, + +00:24:24.960 --> 00:24:28.640 +and as a result, our subtitle didn't render right. + +00:24:28.640 --> 00:24:30.640 +Sadly, you can't use macros + +00:24:30.640 --> 00:24:32.909 +or inline function calls everywhere. + +00:24:32.910 --> 00:24:34.680 +And one place where they don't work + +00:24:34.680 --> 00:24:37.189 +is inside of certain export keywords. + +00:24:37.190 --> 00:24:43.219 +So we're gonna have to hard code them here. + +00:24:43.220 --> 00:24:46.320 +Another mistake that we made is we forgot to update + +00:24:46.320 --> 00:24:49.099 +the `#+EXCLUDE_TAGS` export keyword, + +00:24:49.100 --> 00:24:51.439 +because with the RedHat version of the document, + +00:24:51.440 --> 00:24:54.509 +we want to exclude the Debian tag. + +00:24:54.510 --> 00:24:56.400 +Now when we export the document, + +00:24:56.400 --> 00:24:57.839 +everything should be correct. + +00:24:57.840 --> 00:25:00.619 +The word RedHat should appear in the subtitle, + +00:25:00.620 --> 00:25:04.799 +and the Debian fun fact section should not be present. + +00:25:04.800 --> 00:25:06.960 +Now we just need to add a section to the README + +00:25:06.960 --> 00:25:09.280 +that explains the steps you need to take + +00:25:09.280 --> 00:25:11.000 +in order to switch the document + +00:25:11.000 --> 00:25:12.759 +from RedHat to Debian. + +00:25:12.760 --> 00:25:14.000 +Okay, let's see here. + +00:25:14.000 --> 00:25:18.309 +We have to change `#+SUBTITLE`, change the `#+EXCLUDE_TAGS`, + +00:25:18.310 --> 00:25:20.429 +change the `#+EXPORT_FILE_NAME`, + +00:25:20.430 --> 00:25:23.289 +and change the `prefix` property. + +00:25:23.290 --> 00:25:26.289 +This is OK, but it's not great. + +00:25:26.290 --> 00:25:29.429 +Emacs Lisp can once again come to our rescue. + +00:25:29.430 --> 00:25:32.080 +What we'll do is make an Elisp code block + +00:25:32.080 --> 00:25:35.480 +that will invite the user to hit `C-c C-c` on. + +00:25:35.480 --> 00:25:39.520 +And the code block will essentially make all these changes + +00:25:39.520 --> 00:25:40.919 +in the document for them. + +00:25:40.920 --> 00:25:43.280 +This code block, which we'll call `switch_distro`, + +00:25:43.280 --> 00:25:45.680 +takes one argument called `os`, + +00:25:45.680 --> 00:25:48.689 +which by default is set to "Debian". + +00:25:48.690 --> 00:25:50.760 +It starts out with a let expression + +00:25:50.760 --> 00:25:53.029 +that defines three bound variables. + +00:25:53.030 --> 00:25:55.969 +The `debian` variable is a boolean that is true + +00:25:55.970 --> 00:25:58.699 +if the distro we're switching to is Debian. + +00:25:58.700 --> 00:26:00.360 +Based on the value of this boolean, + +00:26:00.360 --> 00:26:04.169 +we'll set the `noexport` and `prefix` variables accordingly. + +00:26:04.170 --> 00:26:06.720 +The `save-excursion` block tells Emacs + +00:26:06.720 --> 00:26:09.199 +that we're going to be moving around in the document + +00:26:09.200 --> 00:26:11.680 +and to remember to put our point back where we started + +00:26:11.680 --> 00:26:13.429 +when the block finishes. + +00:26:13.430 --> 00:26:16.249 +After that, we essentially go to the top of the document + +00:26:16.250 --> 00:26:19.839 +and search and replace the subtitle, `exclude_tags`, + +00:26:19.840 --> 00:26:22.499 +`export_file_name`, and the `prefix`. + +00:26:22.500 --> 00:26:23.389 +Pretty cool. + +00:26:23.390 --> 00:26:25.029 +Let's see this in action. + +00:26:25.030 --> 00:26:27.869 +If we hit `C-c C-c` on this block, + +00:26:27.870 --> 00:26:30.480 +we should see the document automatically change a bit. + +00:26:30.480 --> 00:26:32.320 +And now when we export it, + +00:26:32.320 --> 00:26:36.089 +we get the Debian version of the doc. + +00:26:36.090 --> 00:26:37.629 +If we want to change it back, + +00:26:37.630 --> 00:26:39.880 +we can just head back over to the code block + +00:26:39.880 --> 00:26:43.149 +and change the default value for the os variable + +00:26:43.150 --> 00:26:47.619 +from "Debian" to "RedHat" and hit `C-c C-c` again. + +00:26:47.620 --> 00:26:49.919 +And now when we re-export, + +00:26:49.920 --> 00:26:52.909 +we're looking at the RedHat version of the document. + +00:26:52.910 --> 00:26:55.859 +Just as an aside, if you ever thought to yourself, + +00:26:55.860 --> 00:26:58.159 +"I should learn Emacs Lisp someday" + +00:26:58.160 --> 00:27:01.289 +Make it someday soon. You'll be happy you did. + +00:27:01.290 --> 00:27:03.769 +Not only is it a fun programming language, + +00:27:03.770 --> 00:27:06.679 +but you can do powerful things with it in Emacs, + +00:27:06.680 --> 00:27:12.149 +which I hope is a point that folks take away from this talk. + +00:27:12.150 --> 00:27:14.149 +All right, that was a lot. + +NOTE A tour + +00:27:14.150 --> 00:27:16.840 +Now that we've spent the past 20 minutes or so + +00:27:16.840 --> 00:27:19.409 +digging into some of the tips and tricks I used + +00:27:19.410 --> 00:27:22.879 +when creating my build Emacs from source document, + +00:27:22.880 --> 00:27:26.279 +we'll say goodbye to this document we've been working on + +00:27:26.280 --> 00:27:27.480 +and we'll start a tour + +00:27:27.480 --> 00:27:29.960 +of the actual literate document I wrote. + +00:27:29.960 --> 00:27:33.080 +A document that I'll demonstrate actually downloading + +00:27:33.080 --> 00:27:35.659 +and building a new Emacs when I export it + +00:27:35.660 --> 00:27:38.959 +on both my Ubuntu and RedHat virtual machines. + +00:27:38.960 --> 00:27:41.689 +I'll also show you how org-mode can generate + +00:27:41.690 --> 00:27:44.519 +slick professional looking PDF files + +00:27:44.520 --> 00:27:46.579 +through the power of LaTeX. + +00:27:46.580 --> 00:27:49.619 +We'll start here at the orgdemo2 directory, + +00:27:49.620 --> 00:27:51.229 +which I've cloned from GitLab. + +00:27:51.230 --> 00:27:55.599 +This repository has all the source materials for this talk. + +00:27:55.600 --> 00:27:59.040 +The buildemacs.org file is where most of the good stuff is. + +00:27:59.040 --> 00:28:01.479 +So that's where we'll start. + +00:28:01.480 --> 00:28:03.360 +There's a lot of file-local variables + +00:28:03.360 --> 00:28:04.800 +that we'll need to confirm. + +00:28:04.800 --> 00:28:06.439 +So we'll do that too. + +00:28:06.440 --> 00:28:07.560 +So the first thing we're gonna do + +00:28:07.560 --> 00:28:10.080 +is hit `C-u TAB` twice, + +00:28:10.780 --> 00:28:13.360 +which will give us a top-level overview + +00:28:13.360 --> 00:28:15.139 +of all of our headings. + +00:28:15.140 --> 00:28:16.600 +As you can see, we've got a lot + +00:28:16.600 --> 00:28:20.119 +of the same familiar export keywords we had before. + +00:28:20.120 --> 00:28:23.099 +`#+TITLE`, `#+SUBTITLE`, `#+AUTHOR`, `#+EMAIL`, + +00:28:23.100 --> 00:28:25.359 +plus a few we haven't seen before. + +00:28:25.360 --> 00:28:27.720 +For example, I've squirreled away + +00:28:27.720 --> 00:28:30.619 +a lot of the `#+LATEX_HEADER` export keywords + +00:28:30.620 --> 00:28:33.539 +in this file called latex.setup. + +00:28:33.540 --> 00:28:36.539 +And I did this just so they don't clutter up the document. + +00:28:36.540 --> 00:28:38.320 +Much of the LaTeX magic + +00:28:38.320 --> 00:28:40.909 +that makes the exported document look good + +00:28:40.910 --> 00:28:42.589 +is in these headers. + +00:28:42.590 --> 00:28:45.119 +LaTeX commands begin with a backslash. + +00:28:45.120 --> 00:28:49.679 +And a common one we use a lot here is `\usepackage`. + +00:28:49.680 --> 00:28:52.200 +This lets us bring in packages like geometry, + +00:28:52.200 --> 00:28:56.539 +svg for the cool SeaGL SVG logo, + +00:28:56.540 --> 00:28:58.440 +`fancyhdr` and fancy verbatim [`fancyvrb`] + +00:28:58.440 --> 00:29:00.689 +to keep things looking pretty fancy. + +00:29:00.690 --> 00:29:03.200 +Using a scalable vector image format + +00:29:03.200 --> 00:29:05.720 +makes it possible for us to do really cool things + +00:29:05.720 --> 00:29:09.269 +like having a scaled-down version of the SeaGL logo + +00:29:09.270 --> 00:29:11.979 +appear in the fancy footer below. + +00:29:11.980 --> 00:29:15.360 +I also include some macros in a separate file + +00:29:15.360 --> 00:29:18.120 +just to help keep things tidy in the main document. + +00:29:18.120 --> 00:29:20.600 +Here I've got the familiar macros + +00:29:20.600 --> 00:29:23.399 +we've seen before for `get_prop`. + +00:29:23.400 --> 00:29:25.520 +But here I use different permutations + +00:29:25.520 --> 00:29:28.160 +depending on if I want results raw + +00:29:28.160 --> 00:29:31.869 +or raw verbatim or just verbatim. + +00:29:31.870 --> 00:29:35.069 +I also have a couple of macros here at the top of the file + +00:29:35.070 --> 00:29:40.280 +that are for pulling strings out of results blocks + +00:29:40.280 --> 00:29:41.920 +and then trimming them + +00:29:41.920 --> 00:29:44.719 +so there's no white space on either side. + +00:29:44.720 --> 00:29:46.440 +Like in the version of the document + +00:29:46.440 --> 00:29:48.429 +we worked on at the start of this talk, + +00:29:48.430 --> 00:29:51.079 +the real document also has a README section + +00:29:51.080 --> 00:29:53.469 +marked with the `:noexport:` tag. + +00:29:53.470 --> 00:29:55.400 +It also has a section about choosing + +00:29:55.400 --> 00:29:57.909 +which version of the document to export + +00:29:57.910 --> 00:30:00.599 +and a code block on how to switch between them. + +00:30:00.600 --> 00:30:03.000 +It's also got a lot of helpful information in it + +00:30:03.000 --> 00:30:05.819 +like what OS and Emacs versions + +00:30:05.820 --> 00:30:09.559 +the document has been tested to "run" on, + +00:30:09.560 --> 00:30:12.329 +a section on the LaTeX prerequisites + +00:30:12.330 --> 00:30:14.080 +and the section on executing + +00:30:14.080 --> 00:30:16.199 +the document's various code blocks. + +NOTE TeX and LaTeX + +00:30:16.200 --> 00:30:19.199 +The latter two sections we'll take a look at now. + +00:30:19.200 --> 00:30:22.579 +Out of the box on Fedora and Ubuntu server distros, + +00:30:22.580 --> 00:30:24.709 +the TeX typesetting system + +00:30:24.710 --> 00:30:27.669 +also by noted computer scientist Donald Knuth + +00:30:27.670 --> 00:30:28.859 +is not installed. + +00:30:28.860 --> 00:30:31.719 +So we'll need to install some packages. + +00:30:31.720 --> 00:30:34.449 +Starting out we'll need the `texlive` package + +00:30:34.450 --> 00:30:37.459 +which gets you a fully featured TeX setup. + +00:30:37.460 --> 00:30:39.289 +This also gets you LaTeX + +00:30:39.290 --> 00:30:42.789 +which can be viewed as a distribution of TeX macros. + +00:30:42.790 --> 00:30:44.899 +You'll also need XeTeX. + +00:30:44.900 --> 00:30:49.779 +This gets you Unicode support and lets you use modern fonts. + +00:30:49.780 --> 00:30:52.809 +We'll also want to install pdfTeX. + +00:30:52.810 --> 00:30:57.209 +This gets us the ability to generate PDFs from TeX sources. + +00:30:57.210 --> 00:31:01.299 +And finally, we're gonna need to install latexmk + +00:31:01.300 --> 00:31:02.400 +which is a Perl script + +00:31:02.400 --> 00:31:05.139 +that knows how to run LaTeX multiple times + +00:31:05.140 --> 00:31:09.249 +in order to properly deal with intra-document links. + +NOTE Other prerequisites + +00:31:09.250 --> 00:31:11.069 +But wait, there's more. + +00:31:11.070 --> 00:31:12.960 +We're also gonna need Inkscape + +00:31:12.960 --> 00:31:15.520 +to rasterize our SeaGL vector logo + +00:31:15.520 --> 00:31:17.339 +at different resolutions. + +00:31:17.340 --> 00:31:20.360 +And we're gonna need the JetBrains Mono font + +00:31:20.360 --> 00:31:23.059 +to make our source code look snazzy. + +00:31:23.060 --> 00:31:24.680 +We'll also need the Inter font + +00:31:24.680 --> 00:31:28.039 +to make our prose look snazzy as well. + +00:31:28.040 --> 00:31:31.299 +I've helpfully added a bash code block in the README + +00:31:31.300 --> 00:31:35.739 +that you can hit C-c C-c on to install. + +00:31:35.740 --> 00:31:38.520 +This really does lock up Emacs for a few minutes + +00:31:38.520 --> 00:31:40.329 +and it's sort of annoying. + +00:31:40.330 --> 00:31:43.040 +When we export the document and turn off all caching + +00:31:43.040 --> 00:31:45.599 +and it actually builds Emacs for real, + +00:31:45.600 --> 00:31:48.769 +Emacs can be locked up for tens of minutes. + +00:31:48.770 --> 00:31:50.880 +There's a package called ob-async + +00:31:50.880 --> 00:31:54.259 +that I've been meaning to check out that might help here. + +00:31:54.260 --> 00:31:55.760 +But since I wanted this document + +00:31:55.760 --> 00:31:58.000 +to work on bog-standard Emacs setups, + +00:31:58.000 --> 00:32:00.059 +I didn't get around to it. + +NOTE Caching + +00:32:00.060 --> 00:32:03.139 +Before we get into talking about running the document, + +00:32:03.140 --> 00:32:06.449 +let's talk briefly about results caching. + +00:32:06.450 --> 00:32:08.839 +We'll take a look at the section of the document + +00:32:08.840 --> 00:32:13.139 +where we talk about Git tags for an example. + +00:32:13.140 --> 00:32:15.760 +The `num_tags` bash code block determines + +00:32:15.760 --> 00:32:19.039 +how many tags there are in the Emacs Git repo. + +00:32:19.040 --> 00:32:21.600 +And when I hit C-c C-c on that block + +00:32:21.600 --> 00:32:25.059 +several days ago, when I was first creating the document, + +00:32:25.060 --> 00:32:28.019 +that number was 183. + +00:32:28.020 --> 00:32:32.169 +That result has remained cached in the document since then. + +00:32:32.170 --> 00:32:34.899 +And you can see a snippet of the SHA1 hash + +00:32:34.900 --> 00:32:38.389 +of the contents of the source block below. + +00:32:38.390 --> 00:32:40.800 +You can see where I referenced the result + +00:32:40.800 --> 00:32:44.960 +using the `sr` for string raw macro in the prose below, + +00:32:44.960 --> 00:32:50.509 +and how it gets rendered in the exported PDF document. + +00:32:50.510 --> 00:32:52.880 +All the source blocks in the exported sections + +00:32:52.880 --> 00:32:56.559 +of the document include cached results like this. + +00:32:56.560 --> 00:33:01.389 +If I export the document now, it won't take that long to do + +00:33:01.390 --> 00:33:03.800 +because while there are a ton of code blocks + +00:33:03.800 --> 00:33:09.069 +in the exported sections, they're all cached. + +00:33:09.070 --> 00:33:11.560 +Now let's get back to the section of the README + +00:33:11.560 --> 00:33:14.909 +that explains how to execute the code in the document. + +00:33:14.910 --> 00:33:17.640 +Here I explain that if you want to build Emacs + +00:33:17.640 --> 00:33:20.189 +on your computer using this document, + +00:33:20.190 --> 00:33:22.019 +you've got a couple of options. + +00:33:22.020 --> 00:33:25.649 +The first option is to manually invalidate the caches + +00:33:25.650 --> 00:33:28.960 +and take C-c C-c on every code block + +00:33:28.960 --> 00:33:30.959 +in the main document. + +00:33:30.960 --> 00:33:33.160 +This lets you supervise the entire process, + +00:33:33.160 --> 00:33:36.939 +and it also creates new cached result blocks, + +00:33:36.940 --> 00:33:39.239 +but it's time consuming. + +00:33:39.240 --> 00:33:43.440 +There is also an internal link to the main document here, + +00:33:43.440 --> 00:33:47.379 +and you can jump to it with C-c C-o. + +00:33:47.380 --> 00:33:50.040 +This is one of those intra-document links + +00:33:50.040 --> 00:33:52.999 +that is really tricky to get right with LaTeX, + +00:33:53.000 --> 00:33:56.989 +and is why we opted to use the latexmk Perl script + +00:33:56.990 --> 00:34:00.049 +to build the PDF version of the document. + +00:34:00.050 --> 00:34:01.920 +I'm mentioning it specifically here + +00:34:01.920 --> 00:34:05.629 +because it took me forever to figure this out. + +00:34:05.630 --> 00:34:07.269 +The second option you've got + +00:34:07.270 --> 00:34:09.280 +is to change the default header arg + +00:34:09.280 --> 00:34:13.739 +from `:cache yes` to `:cache no` at the top of the document. + +00:34:13.740 --> 00:34:16.269 +If we cruise up to the top of the document, + +00:34:16.270 --> 00:34:19.129 +you can see that this header argument property + +00:34:19.130 --> 00:34:22.440 +basically says that unless a code block + +00:34:22.440 --> 00:34:24.160 +explicitly says otherwise, + +00:34:24.160 --> 00:34:27.118 +it's by default supposed to be cached. + +00:34:27.119 --> 00:34:29.440 +That's how we were able to export the document + +00:34:29.440 --> 00:34:31.558 +before so quickly. + +00:34:31.559 --> 00:34:34.819 +The code block named `no_cache_no_confirm` + +00:34:34.820 --> 00:34:38.618 +uses the `save-excursion` and regex replace trick + +00:34:38.619 --> 00:34:40.348 +that I demonstrated earlier + +00:34:40.349 --> 00:34:42.819 +to munch the default cache header arg + +00:34:42.820 --> 00:34:45.409 +from "cache yes" to "cache no". + +00:34:45.410 --> 00:34:49.299 +And it also turns off confirmations on bash code blocks. + +00:34:49.300 --> 00:34:51.939 +Let's do that now. + +00:34:51.940 --> 00:34:54.559 +Now we'll export the document to PDF, + +00:34:54.560 --> 00:34:57.439 +which will ignore the cache result blocks + +00:34:57.440 --> 00:35:00.319 +and clone the Git repository on Savannah, + +00:35:00.320 --> 00:35:01.760 +create a branch that points + +00:35:01.760 --> 00:35:05.459 +to the most recently tagged version of Emacs 29, + +00:35:05.460 --> 00:35:07.759 +run configure a handful of times, + +00:35:07.760 --> 00:35:10.720 +installing packages to fix missing dependencies + +00:35:10.720 --> 00:35:12.399 +along the way, + +00:35:12.400 --> 00:35:16.099 +build Emacs, install Emacs in our home directory, + +00:35:16.100 --> 00:35:19.339 +verify that it has successfully built a binary, + +00:35:19.340 --> 00:35:22.549 +run it in batch mode with some sample Elisp + +00:35:22.550 --> 00:35:26.869 +and show the file sizes and dates of the generated files. + +00:35:26.870 --> 00:35:28.339 +This is gonna take a while. + +00:35:28.340 --> 00:35:32.829 +And while it's running, we'll pop over to our Fedora box. + +00:35:32.830 --> 00:35:34.680 +All right, now we'll fire up Emacs, + +00:35:34.680 --> 00:35:39.280 +hit `C-c C-c` on the `configure_document` code block + +00:35:39.280 --> 00:35:41.849 +to configure the document for RedHat + +00:35:41.850 --> 00:35:45.709 +since Fedora here is a RedHat based distro. + +00:35:45.710 --> 00:35:47.040 +Then what we'll do is we'll pop down + +00:35:47.040 --> 00:35:49.589 +and hit `C-c C-c` + +00:35:49.590 --> 00:35:53.699 +on the `rh_install_latex` code block + +00:35:53.700 --> 00:35:56.229 +to install the LaTeX prerequisites + +00:35:56.230 --> 00:35:58.459 +for this Fedora virtual machine. + +00:35:58.460 --> 00:36:02.589 +Finally, we'll execute the `no_cache_no_confirm` block + +00:36:02.590 --> 00:36:05.049 +and then kick off the export. + +00:36:05.050 --> 00:36:07.280 +Then we'll go and check back on what's happening + +00:36:07.280 --> 00:36:09.529 +on the Ubuntu box. + +00:36:09.530 --> 00:36:11.240 +Ooh, top looks pretty quiet. + +00:36:11.240 --> 00:36:14.039 +I think the export is complete. + +00:36:14.040 --> 00:36:17.559 +Ooh, those are the words I love to see in the status area, + +00:36:17.560 --> 00:36:20.609 +PDF file produced! + +NOTE Looking at the PDF + +00:36:20.610 --> 00:36:22.600 +Now I can't use my web browser + +00:36:22.600 --> 00:36:24.959 +to take a look at this PDF file + +00:36:24.960 --> 00:36:27.080 +because I haven't set up a web server + +00:36:27.080 --> 00:36:30.759 +or anything like that on the Ubuntu virtual machine. + +00:36:30.760 --> 00:36:34.439 +I can, however, use TRAMP with the ssh method + +00:36:34.440 --> 00:36:36.560 +to poke around on the ubuntu host + +00:36:36.560 --> 00:36:39.120 +on my personal version of Emacs. + +00:36:39.120 --> 00:36:40.939 +So let's do that. + +00:36:40.940 --> 00:36:44.809 +Okay, so now if we go into the source directory + +00:36:44.810 --> 00:36:48.039 +and then we hop into the orgdemo2 directory + +00:36:48.040 --> 00:36:51.619 +and then we look at the deb version of the PDF, + +00:36:51.620 --> 00:36:54.149 +there she blows. + +00:36:54.150 --> 00:36:58.160 +Now, if we go down to the Building Emacs section, + +00:36:58.160 --> 00:37:00.129 +we can see that it built. + +00:37:00.130 --> 00:37:03.839 +And if we look in the bin directory, + +00:37:03.840 --> 00:37:06.779 +we can see that at 17:01, + +00:37:06.780 --> 00:37:11.379 +that's when all of those files got created. + +00:37:11.380 --> 00:37:15.589 +Also the file creation date on the PDF is 17:01. + +00:37:15.590 --> 00:37:18.720 +So all of this code executed roughly the same time + +00:37:18.720 --> 00:37:21.159 +the PDF was created. + +00:37:21.160 --> 00:37:25.339 +All right, so now let's head back over to the Fedora box + +00:37:25.340 --> 00:37:27.920 +and then we'll navigate to the source directory, + +00:37:27.920 --> 00:37:30.119 +the orgdemo2 directory, + +00:37:30.120 --> 00:37:35.719 +and there is our RedHat version of the built Emacs PDF. + +00:37:35.720 --> 00:37:38.219 +And Bob's your uncle. + +00:37:38.220 --> 00:37:42.549 +And you can see it is the RedHat version of the document + +00:37:42.550 --> 00:37:44.939 +because this is a RedHat box. + +00:37:44.940 --> 00:37:51.639 +And if we go over to the What did we install? section, + +00:37:51.640 --> 00:37:56.049 +you can see that these binaries were built at 17:35. + +00:37:56.050 --> 00:37:58.699 +And now if we pop open dired + +00:37:58.700 --> 00:38:00.739 +and we take a look at the PDF, + +00:38:00.740 --> 00:38:07.329 +we can see it also was created at 17:35. + +00:38:07.330 --> 00:38:10.039 +All right, in the couple minutes remaining, + +00:38:10.040 --> 00:38:11.640 +I thought it would be a good idea + +00:38:11.640 --> 00:38:15.739 +just to take a look at the document + +00:38:15.740 --> 00:38:19.000 +and maybe just go through some of what it actually does + +00:38:19.000 --> 00:38:22.579 +in explaining how to build Emacs from source. + +00:38:22.580 --> 00:38:27.139 +We'll look at the RedHat version since we're here. + +00:38:27.140 --> 00:38:28.160 +And the first thing you do is + +00:38:28.160 --> 00:38:31.539 +you have to get access to the source code. + +00:38:31.540 --> 00:38:32.840 +And before you can do anything, + +00:38:32.840 --> 00:38:35.419 +this is a RedHat-specific section + +00:38:35.420 --> 00:38:38.299 +where you need to install some development tools. + +00:38:38.300 --> 00:38:41.539 +And this development tools group actually has Git. + +00:38:41.540 --> 00:38:44.640 +Now I installed Git earlier, but if you didn't do that, + +00:38:44.640 --> 00:38:46.939 +that would be the first thing that you need to do. + +00:38:46.940 --> 00:38:50.039 +We create a source directory, we cd into it, + +00:38:50.040 --> 00:38:53.059 +we clone the repo from Savannah. + +00:38:53.060 --> 00:38:56.059 +And then we start to take a look at some of the Git tags. + +00:38:56.060 --> 00:38:58.560 +And we showed this before where we check out + +00:38:58.560 --> 00:39:00.369 +how many different tags there are. + +00:39:00.370 --> 00:39:02.400 +And then we run this kind of funky Git command + +00:39:02.400 --> 00:39:06.040 +to sort of list all the tags that begin with 'emacs-29', + +00:39:06.040 --> 00:39:08.759 +and we sort them by when they were tagged. + +00:39:08.760 --> 00:39:12.400 +So we can see that Emacs 29.1.pretest + +00:39:12.400 --> 00:39:14.439 +is the most recent version. + +00:39:14.440 --> 00:39:15.880 +So that's the one we grab + +00:39:15.880 --> 00:39:18.659 +and that's the one we decide to build. + +00:39:18.660 --> 00:39:22.779 +And then we create a branch that is based on this tag. + +00:39:22.780 --> 00:39:27.479 +And this is dynamically generated based on what we saw here. + +00:39:27.480 --> 00:39:29.439 +So that's what we use here. + +NOTE Errors + +00:39:29.440 --> 00:39:32.920 +In this case, we're piping standard error + +00:39:32.920 --> 00:39:35.099 +to where standard out goes. + +00:39:35.100 --> 00:39:36.069 +That's another trick. + +00:39:36.070 --> 00:39:39.559 +If you want to actually see an error get created, + +00:39:39.560 --> 00:39:44.119 +org-mode will capture any errors that code blocks produce, + +00:39:44.120 --> 00:39:46.819 +and it will show you the error message in a buffer. + +00:39:46.820 --> 00:39:49.240 +So if you actually wanna show what it looks like + +00:39:49.240 --> 00:39:53.059 +when something errors out, this is the trick you have to use. + +00:39:53.060 --> 00:39:56.200 +And then what we do is we look for a configure script + +00:39:56.200 --> 00:39:57.419 +and there isn't one. + +00:39:57.420 --> 00:39:58.599 +And then we realize, + +00:39:58.600 --> 00:40:00.909 +uh-oh, we're gonna have to deal with autotools. + +00:40:00.910 --> 00:40:05.560 +So, you know, we run the autogen script and it complains + +00:40:05.560 --> 00:40:08.679 +because we're missing some prerequisites. + +00:40:08.680 --> 00:40:11.349 +So we have to install autoconf, + +00:40:11.350 --> 00:40:13.019 +and then we run it again, + +00:40:13.020 --> 00:40:15.959 +and finally it generates a configure script. + +00:40:15.960 --> 00:40:19.019 +And this is another case where I pull this number + +00:40:19.020 --> 00:40:21.979 +right here into the actual prose. + +00:40:21.980 --> 00:40:24.840 +And I can see it's, oh, it's, you know, this how many bytes. + +00:40:24.840 --> 00:40:26.800 +When was the last time you wrote a shell script + +00:40:26.800 --> 00:40:29.579 +that was this many bytes long? + +00:40:29.580 --> 00:40:31.320 +And then we configure the build process. + +00:40:31.320 --> 00:40:33.760 +And, you know, it's not gonna work right away + +00:40:33.760 --> 00:40:36.699 +because we don't have GNU Texinfo installed. + +00:40:36.700 --> 00:40:41.439 +So we gotta do that, which we do with `dnf install` here. + +00:40:41.440 --> 00:40:44.320 +And then there's this section that is either RedHat- + +00:40:44.320 --> 00:40:48.919 +or Debian-specific that talks about, like, + +00:40:48.920 --> 00:40:51.240 +if you don't know the name of a package + +00:40:51.240 --> 00:40:55.160 +that contains a given file name, how do you query it? + +00:40:55.160 --> 00:40:59.519 +And in the RedHat world, you use `dnf provides makeinfo`. + +00:40:59.520 --> 00:41:02.289 +In the Debian world, you do something entirely different. + +00:41:02.290 --> 00:41:06.639 +And then we have to install the `ncurses` binary. + +00:41:06.640 --> 00:41:10.299 +And finally we get like a minimal configuration + +00:41:10.300 --> 00:41:13.699 +and you can see that there's a whole bunch of nos here. + +00:41:13.700 --> 00:41:15.200 +So, you know, we don't have cairo, + +00:41:15.200 --> 00:41:18.799 +we don't have imagemagick, we don't have dbus, + +00:41:18.800 --> 00:41:20.600 +you know, there's a whole bunch of stuff we don't have. + +00:41:20.600 --> 00:41:23.880 +We don't have X, we don't have libjansson, no tree-sitter. + +00:41:23.880 --> 00:41:25.960 +This is really a bare-bones Emacs + +00:41:25.960 --> 00:41:28.639 +that is strictly terminal mode. + +00:41:28.640 --> 00:41:30.800 +Then we actually build Emacs, which is, you know, + +00:41:30.800 --> 00:41:33.259 +kind of boring, we're just gonna type make + +00:41:33.260 --> 00:41:35.259 +and then make is gonna run successfully. + +00:41:35.260 --> 00:41:37.880 +And make is gonna spew a ton of output, right? + +00:41:37.880 --> 00:41:41.099 +So here's where I do that /dev/null trick, + +00:41:41.100 --> 00:41:42.600 +where I pipe everything to /dev/null + +00:41:42.600 --> 00:41:45.819 +and then I, or I pipe standard output to /dev/null + +00:41:45.820 --> 00:41:47.520 +and then I pipe standard error + +00:41:47.520 --> 00:41:50.239 +to wherever standard output's going. + +00:41:50.240 --> 00:41:52.799 +And then at the end to say that it ran successfully, + +00:41:52.800 --> 00:41:55.379 +I say "Make ran successfully!" + +00:41:55.380 --> 00:41:57.799 +Then we take a look at the Emacs binary + +00:41:57.800 --> 00:41:59.879 +and you know, it's an elf binary. + +00:41:59.880 --> 00:42:01.720 +And, you know, because this is running on my Mac, + +00:42:01.720 --> 00:42:06.619 +this is an ARM-based machine, this virtual machine is. + +00:42:06.620 --> 00:42:10.519 +Oops, and this is a bug. + +00:42:10.520 --> 00:42:12.200 +This really should be a macro call, + +00:42:12.200 --> 00:42:14.800 +but I think I have the wrong number of curly braces + +00:42:14.800 --> 00:42:16.159 +or something in there. + +00:42:16.160 --> 00:42:19.129 +I need to figure out why that's not right. + +00:42:19.130 --> 00:42:21.109 +I'll look into that later. + +00:42:21.110 --> 00:42:23.979 +And then we install Emacs and then we kind of show + +00:42:23.980 --> 00:42:27.719 +like the file sizes of everything in the home directory. + +00:42:27.720 --> 00:42:31.989 +And then we, you know, show the binaries that got installed. + +NOTE Final thoughts + +00:42:31.990 --> 00:42:35.599 +Anyway, so this is the final thoughts section. + +00:42:35.600 --> 00:42:39.219 +And my final thoughts are, is I hope you enjoyed this talk + +00:42:39.220 --> 00:42:42.379 +and I hope you actually learned a thing or two. + +00:42:42.380 --> 00:42:43.360 +All right, thanks everybody. + +00:42:43.360 --> 00:42:45.200 +And I'll see you all next time. |