diff options
Diffstat (limited to '2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.vtt')
| -rw-r--r-- | 2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.vtt | 1426 |
1 files changed, 1426 insertions, 0 deletions
diff --git a/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.vtt b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.vtt new file mode 100644 index 00000000..3179635f --- /dev/null +++ b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.vtt @@ -0,0 +1,1426 @@ +WEBVTT + +00:00:03.600 --> 00:00:04.400 +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:16.400 +and it's usually a markdown file but if + +00:00:16.400 --> 00:00:17.600 +you use an org + +00:00:17.600 --> 00:00:20.720 +more an org mode file instead you can + +00:00:20.720 --> 00:00:22.560 +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.920 +starting with an empty org file like you + +00:00:51.920 --> 00:00:54.800 +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 I r that I've written about + +00:01:07.760 --> 00:01:10.840 +about my project here so you can kind of + +00:01:10.840 --> 00:01:12.240 +see + +00:01:12.240 --> 00:01:15.280 +what this would look like + +00:01:15.280 --> 00:01:17.119 +so as you can see I have a title and a + +00:01:17.119 --> 00:01:20.320 +description and then a sub section + +00:01:20.320 --> 00:01:23.840 +as well as some code snippets + +00:01:23.840 --> 00:01:25.520 +and you can see that orgmo does a great + +00:01:25.520 --> 00:01:28.240 +job of formatting lists and + +00:01:28.240 --> 00:01:31.280 +code sections diagrams and so forth + +00:01:31.280 --> 00:01:33.920 +it's good or it's as good or better than + +00:01:33.920 --> 00:01:35.040 +markdown + +00:01:35.040 --> 00:01:37.520 +but when you use it in the Emacs you can + +00:01:37.520 --> 00:01:38.880 +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 so 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 control c control c you'll see + +00:01:49.439 --> 00:01:51.439 +that we generate a + +00:01:51.439 --> 00:01:55.439 +diagram dynamically you can run + +00:01:55.439 --> 00:01:59.200 +so 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 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 important most importantly for + +00:02:10.640 --> 00:02:11.520 +the + +00:02:11.520 --> 00:02:14.800 +purposes my purpose is here + +00:02:14.800 --> 00:02:17.200 +orgmo 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.360 +and gives you a quick overview of what I + +00:02:25.360 --> 00:02:27.520 +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:33.920 +that we start with a readme.org file on + +00:02:33.920 --> 00:02:34.720 +top + +00:02:34.720 --> 00:02:36.879 +at this point we can do one of two + +00:02:36.879 --> 00:02:37.920 +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 +and 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.519 +but this is really all that there is to + +00:03:01.519 --> 00:03:04.480 +it you just + +00:03:04.480 --> 00:03:06.400 +who are simply using literate illiterate + +00:03:06.400 --> 00:03:07.840 +source file + +00:03:07.840 --> 00:03:10.319 +in this case the readme.org to generate + +00:03:10.319 --> 00:03:11.680 +the rest of the project + +00:03:11.680 --> 00:03:17.120 +the rest of the project files basically + +00:03:17.120 --> 00:03:20.959 +so let's dig in to the details of how + +00:03:20.959 --> 00:03:22.640 +this works + +00:03:22.640 --> 00:03:24.560 +and 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:28.959 +so returning to the file here let's + +00:03:28.959 --> 00:03:31.120 +assume we have enough documentation now + +00:03:31.120 --> 00:03:32.080 +that we want to get started + +00:03:32.080 --> 00:03:34.159 +coding so maybe we'll just start with + +00:03:34.159 --> 00:03:35.519 +like a hello world + +00:03:35.519 --> 00:03:38.159 +app 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 +so 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:50.319 +add + +00:03:50.319 --> 00:03:52.239 +a source block for literate programming + +00:03:52.239 --> 00:03:53.599 +quickly + +00:03:53.599 --> 00:03:56.959 +and there's not much to it + +00:03:56.959 --> 00:03:58.799 +but there is some important annotations + +00:03:58.799 --> 00:04:01.599 +here so there's + +00:04:01.599 --> 00:04:04.080 +excuse me there's a 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 +and then there's also a no web property + +00:04:13.280 --> 00:04:18.880 +called no export + +00:04:18.880 --> 00:04:23.759 +and basically + +00:04:23.759 --> 00:04:26.800 +basically the no export will explain + +00:04:26.800 --> 00:04:28.639 +that a little bit + +00:04:28.639 --> 00:04:32.080 +more later um it has has to do with how + +00:04:32.080 --> 00:04:33.919 +the tangling + +00:04:33.919 --> 00:04:37.600 +is uh done in the tangle step versus the + +00:04:37.600 --> 00:04:39.280 +weave step and I'll explain that a + +00:04:39.280 --> 00:04:41.199 +little bit more but the tangle + +00:04:41.199 --> 00:04:45.199 +field just simply tells tells uh + +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 +uh you'll 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:02.160 +using + +00:05:02.160 --> 00:05:05.360 +the most lately uh but + +00:05:05.360 --> 00:05:07.360 +this programming strategy is language + +00:05:07.360 --> 00:05:08.400 +agnostic + +00:05:08.400 --> 00:05:12.080 +you could use any language or any mix + +00:05:12.080 --> 00:05:14.720 +of languages you could create some files + +00:05:14.720 --> 00:05:16.560 +in python some files and go + +00:05:16.560 --> 00:05:19.520 +some files in in lisp or whatever you + +00:05:19.520 --> 00:05:21.520 +want + +00:05:21.520 --> 00:05:24.720 +and so but let's + +00:05:24.720 --> 00:05:28.000 +uh let's create just a little hello + +00:05:28.000 --> 00:05:29.440 +world + +00:05:29.440 --> 00:05:32.320 +let's use another snippet here to + +00:05:32.320 --> 00:05:33.520 +generate + +00:05:33.520 --> 00:05:36.560 +the basics of a go program + +00:05:36.560 --> 00:05:40.240 +so 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.320 +let's make it a section in our + +00:05:52.320 --> 00:05:55.280 +file so now you can see we've got this + +00:05:55.280 --> 00:05:56.400 +snippet + +00:05:56.400 --> 00:05:59.600 +um 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:02.880 +into a + +00:06:02.880 --> 00:06:04.960 +language specific buffer by typing + +00:06:04.960 --> 00:06:07.680 +control c single quote + +00:06:07.680 --> 00:06:10.240 +so you can see now I have a a go 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:18.800 +normally if you hit ctrl c + +00:06:18.800 --> 00:06:20.800 +single quote again then it goes back and + +00:06:20.800 --> 00:06:22.639 +any changes you + +00:06:22.639 --> 00:06:25.280 +make would will be updated there but you + +00:06:25.280 --> 00:06:26.160 +can do quite a bit + +00:06:26.160 --> 00:06:28.000 +just inside of here too there's quite a + +00:06:28.000 --> 00:06:29.199 +bit of + +00:06:29.199 --> 00:06:33.360 +language specific + +00:06:33.360 --> 00:06:35.440 +functionality just in place and so you + +00:06:35.440 --> 00:06:36.880 +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 +but it's a it's a nice option sometimes + +00:06:42.319 --> 00:06:44.319 +but 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.560 +but right now it just lives here in this + +00:06:48.560 --> 00:06:50.240 +documentation + +00:06:50.240 --> 00:06:52.160 +so 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:05.280 +bit more + +00:07:05.280 --> 00:07:12.240 +documentation really quick here + +00:07:12.240 --> 00:07:17.360 +okay all right so just kind of as a + +00:07:17.360 --> 00:07:21.520 +kind of as a side note I like to follow + +00:07:21.520 --> 00:07:24.800 +this process uh whenever having whenever + +00:07:24.800 --> 00:07:26.639 +I have an operation to perform I + +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 in line + +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 I take the + +00:07:40.319 --> 00:07:41.680 +take the time to figure out what it is + +00:07:41.680 --> 00:07:43.440 +and document it and so then it's + +00:07:43.440 --> 00:07:44.879 +recorded + +00:07:44.879 --> 00:07:48.400 +and so here we find that to do a tangle + +00:07:48.400 --> 00:07:49.120 +operation + +00:07:49.120 --> 00:07:51.680 +you run the command or babel tangled + +00:07:51.680 --> 00:07:52.560 +which is a + +00:07:52.560 --> 00:07:55.840 +e-list command so if you hit ctrl c + +00:07:55.840 --> 00:07:59.199 +ctrl c to run it in place you get the + +00:07:59.199 --> 00:08:00.080 +result + +00:08:00.080 --> 00:08:02.720 +of main dot 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 +and you can see that that's true + +00:08:11.039 --> 00:08:14.000 +if you go to the file system and you + +00:08:14.000 --> 00:08:14.400 +look + +00:08:14.400 --> 00:08:17.840 +so now in uh in our demo directory + +00:08:17.840 --> 00:08:20.960 +we have a readme.org we have that png + +00:08:20.960 --> 00:08:22.479 +that we generated but we also have a + +00:08:22.479 --> 00:08:23.440 +main.go + +00:08:23.440 --> 00:08:26.080 +and if you if you visit that file you'll + +00:08:26.080 --> 00:08:27.759 +see that it's just the source code that + +00:08:27.759 --> 00:08:29.280 +was in our documentation which is + +00:08:29.280 --> 00:08:31.039 +exactly what we expected and what we + +00:08:31.039 --> 00:08:32.880 +wanted so that's good + +00:08:32.880 --> 00:08:36.560 +so if we return to + +00:08:36.560 --> 00:08:41.120 +to where we are at + +00:08:41.120 --> 00:08:42.959 +now we're we're at the point where we + +00:08:42.959 --> 00:08:44.640 +have a file on the file system so now we + +00:08:44.640 --> 00:08:45.760 +need + +00:08:45.760 --> 00:08:48.959 +um now we need to build it and to + +00:08:48.959 --> 00:08:53.600 +run it so let's follow the same + +00:08:53.600 --> 00:08:57.040 +philosophy where let's document + +00:08:57.040 --> 00:08:58.720 +these operations that we're going to + +00:08:58.720 --> 00:09:00.160 +perform + +00:09:00.160 --> 00:09:04.560 +so I'm dropping in a + +00:09:04.560 --> 00:09:07.839 +a build instruction section and a run + +00:09:07.839 --> 00:09:13.360 +instruction section + +00:09:13.360 --> 00:09:15.279 +so 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:20.000 +and another batch source block this one + +00:09:20.000 --> 00:09:22.000 +compiles the go build command is what + +00:09:22.000 --> 00:09:25.440 +compiles a file and then + +00:09:25.440 --> 00:09:26.880 +the file that gets generated should be + +00:09:26.880 --> 00:09:30.080 +called demo + +00:09:30.080 --> 00:09:32.959 +and uh so we just run it here so if if I + +00:09:32.959 --> 00:09:34.000 +type control c + +00:09:34.000 --> 00:09:37.839 +control c we get an empty results block + +00:09:37.839 --> 00:09:40.640 +when you compile things no news is good + +00:09:40.640 --> 00:09:41.360 +news + +00:09:41.360 --> 00:09:44.399 +so it means there's no errors so + +00:09:44.399 --> 00:09:46.560 +presumably we've created an executable + +00:09:46.560 --> 00:09:48.000 +that's called demo + +00:09:48.000 --> 00:09:51.440 +so let's uh + +00:09:51.440 --> 00:09:54.560 +let's look again at the file system and + +00:09:54.560 --> 00:10:02.480 +regenerate + +00:10:02.480 --> 00:10:05.760 +yep and what we have here is a demo + +00:10:05.760 --> 00:10:07.200 +executable which is exactly what we + +00:10:07.200 --> 00:10:07.760 +wanted + +00:10:07.760 --> 00:10:12.079 +so let's go back + +00:10:12.079 --> 00:10:14.160 +so now we should be able to run it so + +00:10:14.160 --> 00:10:16.079 +ctrl c ctrl 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 you can do that much + +00:10:30.839 --> 00:10:33.040 +um but + +00:10:33.040 --> 00:10:34.560 +that's really just kind of the tip of + +00:10:34.560 --> 00:10:37.839 +the iceberg to uh to really + +00:10:37.839 --> 00:10:41.040 +kind of um + +00:10:41.040 --> 00:10:43.440 +use the more impressive features of + +00:10:43.440 --> 00:10:46.160 +literate programming we need to uh + +00:10:46.160 --> 00:10:49.920 +we need to do a little bit more + +00:10:49.920 --> 00:10:53.200 +so or at least + +00:10:53.200 --> 00:10:55.519 +at least really to get the full benefit + +00:10:55.519 --> 00:10:56.480 +of it then + +00:10:56.480 --> 00:10:59.600 +we need to do + +00:10:59.600 --> 00:11:02.959 +add some sections that will cause uh + +00:11:02.959 --> 00:11:06.320 +Emacs to have to to tangle or assemble + +00:11:06.320 --> 00:11:06.720 +this + +00:11:06.720 --> 00:11:09.760 +this file from different pieces so + +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 in + +00:11:24.399 --> 00:11:29.360 +imports section + +00:11:29.360 --> 00:11:32.399 +in a functions section + +00:11:32.399 --> 00:11:35.040 +and then maybe just a main section and + +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.000 +like a template or a scaffolding or + +00:11:42.000 --> 00:11:42.880 +outline + +00:11:42.880 --> 00:11:46.000 +for what what our file is going to be it + +00:11:46.000 --> 00:11:48.399 +looks a little bit like pseudocode + +00:11:48.399 --> 00:11:50.800 +and what we're going to have literate + +00:11:50.800 --> 00:11:52.399 +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 +maybe called say hello so we want + +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 +um 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 but it's + +00:12:27.839 --> 00:12:31.040 +it just has a few differences so say we + +00:12:31.040 --> 00:12:31.680 +want to + +00:12:31.680 --> 00:12:34.160 +drop code into the import section and we + +00:12:34.160 --> 00:12:36.639 +want it to be in go + +00:12:36.639 --> 00:12:39.120 +here we use the same noed no web no + +00:12:39.120 --> 00:12:40.720 +export syntax + +00:12:40.720 --> 00:12:43.200 +but then we've added this no web refs + +00:12:43.200 --> 00:12:44.560 +imports + +00:12:44.560 --> 00:12:48.240 +and this ties that slot + +00:12:48.240 --> 00:12:51.120 +basically to this reference it tells + +00:12:51.120 --> 00:12:53.760 +Emacs that when you tangle + +00:12:53.760 --> 00:12:56.880 +we want to stick whatever's in here in + +00:12:56.880 --> 00:12:58.240 +that spot + +00:12:58.240 --> 00:13:02.079 +so 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 you're + +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:18.839 +so let's add another section for uh + +00:13:18.839 --> 00:13:22.240 +functions and let's create a + +00:13:22.240 --> 00:13:25.519 +let's just create a function called + +00:13:25.519 --> 00:13:30.240 +say hello that + +00:13:30.240 --> 00:13:32.839 +doesn't have any arguments no return + +00:13:32.839 --> 00:13:34.000 +types + +00:13:34.000 --> 00:13:35.760 +all it does is kind of pretty much the + +00:13:35.760 --> 00:13:37.440 +same thing as we did before + +00:13:37.440 --> 00:13:39.199 +just print something but let's just say + +00:13:39.199 --> 00:13:41.360 +hello + +00:13:41.360 --> 00:13:45.760 +Emacs comp this time + +00:13:45.760 --> 00:13:49.519 +okay so now we have a function and now + +00:13:49.519 --> 00:13:51.040 +the function won't do anything unless we + +00:13:51.040 --> 00:13:52.720 +invoke it so 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 and then let's + +00:14:03.519 --> 00:14:06.560 +just invoke + +00:14:06.560 --> 00:14:10.320 +that that function + +00:14:10.320 --> 00:14:13.360 +so now you can see that we've got + +00:14:13.360 --> 00:14:15.600 +our scaffolding scaffolding kind of + +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 +so I I've kind of used this syntax + +00:14:25.440 --> 00:14:27.199 +it's it's kind of borrowed from + +00:14:27.199 --> 00:14:28.560 +literature programming a little bit with + +00:14:28.560 --> 00:14:30.320 +a plus equals 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 so + +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.519 +when you generate documentation you + +00:14:41.519 --> 00:14:43.519 +won't see these + +00:14:43.519 --> 00:14:46.160 +these these particular property + +00:14:46.160 --> 00:14:49.360 +annotations and so you won't know + +00:14:49.360 --> 00:14:51.440 +immediately that this section goes in + +00:14:51.440 --> 00:14:53.839 +the imports area and 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 +and 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.399 +documentation above to explain what you + +00:15:06.399 --> 00:15:07.360 +were doing + +00:15:07.360 --> 00:15:11.519 +maybe right here + +00:15:11.519 --> 00:15:13.279 +you could you could picture yourself + +00:15:13.279 --> 00:15:15.040 +maybe explaining + +00:15:15.040 --> 00:15:17.440 +a complicated algorithm or something up + +00:15:17.440 --> 00:15:18.079 +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:29.920 +tangle properly so your best friend + +00:15:29.920 --> 00:15:33.519 +at this point is is uh + +00:15:33.519 --> 00:15:35.680 +is a keyboard shortcut that lets you + +00:15:35.680 --> 00:15:38.240 +preview the tangled operation so if you + +00:15:38.240 --> 00:15:38.959 +say control + +00:15:38.959 --> 00:15:42.560 +c control v control v + +00:15:42.560 --> 00:15:45.120 +it will create a new buffer with the + +00:15:45.120 --> 00:15:46.480 +tangled + +00:15:46.480 --> 00:15:49.360 +contents and so you can see here that + +00:15:49.360 --> 00:15:50.639 +the fmt + +00:15:50.639 --> 00:15:53.199 +import went to the right place that + +00:15:53.199 --> 00:15:54.720 +function went to the right place the + +00:15:54.720 --> 00:15:56.160 +function invocation went to the right + +00:15:56.160 --> 00:15:58.480 +place and so we're feeling good + +00:15:58.480 --> 00:16:01.279 +you can nest these things many layers + +00:16:01.279 --> 00:16:02.800 +deep + +00:16:02.800 --> 00:16:04.800 +actually so like if you came into the + +00:16:04.800 --> 00:16:07.199 +say hello function you could add + +00:16:07.199 --> 00:16:10.560 +more sections + +00:16:10.560 --> 00:16:12.160 +you know and it gets and it'll go + +00:16:12.160 --> 00:16:13.759 +through and it'll + +00:16:13.759 --> 00:16:15.680 +keep track of all that and tangle it for + +00:16:15.680 --> 00:16:16.959 +you 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:19.600 +document things + +00:16:19.600 --> 00:16:22.320 +by doing this so now that we've + +00:16:22.320 --> 00:16:25.839 +previewed it and we feel good about it + +00:16:25.839 --> 00:16:28.639 +we need to uh we need to tangle so we + +00:16:28.639 --> 00:16:31.440 +get the file on the file system + +00:16:31.440 --> 00:16:34.480 +so ctrl c ctrl c and + +00:16:34.480 --> 00:16:37.199 +get just main.go comes back again + +00:16:37.199 --> 00:16:37.920 +control c + +00:16:37.920 --> 00:16:40.959 +control c and no errors come back + +00:16:40.959 --> 00:16:43.839 +and then if we did this right when we + +00:16:43.839 --> 00:16:45.600 +when we run this we should get hello + +00:16:45.600 --> 00:16:47.199 +Emacs comp so ctrl c + +00:16:47.199 --> 00:16:51.199 +ctrl c hello Emacs comp + +00:16:51.199 --> 00:16:54.800 +so I uh + +00:16:54.800 --> 00:16:57.120 +I think that's pretty pretty cool + +00:16:57.120 --> 00:16:58.240 +actually so we've got + +00:16:58.240 --> 00:17:00.160 +kind of the breadcrumbs of the process + +00:17:00.160 --> 00:17:02.399 +we've gone through to get to this point + +00:17:02.399 --> 00:17:05.520 +this initial this initial + +00:17:05.520 --> 00:17:08.000 +document that has some tangling in it we + +00:17:08.000 --> 00:17:09.919 +have documentation for how to tangle + +00:17:09.919 --> 00:17:12.799 +how to build how to run it's we've + +00:17:12.799 --> 00:17:14.079 +really built a nice + +00:17:14.079 --> 00:17:17.760 +foundation for + +00:17:17.760 --> 00:17:20.160 +moving forward on our project and a nice + +00:17:20.160 --> 00:17:21.439 +way of breaking things out and + +00:17:21.439 --> 00:17:23.280 +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 I + +00:17:30.559 --> 00:17:34.799 +that's 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 documentation so this time on how + +00:17:41.760 --> 00:17:42.400 +to weave + +00:17:42.400 --> 00:17:44.400 +so it's really just an export function + +00:17:44.400 --> 00:17:47.520 +it's not there's not a separate weave + +00:17:47.520 --> 00:17:49.280 +command going on here we're just going + +00:17:49.280 --> 00:17:50.640 +to export + +00:17:50.640 --> 00:17:52.799 +what we've got here into a markdown + +00:17:52.799 --> 00:17:55.200 +format so we're using org + +00:17:55.200 --> 00:17:57.440 +gfm export to markdown which is the + +00:17:57.440 --> 00:17:58.880 +github style + +00:17:58.880 --> 00:18:02.160 +markdown you can use the other just + +00:18:02.160 --> 00:18:05.440 +more standard type as well so hit ctrl c + +00:18:05.440 --> 00:18:10.320 +ctrl c now you see we've got a readme + +00:18:10.320 --> 00:18:15.280 +file and if you look + +00:18:15.280 --> 00:18:17.440 +in the file system we've got that right + +00:18:17.440 --> 00:18:19.120 +there and so + +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:34.559 +now you can see that it's generated some + +00:18:34.559 --> 00:18:35.520 +documentation + +00:18:35.520 --> 00:18:38.320 +it puts a index at top at the top I + +00:18:38.320 --> 00:18:39.679 +usually just + +00:18:39.679 --> 00:18:42.000 +I usually turn that off it's easy to do + +00:18:42.000 --> 00:18:43.679 +that by putting a property at the top of + +00:18:43.679 --> 00:18:44.559 +your + +00:18:44.559 --> 00:18:46.880 +your org file but some people like to + +00:18:46.880 --> 00:18:48.559 +have an index + +00:18:48.559 --> 00:18:50.799 +but here you can see that it's generated + +00:18:50.799 --> 00:18:52.160 +pretty nicely and + +00:18:52.160 --> 00:18:55.200 +formatted snippets well + +00:18:55.200 --> 00:18:56.880 +put the diagram in there and then it's + +00:18:56.880 --> 00:18:58.240 +preserved + +00:18:58.240 --> 00:19:01.039 +it's preserved this literate programming + +00:19:01.039 --> 00:19:02.799 +syntax + +00:19:02.799 --> 00:19:04.960 +which is important because that's how we + +00:19:04.960 --> 00:19:06.480 +want to view the documentation that's + +00:19:06.480 --> 00:19:07.200 +what the no + +00:19:07.200 --> 00:19:10.559 +exports um + +00:19:10.559 --> 00:19:13.360 +property was was trying to maintain so + +00:19:13.360 --> 00:19:14.000 +that + +00:19:14.000 --> 00:19:16.080 +no exports means when you export do not + +00:19:16.080 --> 00:19:18.400 +try to tangle so that's + +00:19:18.400 --> 00:19:20.559 +hopefully that makes more sense now but + +00:19:20.559 --> 00:19:22.240 +now you can see all the documentation + +00:19:22.240 --> 00:19:26.080 +and I think it demonstrates a + +00:19:26.080 --> 00:19:29.919 +pretty useful feature that's inside of + +00:19:29.919 --> 00:19:33.520 +Emacs and and hopefully + +00:19:33.520 --> 00:19:35.039 +hopefully you'll have as much fun using + +00:19:35.039 --> 00:19:39.919 +that as I have + +00:19:39.919 --> 00:19:43.600 +so thanks |