From a02885944e69a3f714814a2811ec02ffa8a11e74 Mon Sep 17 00:00:00 2001 From: Sacha Chua Date: Sat, 19 Dec 2020 01:08:04 -0500 Subject: Add subtitles for 13, 14, 15 --- ...onf-2020--14-readme-driven-design--adam-ard.vtt | 1297 ++++++++++++++++++++ 1 file changed, 1297 insertions(+) create mode 100644 2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt (limited to '2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt') diff --git a/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt new file mode 100644 index 00000000..608729bd --- /dev/null +++ b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt @@ -0,0 +1,1297 @@ +WEBVTT + +00:00:03.600 --> 00:00:04.400 +Adam: Hello! + +00:00:04.400 --> 00:00:06.560 +Welcome to Readme Driven Design in Emacs + +00:00:06.560 --> 00:00:08.400 +by Adam Aard. + +00:00:08.400 --> 00:00:10.800 +If you're a programmer, you're accustomed + +00:00:10.800 --> 00:00:12.559 +to putting a README file at the root of + +00:00:12.559 --> 00:00:13.759 +your project. + +00:00:13.759 --> 00:00:15.845 +It's usually a Markdown file + +00:00:15.845 --> 00:00:20.579 +But if you use an Org Mode file instead, + +00:00:20.579 --> 00:00:22.560 +you can take advantage of the +great features + +00:00:22.560 --> 00:00:24.400 +that Org Mode provides, including + +00:00:24.400 --> 00:00:25.920 +literate programming, + +00:00:25.920 --> 00:00:28.000 +which lets you generate your source code + +00:00:28.000 --> 00:00:31.840 +and Markdown documentation dynamically. + +00:00:31.840 --> 00:00:34.719 +I want to walk you through a little bit + +00:00:34.719 --> 00:00:37.120 +of what this looks like. + +00:00:37.120 --> 00:00:39.440 +When you start a project, especially if + +00:00:39.440 --> 00:00:41.280 +if you use something like Github you + +00:00:41.280 --> 00:00:43.320 +begin with an automatically generated + +00:00:43.320 --> 00:00:47.039 +README.md file. So just delete that + +00:00:47.039 --> 00:00:50.239 +and instead create a README.org file. + +00:00:50.239 --> 00:00:51.712 +Starting with an empty Org file, + +00:00:51.712 --> 00:00:54.800 +like you see here, you can begin + +00:00:54.800 --> 00:00:56.559 +by recording important information about + +00:00:56.559 --> 00:00:59.440 +your project goals. You can add diagrams, + +00:00:59.440 --> 00:01:01.920 +code snippets, to-do lists, time tracking + +00:01:01.920 --> 00:01:03.520 +and much more. + +00:01:03.520 --> 00:01:05.360 +I'm going to drop in some documentation + +00:01:05.360 --> 00:01:07.760 +that that I've written about + +00:01:07.760 --> 00:01:12.240 +about my project here, so you can see + +00:01:12.240 --> 00:01:15.280 +what this would look like. + +00:01:15.280 --> 00:01:17.119 +As you can see, I have a title, and a + +00:01:17.119 --> 00:01:20.320 +description, and then a subsection + +00:01:20.320 --> 00:01:23.840 +as well as some code snippets. + +00:01:23.840 --> 00:01:25.520 +You can see that Org Mode does a great + +00:01:25.520 --> 00:01:28.240 +job of formatting lists, + +00:01:28.240 --> 00:01:31.280 +code sections, diagrams, and so forth. + +00:01:31.280 --> 00:01:35.040 +It's as good or better than Markdown, + +00:01:35.040 --> 00:01:37.179 +but when you use it in Emacs + +00:01:37.179 --> 00:01:38.880 +you can do a lot more. + +00:01:38.880 --> 00:01:40.479 +For example, you can dynamically create + +00:01:40.479 --> 00:01:43.360 +diagrams using Graphviz + +00:01:43.360 --> 00:01:45.200 +from a text description. If you go to + +00:01:45.200 --> 00:01:46.560 +this source block here + +00:01:46.560 --> 00:01:49.439 +and hit C-c C-c, you'll see + +00:01:49.439 --> 00:01:52.979 +that we generate a diagram dynamically + +00:01:55.439 --> 00:01:59.200 +You can run these code snippets in + +00:01:59.200 --> 00:02:00.799 +place and get the results + +00:02:00.799 --> 00:02:03.040 +to show up inside of your file, + +00:02:03.040 --> 00:02:08.000 +which is a really powerful paradigm. + +00:02:08.000 --> 00:02:10.640 +But most importantly, for + +00:02:10.640 --> 00:02:14.800 +my purposes here, + +00:02:14.800 --> 00:02:17.200 +Org Mode provides you the ability to do + +00:02:17.200 --> 00:02:19.520 +literate programming. + +00:02:19.520 --> 00:02:21.440 +So take a quick look at this diagram + +00:02:21.440 --> 00:02:23.200 +that I generated here. + +00:02:23.200 --> 00:02:25.312 +It gives you a quick overview of what + +00:02:25.312 --> 00:02:27.520 +I mean by literate programming + +00:02:27.520 --> 00:02:31.200 +and how I'm using it. You can see + +00:02:31.200 --> 00:02:34.720 +that we start with a README.org file +on top. + +00:02:34.720 --> 00:02:37.920 +At this point, we can do one of two +things: + +00:02:37.920 --> 00:02:41.280 +tangle or weave. Tangle is used to + +00:02:41.280 --> 00:02:42.720 +describe the process of + +00:02:42.720 --> 00:02:46.319 +generating source code, while weave + +00:02:46.319 --> 00:02:47.599 +is the process of generating + +00:02:47.599 --> 00:02:49.840 +documentation. These are terms that + +00:02:49.840 --> 00:02:51.920 +Donald Knuth used. + +00:02:51.920 --> 00:02:53.840 +He's the one that came up with the + +00:02:53.840 --> 00:02:55.519 +idea of literate programming + +00:02:55.519 --> 00:02:59.920 +in the early 1980s. + +00:02:59.920 --> 00:03:01.945 +But this is really all that there is to +it. + +00:03:01.945 --> 00:03:05.412 +You just... You are simply + +00:03:05.412 --> 00:03:07.840 +using a literate source file, + +00:03:07.840 --> 00:03:10.319 +in this case the README.org, to generate + +00:03:11.680 --> 00:03:17.120 +the rest of the project files, basically. + +00:03:17.120 --> 00:03:22.640 +So let's dig in to the details of how +this works. + +00:03:22.640 --> 00:03:24.560 +I hope you... Hopefully you'll see how + +00:03:24.560 --> 00:03:26.159 +cool this is. + +00:03:26.159 --> 00:03:27.545 +So returning to the file here. + +00:03:27.545 --> 00:03:31.120 +Let's assume we have enough +documentation now, + +00:03:31.120 --> 00:03:32.679 +that we want to get started +coding. + +00:03:32.679 --> 00:03:34.159 +So maybe we'll just start with + +00:03:34.159 --> 00:03:35.845 +like a Hello World app, + +00:03:35.845 --> 00:03:38.159 +just so we can make sure that our + +00:03:38.159 --> 00:03:41.519 +environment is set up correctly. + +00:03:41.519 --> 00:03:47.120 +Let's get started with a code block. + +00:03:47.120 --> 00:03:49.519 +So I created a little snippet to help me + +00:03:49.519 --> 00:03:51.612 +add a source block for + +00:03:51.612 --> 00:03:53.599 +literate programming quickly. + +00:03:53.599 --> 00:03:56.959 +There's not much to it, + +00:03:56.959 --> 00:03:59.479 +but there are some important annotations +here. + +00:04:01.599 --> 00:04:04.080 +Excuse me. There's a property + +00:04:04.080 --> 00:04:05.200 +called :tangle + +00:04:05.200 --> 00:04:09.360 +and that takes a value of a file name. + +00:04:09.360 --> 00:04:13.280 +Then there's also a :noweb property + +00:04:13.280 --> 00:04:18.880 +called no-export. + +00:04:23.759 --> 00:04:26.800 +Basically, the noexport--we'll explain + +00:04:26.800 --> 00:04:29.645 +that a little bit more later + +00:04:29.645 --> 00:04:32.080 +It has has to do with how + +00:04:32.080 --> 00:04:36.845 +the tangling is done in the tangle +step + +00:04:36.845 --> 00:04:38.479 +versus the weave step. + +00:04:38.479 --> 00:04:40.212 +I'll explain that a little bit more. + +00:04:40.212 --> 00:04:45.199 +But the tangle field just simply tells + +00:04:45.199 --> 00:04:48.320 +Emacs where it needs to generate the + +00:04:48.320 --> 00:04:50.320 +main.go file and where it needs to put + +00:04:50.320 --> 00:04:55.360 +it on the file system. + +00:04:55.360 --> 00:04:57.680 +You'll notice that we we're + +00:04:57.680 --> 00:04:59.040 +going to use Go. + +00:04:59.040 --> 00:05:01.440 +That's just the language that I've been + +00:05:01.440 --> 00:05:03.379 +using the most lately, + +00:05:03.379 --> 00:05:06.845 +but this programming strategy + +00:05:06.845 --> 00:05:08.400 +is language-agnostic. + +00:05:08.400 --> 00:05:11.279 +You could use any language + +00:05:11.279 --> 00:05:13.145 +or any mix of languages. + +00:05:13.145 --> 00:05:14.720 +You could create some files + +00:05:14.720 --> 00:05:16.560 +in Python, some files in Go, + +00:05:16.560 --> 00:05:19.179 +some files in Lisp, + +00:05:19.179 --> 00:05:21.520 +or whatever you want. + +00:05:24.720 --> 00:05:29.440 +Let's create just a little +Hello World. + +00:05:29.440 --> 00:05:31.379 +Let's use another snippet here + +00:05:31.379 --> 00:05:36.560 +to generate the basics of a Go program. + +00:05:36.560 --> 00:05:40.240 +I'm just going to print + +00:05:40.240 --> 00:05:44.960 +Hello World. + +00:05:44.960 --> 00:05:48.560 +So that's... And then + +00:05:48.560 --> 00:05:52.779 +let's make it a section in our file. + +00:05:52.779 --> 00:05:55.045 +So now you can see, we've got + +00:05:55.045 --> 00:05:56.400 +this snippet. + +00:05:56.400 --> 00:05:59.600 +When you have a source block in + +00:05:59.600 --> 00:06:01.600 +inside of Org Mode, you can easily pop + +00:06:01.600 --> 00:06:04.960 +into a language-specific buffer +by typing + +00:06:04.960 --> 00:06:07.680 +C-c ' (single quote). + +00:06:07.680 --> 00:06:10.240 +So you can see, now I have a + +00:06:10.240 --> 00:06:12.160 +buffer that's in go-mode + +00:06:12.160 --> 00:06:14.240 +and gives you all the ability to edit + +00:06:14.240 --> 00:06:15.520 +like you would + +00:06:15.520 --> 00:06:19.945 +normally. If you hit C-c ' +(single quote) + +00:06:19.945 --> 00:06:20.800 +again, it goes back and + +00:06:20.800 --> 00:06:25.045 +any changes you make will be +updated there. + +00:06:25.045 --> 00:06:26.160 +But you can do quite a bit + +00:06:26.160 --> 00:06:27.879 +just inside of here too. + +00:06:27.879 --> 00:06:29.199 +There's quite a bit of + +00:06:29.199 --> 00:06:34.479 +language-specific functionality + +00:06:34.479 --> 00:06:35.312 +just in place, + +00:06:35.312 --> 00:06:36.880 +so you don't always have to go over to a + +00:06:36.880 --> 00:06:38.080 +separate buffer. + +00:06:38.080 --> 00:06:42.319 +It's a nice option sometimes. + +00:06:42.319 --> 00:06:44.319 +Now that you have the code in here, + +00:06:44.319 --> 00:06:46.720 +you're going to want to run it. + +00:06:46.720 --> 00:06:48.179 +Right now, it just lives here + +00:06:48.179 --> 00:06:50.240 +in this documentation. + +00:06:50.240 --> 00:06:52.160 +You need to get a copy of it into a + +00:06:52.160 --> 00:06:53.840 +separate file, + +00:06:53.840 --> 00:06:57.440 +and that's the tangle process that you + +00:06:57.440 --> 00:07:01.360 +you need to follow there. So I'm gonna + +00:07:01.360 --> 00:07:03.360 +drop in a little bit more doc, a little + +00:07:03.360 --> 00:07:12.240 +bit more documentation really quick here. + +00:07:12.240 --> 00:07:19.112 +Okay, all right. So just as a side note, + +00:07:19.112 --> 00:07:22.845 +I like to follow this process. + +00:07:22.845 --> 00:07:26.639 +Whenever I have an operation to perform, + +00:07:26.639 --> 00:07:28.880 +I'd like to document it here with a + +00:07:28.880 --> 00:07:31.680 +snippet that can be executed inline. + +00:07:31.680 --> 00:07:33.280 +Then I don't have to leave Org Mode, and + +00:07:33.280 --> 00:07:34.639 +I don't have to try to remember what I + +00:07:34.639 --> 00:07:36.800 +did later. So instead of just + +00:07:36.800 --> 00:07:38.960 +trying to do an operation, the first time + +00:07:38.960 --> 00:07:40.319 +I do something, + +00:07:40.319 --> 00:07:41.680 +I take the time to figure out what it is + +00:07:41.680 --> 00:07:44.879 +and document it, so then it's +recorded. + +00:07:44.879 --> 00:07:49.120 +So here we find that to do a tangle +operation, + +00:07:49.120 --> 00:07:51.680 +you run the command org-babel-tangle, + +00:07:51.680 --> 00:07:53.779 +which is an Elisp command. + +00:07:53.779 --> 00:07:58.712 +If you hit C-c C-c to run it in place, + +00:07:58.712 --> 00:08:00.080 +you get the result + +00:08:00.080 --> 00:08:02.720 +of main.go, which basically is + +00:08:02.720 --> 00:08:03.759 +telling us that + +00:08:03.759 --> 00:08:07.680 +we've tangled one file called main.go. + +00:08:07.680 --> 00:08:11.039 +You can see that that's true + +00:08:11.039 --> 00:08:12.879 +if you go to the file system + +00:08:12.879 --> 00:08:14.400 +and you look. + +00:08:14.400 --> 00:08:17.840 +Now in our demo directory, + +00:08:17.840 --> 00:08:19.712 +we have a README.org, + +00:08:19.712 --> 00:08:22.045 +we have that PNG that we generated, + +00:08:22.045 --> 00:08:23.440 +but we also have a main.go. + +00:08:23.440 --> 00:08:25.945 +If you visit that file, + +00:08:25.945 --> 00:08:27.045 +you'll see that it's just + +00:08:27.045 --> 00:08:28.212 +the source code that was + +00:08:28.212 --> 00:08:29.280 +in our documentation, which is + +00:08:29.280 --> 00:08:30.679 +exactly what we expected + +00:08:30.679 --> 00:08:32.880 +and what we wanted. So that's good. + +00:08:32.880 --> 00:08:41.120 +So if we return to where we were at... + +00:08:41.120 --> 00:08:42.959 +Now we're at the point where we + +00:08:42.959 --> 00:08:44.479 +have a file on the file system. + +00:08:45.760 --> 00:08:48.379 +Now we need to build it + +00:08:48.379 --> 00:08:49.612 +and to run it. + +00:08:49.612 --> 00:08:57.040 +So let's follow the same philosophy, +where let's document + +00:08:57.040 --> 00:09:00.160 +these operations that we're going to +perform. + +00:09:00.160 --> 00:09:04.560 +I'm dropping in a + +00:09:04.560 --> 00:09:07.112 +a build instruction section + +00:09:07.112 --> 00:09:13.360 +and a run instruction section. + +00:09:13.360 --> 00:09:15.279 +As you can see here, we have a little + +00:09:15.279 --> 00:09:17.839 +a bash source block, + +00:09:17.839 --> 00:09:19.245 +and another bash source block. + +00:09:19.245 --> 00:09:21.812 +This one compiles. The go build command + +00:09:21.812 --> 00:09:25.440 +is what compiles a file. Then + +00:09:25.440 --> 00:09:26.579 +the file that gets generated + +00:09:26.579 --> 00:09:30.080 +should be called demo. + +00:09:30.080 --> 00:09:32.412 +So we just run it here. + +00:09:32.412 --> 00:09:37.839 +If I type C-c C-c, we get an +empty results block. + +00:09:37.839 --> 00:09:38.979 +When you compile things, + +00:09:38.979 --> 00:09:41.360 +no news is good news. + +00:09:41.360 --> 00:09:43.012 +It means there's no errors + +00:09:43.012 --> 00:09:45.912 +So presumably, we've created + +00:09:45.912 --> 00:09:48.000 +an executable that's called demo. + +00:09:51.440 --> 00:09:53.312 +Let's look again at the file system + +00:09:53.312 --> 00:10:02.480 +and regenerate... + +00:10:02.480 --> 00:10:06.479 +Yep. What we have here is a demo +executable, + +00:10:06.479 --> 00:10:07.760 +which is exactly what we +wanted. + +00:10:07.760 --> 00:10:12.079 +Let's go back. + +00:10:12.079 --> 00:10:14.160 +Now we should be able to run it. + +00:10:14.160 --> 00:10:16.079 +C-c C-c, + +00:10:16.079 --> 00:10:20.399 +and we get Hello World as a result, + +00:10:20.399 --> 00:10:23.440 +which was exactly what we were expecting. + +00:10:23.440 --> 00:10:26.560 +So that's already pretty cool. + +00:10:26.560 --> 00:10:30.839 +You can do that much. + +00:10:33.040 --> 00:10:34.560 +That's really just the tip of + +00:10:34.560 --> 00:10:37.839 +the iceberg. To really + +00:10:41.040 --> 00:10:43.440 +use the more impressive features of + +00:10:43.440 --> 00:10:46.160 +literate programming, + +00:10:46.160 --> 00:10:49.920 +we need to do a little bit more + +00:10:53.200 --> 00:10:54.512 +at least. Really, + +00:10:54.512 --> 00:10:56.480 +to get the full benefit of it, + +00:10:56.480 --> 00:11:01.079 +we need to add some sections + +00:11:01.079 --> 00:11:04.412 +that will cause Emacs to have to + +00:11:04.412 --> 00:11:06.720 +tangle or assemble + +00:11:06.720 --> 00:11:09.760 +this file from different pieces. + +00:11:09.760 --> 00:11:13.120 +Imagine that we wanted to take this file + +00:11:13.120 --> 00:11:16.720 +and maybe kind of templatize it. + +00:11:16.720 --> 00:11:19.120 +So, using literature programming syntax, + +00:11:19.120 --> 00:11:21.279 +this angle bracket syntax, + +00:11:21.279 --> 00:11:24.399 +let's say that we want to create an + +00:11:24.399 --> 00:11:29.360 +imports section, + +00:11:29.360 --> 00:11:32.399 +a functions section, + +00:11:32.399 --> 00:11:35.040 +and then maybe just a main section. + +00:11:35.040 --> 00:11:36.240 +We'll get rid of this. + +00:11:36.240 --> 00:11:37.920 +So now you see, we've created something + +00:11:37.920 --> 00:11:39.760 +that looks a little bit like a + +00:11:39.760 --> 00:11:42.880 +template or a scaffolding or outline + +00:11:42.880 --> 00:11:45.812 +for what our file is going to be. + +00:11:45.812 --> 00:11:48.399 +It looks a little bit like pseudocode. + +00:11:48.399 --> 00:11:50.612 +What we're going to have + +00:11:50.612 --> 00:11:52.399 +literate programming do + +00:11:52.399 --> 00:11:54.800 +is dynamically insert those things into + +00:11:54.800 --> 00:11:56.639 +those slots. + +00:11:56.639 --> 00:12:00.079 +So the first thing we need to do + +00:12:00.079 --> 00:12:03.200 +is... So let's create a section + +00:12:03.200 --> 00:12:08.079 +called "Say Hello." + +00:12:08.079 --> 00:12:09.519 +We want to add some functionality that + +00:12:09.519 --> 00:12:12.720 +makes our program say hello. + +00:12:12.720 --> 00:12:15.680 +So using a different snippet that I have + +00:12:15.680 --> 00:12:17.600 +for creating something + +00:12:17.600 --> 00:12:20.800 +that I call like a literate section, + +00:12:20.800 --> 00:12:24.079 +basically, we create a + +00:12:24.079 --> 00:12:26.000 +another source block that's almost the + +00:12:26.000 --> 00:12:27.839 +same as the one for the file. + +00:12:27.839 --> 00:12:29.412 +It just has a few differences + +00:12:29.412 --> 00:12:34.079 +Say we want to drop code into the import +section + +00:12:34.079 --> 00:12:36.639 +and we want it to be in Go. + +00:12:36.639 --> 00:12:40.720 +Here we use the same :noweb no-export syntax, + +00:12:40.720 --> 00:12:44.560 +but then we've added this :noweb-ref imports, + +00:12:44.560 --> 00:12:48.240 +and this ties that slot + +00:12:48.240 --> 00:12:51.120 +to this reference. It tells + +00:12:51.120 --> 00:12:53.760 +Emacs that when you tangle, + +00:12:53.760 --> 00:12:55.479 +we want to stick whatever's in here + +00:12:55.479 --> 00:12:58.240 +in that spot. + +00:12:58.240 --> 00:13:02.079 +You skip the tangle file name section + +00:13:02.079 --> 00:13:03.279 +because you're not actually creating a + +00:13:03.279 --> 00:13:04.240 +file name. + +00:13:04.240 --> 00:13:06.160 +You're putting information into an + +00:13:06.160 --> 00:13:07.680 +existing file. + +00:13:07.680 --> 00:13:10.720 +So here, we would just add the "fmt" + +00:13:10.720 --> 00:13:14.399 +for the imports. + +00:13:14.399 --> 00:13:16.145 +Let's add another section + +00:13:16.145 --> 00:13:22.240 +for functions. + +00:13:22.240 --> 00:13:23.812 +Let's just create a function + +00:13:23.812 --> 00:13:28.079 +called sayHello + +00:13:28.079 --> 00:13:31.745 +that doesn't have any arguments. + +00:13:31.745 --> 00:13:34.000 +No return types. + +00:13:34.000 --> 00:13:35.760 +All it does is pretty much the + +00:13:35.760 --> 00:13:37.440 +same thing as we did before: + +00:13:37.440 --> 00:13:38.479 +just print something. + +00:13:38.479 --> 00:13:45.760 +Let's just say "Hello EmacsConf" +this time. + +00:13:45.760 --> 00:13:47.279 +Now we have a function, + +00:13:47.279 --> 00:13:50.779 +and now the function won't do anything + +00:13:50.779 --> 00:13:52.720 +unless we invoke it. Let's do + +00:13:52.720 --> 00:13:56.000 +one last literate section + +00:13:56.000 --> 00:13:59.920 +called main. Make that Go + +00:13:59.920 --> 00:14:03.519 +source block. Then let's + +00:14:03.519 --> 00:14:10.320 +invoke that function. + +00:14:10.320 --> 00:14:13.360 +Now you can see that we've got + +00:14:13.360 --> 00:14:15.600 +our scaffolding + +00:14:15.600 --> 00:14:17.199 +outline, and then we have + +00:14:17.199 --> 00:14:20.079 +the sections that we want to get tangled + +00:14:20.079 --> 00:14:21.360 +or inserted. + +00:14:21.360 --> 00:14:25.440 +I've used this syntax. + +00:14:25.440 --> 00:14:27.199 +It's kinda borrowed from + +00:14:27.199 --> 00:14:28.479 +literate programming a little bit + +00:14:28.479 --> 00:14:30.320 +with a +=, so really it's just saying + +00:14:30.320 --> 00:14:32.480 +that I want to append + +00:14:32.480 --> 00:14:35.760 +this item into the import section + +00:14:35.760 --> 00:14:37.600 +It's really just to make a little bit + +00:14:37.600 --> 00:14:39.839 +more clear what's going on. + +00:14:39.839 --> 00:14:41.445 +When you generate documentation, + +00:14:41.445 --> 00:14:43.519 +you won't see these + +00:14:43.519 --> 00:14:46.979 +particular property annotations, + +00:14:46.979 --> 00:14:50.145 +and so you won't know immediately + +00:14:50.145 --> 00:14:51.779 +that this section goes in the + +00:14:51.779 --> 00:14:53.839 +imports area. So I usually put + +00:14:53.839 --> 00:14:55.440 +a little bit of documentation on top + +00:14:55.440 --> 00:14:57.760 +there, so that it's easy to see. + +00:14:57.760 --> 00:15:01.120 +You would, probably, if this was very + +00:15:01.120 --> 00:15:03.040 +complicated, you'd put some + +00:15:03.040 --> 00:15:06.245 +documentation above to explain + +00:15:06.245 --> 00:15:07.360 +what you were doing, + +00:15:07.360 --> 00:15:11.519 +maybe right here. + +00:15:11.519 --> 00:15:13.279 +You could picture yourself + +00:15:13.279 --> 00:15:15.040 +maybe explaining + +00:15:15.040 --> 00:15:16.745 +a complicated algorithm + +00:15:16.745 --> 00:15:18.079 +or something up here + +00:15:18.079 --> 00:15:21.120 +and having a nice way to document it. + +00:15:21.120 --> 00:15:22.959 +So now that we've got that here in the + +00:15:22.959 --> 00:15:25.600 +documentation, we need to figure out... + +00:15:25.600 --> 00:15:27.040 +We need to make sure that it's going to + +00:15:27.040 --> 00:15:28.045 +tangle properly. + +00:15:28.045 --> 00:15:33.519 +Your best friend at this point + +00:15:33.519 --> 00:15:35.680 +is a keyboard shortcut that lets you + +00:15:35.680 --> 00:15:37.945 +preview the tangled operation. + +00:15:37.945 --> 00:15:42.560 +If you say C-c C-v C-v, + +00:15:42.560 --> 00:15:44.079 +it will create a new buffer + +00:15:44.079 --> 00:15:47.212 +with the tangled contents + +00:15:47.212 --> 00:15:49.179 +and so you can see here + +00:15:49.179 --> 00:15:52.345 +that the fmt import went to the right +place, + +00:15:52.345 --> 00:15:54.679 +that function went to the right place, + +00:15:54.679 --> 00:15:56.079 +the function invocation went to + +00:15:56.079 --> 00:15:58.480 +the right place. We're feeling good. + +00:15:58.480 --> 00:16:00.912 +You can nest these things + +00:16:00.912 --> 00:16:02.800 +many layers deep. + +00:16:02.800 --> 00:16:06.045 +If you came into the sayHello function, + +00:16:06.045 --> 00:16:10.560 +you could add more sections. + +00:16:10.560 --> 00:16:13.759 +It'll go through and it'll + +00:16:13.759 --> 00:16:15.345 +keep track of all that + +00:16:15.345 --> 00:16:16.212 +and tangle it for you + +00:16:16.212 --> 00:16:16.959 +so you really get a lot of freedom + +00:16:16.959 --> 00:16:18.320 +and flexibility for how you want to + +00:16:18.320 --> 00:16:20.479 +document things by doing this. + +00:16:20.479 --> 00:16:23.079 +So now that we've previewed it + +00:16:23.079 --> 00:16:25.839 +and we feel good about it, + +00:16:25.839 --> 00:16:28.639 +we need to tangle so + +00:16:28.639 --> 00:16:31.440 +we get the file on the file system. + +00:16:31.440 --> 00:16:34.979 +so C-c C-c and get... + +00:16:34.979 --> 00:16:37.199 +just main.go comes back again. + +00:16:37.199 --> 00:16:40.959 +C-c C-cc and no errors come back. + +00:16:40.959 --> 00:16:43.279 +Then if we did this right, + +00:16:43.279 --> 00:16:45.079 +when we run this, we should get + +00:16:45.079 --> 00:16:45.600 +"Hello, EmacsConf." + +00:16:45.600 --> 00:16:51.199 +So C-c C-c, Hello EmacsConf. + +00:16:54.800 --> 00:16:57.645 +I think that's pretty, pretty cool, +actually. + +00:16:57.645 --> 00:16:59.579 +So we've got the breadcrumbs + +00:16:59.579 --> 00:17:01.212 +of the process we've gone through + +00:17:01.212 --> 00:17:02.399 +to get to this point, + +00:17:02.399 --> 00:17:07.545 +this initial document that has some +tangling in it. + +00:17:07.545 --> 00:17:09.919 +We have documentation for how to tangle, + +00:17:09.919 --> 00:17:11.345 +how to build, how to run. + +00:17:11.345 --> 00:17:15.045 +We've really built a nice foundation + +00:17:15.045 --> 00:17:19.379 +for moving forward on our project + +00:17:19.379 --> 00:17:21.439 +and a nice way of breaking things +out + +00:17:21.439 --> 00:17:23.280 +and documenting further. + +00:17:23.280 --> 00:17:27.120 +The last piece that we need to + +00:17:27.120 --> 00:17:30.559 +take care of is the weave that + +00:17:30.559 --> 00:17:34.799 +I showed you in the diagram above. + +00:17:34.799 --> 00:17:38.640 +So one more time, we'll drop in + +00:17:38.640 --> 00:17:41.760 +some documentatio, this time on how + +00:17:41.760 --> 00:17:42.400 +to weave. + +00:17:42.400 --> 00:17:44.400 +It's really just an export function. + +00:17:44.400 --> 00:17:46.245 +it's not... There's not a separate + +00:17:46.245 --> 00:17:49.012 +weave command going on here. + +00:17:49.012 --> 00:17:50.640 +we're just going to export + +00:17:50.640 --> 00:17:53.512 +what we've got here into a Markdown +format. + +00:17:53.512 --> 00:17:57.045 +We're using org-gfm-export-to-markdown, + +00:17:57.045 --> 00:17:59.745 +which is the Github style markdown. + +00:17:59.745 --> 00:18:02.160 +You can use the other, + +00:18:02.160 --> 00:18:03.812 +more standard type as well. + +00:18:03.812 --> 00:18:08.479 +Hit C-c C-c. Now you see + +00:18:08.479 --> 00:18:11.312 +we've got a README file, + +00:18:11.312 --> 00:18:16.512 +and if you look in the file system, + +00:18:16.512 --> 00:18:19.120 +we've got that right there. + +00:18:19.120 --> 00:18:23.120 +If you go to something like ghostwriter + +00:18:23.120 --> 00:18:31.679 +and open that file, + +00:18:31.679 --> 00:18:32.879 +now you can see that + +00:18:32.879 --> 00:18:35.520 +it's generated some documentation. + +00:18:35.520 --> 00:18:37.645 +It puts a index at top at the top. + +00:18:39.679 --> 00:18:41.145 +I usually turn that off. + +00:18:41.145 --> 00:18:42.379 +It's easy to do that by + +00:18:42.379 --> 00:18:43.179 +putting a property at the + +00:18:43.179 --> 00:18:46.145 +top of your Org file, + +00:18:46.145 --> 00:18:46.880 +but some people like to + +00:18:46.880 --> 00:18:48.559 +have an index. + +00:18:48.559 --> 00:18:50.799 +Here you can see that it has generated + +00:18:50.799 --> 00:18:55.200 +pretty nicely and formatted +snippets well, + +00:18:55.200 --> 00:18:56.880 +put the diagram in there, and then + +00:18:58.240 --> 00:19:02.799 +it's preserved this +literate programming syntax, + +00:19:02.799 --> 00:19:04.960 +which is important because that's how we + +00:19:04.960 --> 00:19:06.112 +want to view the documentation. + +00:19:06.112 --> 00:19:11.312 +That's what the no-exports property + +00:19:11.312 --> 00:19:13.360 +was trying to maintain. + +00:19:13.360 --> 00:19:15.979 +no-exports means when you export, + +00:19:15.979 --> 00:19:18.400 +do not try to tangle. + +00:19:18.400 --> 00:19:20.559 +Hopefully that makes more sense now. + +00:19:20.559 --> 00:19:22.240 +Now you can see all the documentation. + +00:19:22.240 --> 00:19:26.080 +I think it demonstrates a + +00:19:26.080 --> 00:19:33.520 +pretty useful feature that's inside of +Emacs. + +00:19:33.520 --> 00:19:34.979 +Hopefully you'll have as much fun + +00:19:34.979 --> 00:19:39.919 +using that as I have. + +00:19:39.919 --> 00:19:43.600 +So thanks! -- cgit v1.2.3