diff options
Diffstat (limited to '2023/info/doc-after.md')
| -rw-r--r-- | 2023/info/doc-after.md | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/2023/info/doc-after.md b/2023/info/doc-after.md index a9ce616a..9ac644ba 100644 --- a/2023/info/doc-after.md +++ b/2023/info/doc-after.md @@ -4,6 +4,9 @@ <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"]] @@ -23,6 +26,9 @@ [[!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"]] @@ -50,6 +56,9 @@ [[!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"]] @@ -99,6 +108,9 @@ [[!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"]] @@ -143,6 +155,9 @@ [[!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"]] @@ -154,6 +169,9 @@ [[!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"]] @@ -173,6 +191,9 @@ [[!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"]] @@ -184,6 +205,9 @@ [[!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"]] @@ -221,6 +245,9 @@ [[!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"]] @@ -295,6 +322,9 @@ [[!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"]] @@ -348,6 +378,9 @@ [[!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"]] @@ -371,6 +404,9 @@ [[!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 "distro" 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"]] @@ -429,6 +465,9 @@ [[!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"]] @@ -451,6 +490,9 @@ [[!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"]] @@ -473,6 +515,9 @@ [[!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"]] @@ -505,6 +550,9 @@ [[!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"]] @@ -583,6 +631,9 @@ [[!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"]] @@ -652,6 +703,9 @@ [[!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"]] @@ -670,6 +724,9 @@ [[!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"]] @@ -690,6 +747,9 @@ [[!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"]] @@ -777,6 +837,9 @@ [[!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"]] @@ -838,6 +901,9 @@ [[!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"]] @@ -903,6 +969,9 @@ [[!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"]] |