diff options
Diffstat (limited to '2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.sbv')
| -rw-r--r-- | 2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.sbv | 1425 |
1 files changed, 1425 insertions, 0 deletions
diff --git a/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.sbv b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.sbv new file mode 100644 index 00000000..6435d778 --- /dev/null +++ b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.sbv @@ -0,0 +1,1425 @@ +0:00:03.600,0:00:06.560 +hello + +0:00:04.400,0:00:08.400 +welcome to readme driven design in emacs + +0:00:06.560,0:00:10.800 +by adam aard + +0:00:08.400,0:00:12.559 +if you're a programmer you're accustomed + +0:00:10.800,0:00:13.759 +to putting a readme file at the root of + +0:00:12.559,0:00:16.400 +your project + +0:00:13.759,0:00:17.600 +and it's usually a markdown file but if + +0:00:16.400,0:00:20.720 +you use an org + +0:00:17.600,0:00:22.560 +more an org mode file instead you can + +0:00:20.720,0:00:24.400 +take advantage of the great features + +0:00:22.560,0:00:25.920 +that org mode provides including + +0:00:24.400,0:00:28.000 +literate programming + +0:00:25.920,0:00:31.840 +which lets you generate your source code + +0:00:28.000,0:00:34.719 +and markdown documentation dynamically + +0:00:31.840,0:00:37.120 +i want to walk you through a little bit + +0:00:34.719,0:00:39.440 +of what this looks like + +0:00:37.120,0:00:41.280 +when you start a project especially if + +0:00:39.440,0:00:43.320 +if you use something like github you + +0:00:41.280,0:00:47.039 +begin with an automatically generated + +0:00:43.320,0:00:50.239 +readme.md file so just delete that + +0:00:47.039,0:00:51.920 +and instead create a readme.org file + +0:00:50.239,0:00:54.800 +starting with an empty org file like you + +0:00:51.920,0:00:56.559 +see here you can begin + +0:00:54.800,0:00:59.440 +by recording important information about + +0:00:56.559,0:01:01.920 +your project goals you can add diagrams + +0:00:59.440,0:01:03.520 +code snippets to-do lists time tracking + +0:01:01.920,0:01:05.360 +and much more + +0:01:03.520,0:01:07.760 +i'm going to drop in some documentation + +0:01:05.360,0:01:10.840 +that i r that i've written about + +0:01:07.760,0:01:12.240 +about my project here so you can kind of + +0:01:10.840,0:01:15.280 +see + +0:01:12.240,0:01:17.119 +what this would look like + +0:01:15.280,0:01:20.320 +so as you can see i have a title and a + +0:01:17.119,0:01:23.840 +description and then a sub section + +0:01:20.320,0:01:25.520 +as well as some code snippets + +0:01:23.840,0:01:28.240 +and you can see that orgmo does a great + +0:01:25.520,0:01:31.280 +job of formatting lists and + +0:01:28.240,0:01:33.920 +code sections diagrams and so forth + +0:01:31.280,0:01:35.040 +it's good or it's as good or better than + +0:01:33.920,0:01:37.520 +markdown + +0:01:35.040,0:01:38.880 +but when you use it in the emacs you can + +0:01:37.520,0:01:40.479 +do a lot more + +0:01:38.880,0:01:43.360 +for example you can dynamically create + +0:01:40.479,0:01:45.200 +diagrams using graphviz + +0:01:43.360,0:01:46.560 +from a text description so if you go to + +0:01:45.200,0:01:49.439 +this source block here + +0:01:46.560,0:01:51.439 +and hit control c control c you'll see + +0:01:49.439,0:01:55.439 +that we generate a + +0:01:51.439,0:01:59.200 +diagram dynamically you can run + +0:01:55.439,0:02:00.799 +so you can run these code snippets in + +0:01:59.200,0:02:03.040 +place and get the results + +0:02:00.799,0:02:06.640 +to show up inside of your your file + +0:02:03.040,0:02:06.640 +which is a really powerful paradigm + +0:02:08.000,0:02:11.520 +but most important most importantly for + +0:02:10.640,0:02:14.800 +the + +0:02:11.520,0:02:17.200 +purposes my purpose is here + +0:02:14.800,0:02:19.520 +orgmo provides you the ability to do + +0:02:17.200,0:02:21.440 +literate programming + +0:02:19.520,0:02:23.200 +so take a quick look at this diagram + +0:02:21.440,0:02:25.360 +that i generated here + +0:02:23.200,0:02:27.520 +and gives you a quick overview of what i + +0:02:25.360,0:02:31.200 +mean by literate programming + +0:02:27.520,0:02:33.920 +and how i'm using it you can see + +0:02:31.200,0:02:34.720 +that we start with a readme.org file on + +0:02:33.920,0:02:36.879 +top + +0:02:34.720,0:02:37.920 +at this point we can do one of two + +0:02:36.879,0:02:41.280 +things + +0:02:37.920,0:02:42.720 +tangle or weave tangle is used to + +0:02:41.280,0:02:46.319 +describe the process of + +0:02:42.720,0:02:47.599 +generating source code while weave + +0:02:46.319,0:02:49.840 +is the process of generating + +0:02:47.599,0:02:51.920 +documentation these are terms that + +0:02:49.840,0:02:53.840 +donald knuth used + +0:02:51.920,0:02:55.519 +and he's the one that came up with the + +0:02:53.840,0:02:59.920 +idea of literate programming + +0:02:55.519,0:03:01.519 +in the early 1980s + +0:02:59.920,0:03:04.480 +but this is really all that there is to + +0:03:01.519,0:03:06.400 +it you just + +0:03:04.480,0:03:07.840 +who are simply using literate illiterate + +0:03:06.400,0:03:10.319 +source file + +0:03:07.840,0:03:11.680 +in this case the readme.org to generate + +0:03:10.319,0:03:15.680 +the rest of the project + +0:03:11.680,0:03:15.680 +the rest of the project files basically + +0:03:17.120,0:03:22.640 +so let's dig in to the details of how + +0:03:20.959,0:03:24.560 +this works + +0:03:22.640,0:03:26.159 +and i hope you hopefully you'll see how + +0:03:24.560,0:03:28.959 +cool this is + +0:03:26.159,0:03:31.120 +so returning to the file here let's + +0:03:28.959,0:03:32.080 +assume we have enough documentation now + +0:03:31.120,0:03:34.159 +that we want to get started + +0:03:32.080,0:03:35.519 +coding so maybe we'll just start with + +0:03:34.159,0:03:38.159 +like a hello world + +0:03:35.519,0:03:41.519 +app just so we can make sure that our + +0:03:38.159,0:03:47.120 +environment is set up correctly + +0:03:41.519,0:03:49.519 +so let's get started with a code block + +0:03:47.120,0:03:50.319 +so i created a little snippet to help me + +0:03:49.519,0:03:52.239 +add + +0:03:50.319,0:03:53.599 +a source block for literate programming + +0:03:52.239,0:03:56.959 +quickly + +0:03:53.599,0:03:58.799 +and there's not much to it + +0:03:56.959,0:04:01.599 +but there is some important annotations + +0:03:58.799,0:04:04.080 +here so there's + +0:04:01.599,0:04:05.200 +excuse me there's a there's a property + +0:04:04.080,0:04:09.360 +called tangle + +0:04:05.200,0:04:13.280 +and that takes a value of a file name + +0:04:09.360,0:04:16.560 +and then there's also a no web property + +0:04:13.280,0:04:16.560 +called no export + +0:04:18.880,0:04:22.000 +and basically + +0:04:23.759,0:04:28.639 +basically the no export will explain + +0:04:26.800,0:04:32.080 +that a little bit + +0:04:28.639,0:04:33.919 +more later um it has has to do with how + +0:04:32.080,0:04:37.600 +the tangling + +0:04:33.919,0:04:39.280 +is uh done in the tangle step versus the + +0:04:37.600,0:04:41.199 +weave step and i'll explain that a + +0:04:39.280,0:04:45.199 +little bit more but the tangle + +0:04:41.199,0:04:48.320 +field just simply tells tells uh + +0:04:45.199,0:04:50.320 +emacs where it needs to generate the + +0:04:48.320,0:04:53.280 +main.go file and where it needs to put + +0:04:50.320,0:04:53.280 +it on the file system + +0:04:55.360,0:04:59.040 +uh you'll you'll notice that we we're + +0:04:57.680,0:05:01.440 +going to use go + +0:04:59.040,0:05:02.160 +that's just the language that i've been + +0:05:01.440,0:05:05.360 +using + +0:05:02.160,0:05:07.360 +the most lately uh but + +0:05:05.360,0:05:08.400 +this programming strategy is language + +0:05:07.360,0:05:12.080 +agnostic + +0:05:08.400,0:05:14.720 +you could use any language or any mix + +0:05:12.080,0:05:16.560 +of languages you could create some files + +0:05:14.720,0:05:19.520 +in python some files and go + +0:05:16.560,0:05:21.520 +some files in in lisp or whatever you + +0:05:19.520,0:05:24.720 +want + +0:05:21.520,0:05:28.000 +and so but let's + +0:05:24.720,0:05:29.440 +uh let's create just a little hello + +0:05:28.000,0:05:32.320 +world + +0:05:29.440,0:05:33.520 +let's use another snippet here to + +0:05:32.320,0:05:36.560 +generate + +0:05:33.520,0:05:39.840 +the basics of a go program + +0:05:36.560,0:05:39.840 +so i'm just going to print + +0:05:40.240,0:05:42.960 +hello world + +0:05:44.960,0:05:48.240 +so that's and then + +0:05:48.560,0:05:55.280 +let's make it a section in our + +0:05:52.320,0:05:56.400 +file so now you can see we've got this + +0:05:55.280,0:05:59.600 +snippet + +0:05:56.400,0:06:01.600 +um when you have a source block in + +0:05:59.600,0:06:02.880 +inside of org mode you can easily pop + +0:06:01.600,0:06:04.960 +into a + +0:06:02.880,0:06:07.680 +language specific buffer by typing + +0:06:04.960,0:06:10.240 +control c single quote + +0:06:07.680,0:06:12.160 +so you can see now i have a a go a + +0:06:10.240,0:06:14.240 +buffer that's in go mode + +0:06:12.160,0:06:15.520 +and gives you all the ability to edit + +0:06:14.240,0:06:18.800 +like you would + +0:06:15.520,0:06:20.800 +normally if you hit ctrl c + +0:06:18.800,0:06:22.639 +single quote again then it goes back and + +0:06:20.800,0:06:25.280 +any changes you + +0:06:22.639,0:06:26.160 +make would will be updated there but you + +0:06:25.280,0:06:28.000 +can do quite a bit + +0:06:26.160,0:06:29.199 +just inside of here too there's quite a + +0:06:28.000,0:06:32.400 +bit of + +0:06:29.199,0:06:32.400 +language specific + +0:06:33.360,0:06:36.880 +functionality just in place and so you + +0:06:35.440,0:06:38.080 +don't always have to go over to a + +0:06:36.880,0:06:42.319 +separate buffer + +0:06:38.080,0:06:44.319 +but it's a it's a nice option sometimes + +0:06:42.319,0:06:46.720 +but now that you have the code in here + +0:06:44.319,0:06:48.560 +you're going to want to run it + +0:06:46.720,0:06:50.240 +but right now it just lives here in this + +0:06:48.560,0:06:52.160 +documentation + +0:06:50.240,0:06:53.840 +so you need to get a copy of it into a + +0:06:52.160,0:06:57.440 +separate file + +0:06:53.840,0:07:01.360 +and that's the tangle process that you + +0:06:57.440,0:07:03.360 +you need to follow there so i'm gonna + +0:07:01.360,0:07:05.280 +drop in a little bit more doc a little + +0:07:03.360,0:07:08.960 +bit more + +0:07:05.280,0:07:08.960 +documentation really quick here + +0:07:12.240,0:07:21.520 +okay all right so just kind of as a + +0:07:17.360,0:07:24.800 +kind of as a side note i like to follow + +0:07:21.520,0:07:26.639 +this process uh whenever having whenever + +0:07:24.800,0:07:28.880 +i have an operation to perform i + +0:07:26.639,0:07:31.680 +i'd like to document it here with a + +0:07:28.880,0:07:33.280 +snippet that can be executed in line + +0:07:31.680,0:07:34.639 +then i don't have to leave org mode and + +0:07:33.280,0:07:36.800 +i don't have to try to remember what i + +0:07:34.639,0:07:38.960 +did later so instead of just + +0:07:36.800,0:07:40.319 +trying to do an operation the first time + +0:07:38.960,0:07:41.680 +i do something i take the + +0:07:40.319,0:07:43.440 +take the time to figure out what it is + +0:07:41.680,0:07:44.879 +and document it and so then it's + +0:07:43.440,0:07:48.400 +recorded + +0:07:44.879,0:07:49.120 +and so here we find that to do a tangle + +0:07:48.400,0:07:51.680 +operation + +0:07:49.120,0:07:52.560 +you run the command or babel tangled + +0:07:51.680,0:07:55.840 +which is a + +0:07:52.560,0:07:59.199 +e-list command so if you hit ctrl c + +0:07:55.840,0:08:00.080 +ctrl c to run it in place you get the + +0:07:59.199,0:08:02.720 +result + +0:08:00.080,0:08:03.759 +of main dot go which basically is + +0:08:02.720,0:08:07.680 +telling us that + +0:08:03.759,0:08:11.039 +we've tangled one file called main.go + +0:08:07.680,0:08:14.000 +and you can see that that's true + +0:08:11.039,0:08:14.400 +if you go to the file system and you + +0:08:14.000,0:08:17.840 +look + +0:08:14.400,0:08:20.960 +so now in uh in our demo directory + +0:08:17.840,0:08:22.479 +we have a readme.org we have that png + +0:08:20.960,0:08:23.440 +that we generated but we also have a + +0:08:22.479,0:08:26.080 +main.go + +0:08:23.440,0:08:27.759 +and if you if you visit that file you'll + +0:08:26.080,0:08:29.280 +see that it's just the source code that + +0:08:27.759,0:08:31.039 +was in our documentation which is + +0:08:29.280,0:08:32.880 +exactly what we expected and what we + +0:08:31.039,0:08:36.000 +wanted so that's good + +0:08:32.880,0:08:36.000 +so if we return to + +0:08:36.560,0:08:39.919 +to where we are at + +0:08:41.120,0:08:44.640 +now we're we're at the point where we + +0:08:42.959,0:08:45.760 +have a file on the file system so now we + +0:08:44.640,0:08:48.959 +need + +0:08:45.760,0:08:53.600 +um now we need to build it and to + +0:08:48.959,0:08:57.040 +run it so let's follow the same + +0:08:53.600,0:08:58.720 +philosophy where let's document + +0:08:57.040,0:09:00.160 +these operations that we're going to + +0:08:58.720,0:09:03.920 +perform + +0:09:00.160,0:09:03.920 +so i'm dropping in a + +0:09:04.560,0:09:11.200 +a build instruction section and a run + +0:09:07.839,0:09:11.200 +instruction section + +0:09:13.360,0:09:17.839 +so as you can see here we have a little + +0:09:15.279,0:09:20.000 +a bash source block + +0:09:17.839,0:09:22.000 +and another batch source block this one + +0:09:20.000,0:09:25.440 +compiles the go build command is what + +0:09:22.000,0:09:26.880 +compiles a file and then + +0:09:25.440,0:09:29.519 +the file that gets generated should be + +0:09:26.880,0:09:29.519 +called demo + +0:09:30.080,0:09:34.000 +and uh so we just run it here so if if i + +0:09:32.959,0:09:37.839 +type control c + +0:09:34.000,0:09:40.640 +control c we get an empty results block + +0:09:37.839,0:09:41.360 +when you compile things no news is good + +0:09:40.640,0:09:44.399 +news + +0:09:41.360,0:09:46.560 +so it means there's no errors so + +0:09:44.399,0:09:48.000 +presumably we've created an executable + +0:09:46.560,0:09:51.440 +that's called demo + +0:09:48.000,0:09:54.560 +so let's uh + +0:09:51.440,0:09:57.519 +let's look again at the file system and + +0:09:54.560,0:09:57.519 +regenerate + +0:10:02.480,0:10:07.200 +yep and what we have here is a demo + +0:10:05.760,0:10:07.760 +executable which is exactly what we + +0:10:07.200,0:10:12.079 +wanted + +0:10:07.760,0:10:14.160 +so let's go back + +0:10:12.079,0:10:16.079 +so now we should be able to run it so + +0:10:14.160,0:10:20.320 +ctrl c ctrl c + +0:10:16.079,0:10:20.320 +and we get hello world as a result + +0:10:20.399,0:10:26.560 +which was exactly what we were expecting + +0:10:23.440,0:10:30.240 +so that's already pretty cool + +0:10:26.560,0:10:30.240 +you can you can do that much + +0:10:30.839,0:10:34.560 +um but + +0:10:33.040,0:10:37.839 +that's really just kind of the tip of + +0:10:34.560,0:10:41.040 +the iceberg to uh to really + +0:10:37.839,0:10:43.440 +kind of um + +0:10:41.040,0:10:46.160 +use the more impressive features of + +0:10:43.440,0:10:49.519 +literate programming we need to uh + +0:10:46.160,0:10:49.519 +we need to do a little bit more + +0:10:49.920,0:10:55.519 +so or at least + +0:10:53.200,0:10:56.480 +at least really to get the full benefit + +0:10:55.519,0:10:59.120 +of it then + +0:10:56.480,0:10:59.120 +we need to do + +0:10:59.600,0:11:06.320 +add some sections that will cause uh + +0:11:02.959,0:11:06.720 +emacs to have to to tangle or assemble + +0:11:06.320,0:11:09.760 +this + +0:11:06.720,0:11:13.120 +this file from different pieces so + +0:11:09.760,0:11:16.720 +imagine that we wanted to take this file + +0:11:13.120,0:11:19.120 +and maybe kind of templatize it + +0:11:16.720,0:11:21.279 +so using literature programming syntax + +0:11:19.120,0:11:24.399 +this angle bracket syntax + +0:11:21.279,0:11:29.360 +let's say that we want to create an in + +0:11:24.399,0:11:32.399 +imports section + +0:11:29.360,0:11:35.040 +in a functions section + +0:11:32.399,0:11:36.240 +and then maybe just a main section and + +0:11:35.040,0:11:37.920 +we'll get rid of this + +0:11:36.240,0:11:39.760 +so now you see we've created something + +0:11:37.920,0:11:42.000 +that looks a little bit like a + +0:11:39.760,0:11:42.880 +like a template or a scaffolding or + +0:11:42.000,0:11:46.000 +outline + +0:11:42.880,0:11:48.399 +for what what our file is going to be it + +0:11:46.000,0:11:50.800 +looks a little bit like pseudocode + +0:11:48.399,0:11:52.399 +and what we're going to have literate + +0:11:50.800,0:11:54.800 +programming do + +0:11:52.399,0:11:56.639 +is dynamically insert those things into + +0:11:54.800,0:12:00.079 +those slots + +0:11:56.639,0:12:03.200 +so the first thing we need to do + +0:12:00.079,0:12:08.079 +is so let's create a section + +0:12:03.200,0:12:09.519 +maybe called say hello so we want + +0:12:08.079,0:12:12.720 +we want to add some functionality that + +0:12:09.519,0:12:15.680 +makes our program say hello + +0:12:12.720,0:12:17.600 +so using a different snippet that i have + +0:12:15.680,0:12:20.800 +for creating something + +0:12:17.600,0:12:24.079 +that i call like a literate section + +0:12:20.800,0:12:26.000 +um basically we create a + +0:12:24.079,0:12:27.839 +another source block that's almost the + +0:12:26.000,0:12:31.040 +same as the one for the file but it's + +0:12:27.839,0:12:31.680 +it just has a few differences so say we + +0:12:31.040,0:12:34.160 +want to + +0:12:31.680,0:12:36.639 +drop code into the import section and we + +0:12:34.160,0:12:39.120 +want it to be in go + +0:12:36.639,0:12:40.720 +here we use the same noed no web no + +0:12:39.120,0:12:43.200 +export syntax + +0:12:40.720,0:12:44.560 +but then we've added this no web refs + +0:12:43.200,0:12:48.240 +imports + +0:12:44.560,0:12:51.120 +and this ties that slot + +0:12:48.240,0:12:53.760 +basically to this reference it tells + +0:12:51.120,0:12:56.880 +emacs that when you tangle + +0:12:53.760,0:12:58.240 +we want to stick whatever's in here in + +0:12:56.880,0:13:02.079 +that spot + +0:12:58.240,0:13:03.279 +so you skip the tangle file name section + +0:13:02.079,0:13:04.240 +because you're not actually creating a + +0:13:03.279,0:13:06.160 +file name you're + +0:13:04.240,0:13:07.680 +you're putting information into an + +0:13:06.160,0:13:10.720 +existing file + +0:13:07.680,0:13:13.680 +so here we would just add the fmt + +0:13:10.720,0:13:13.680 +for the imports + +0:13:14.399,0:13:22.240 +so let's add another section for uh + +0:13:18.839,0:13:25.519 +functions and let's create a + +0:13:22.240,0:13:30.240 +let's just create a function called + +0:13:25.519,0:13:32.839 +say hello that + +0:13:30.240,0:13:34.000 +doesn't have any arguments no return + +0:13:32.839,0:13:35.760 +types + +0:13:34.000,0:13:37.440 +all it does is kind of pretty much the + +0:13:35.760,0:13:39.199 +same thing as we did before + +0:13:37.440,0:13:41.360 +just print something but let's just say + +0:13:39.199,0:13:45.760 +hello + +0:13:41.360,0:13:49.519 +emacs comp this time + +0:13:45.760,0:13:51.040 +okay so now we have a function and now + +0:13:49.519,0:13:52.720 +the function won't do anything unless we + +0:13:51.040,0:13:56.000 +invoke it so let's do + +0:13:52.720,0:13:59.920 +one last literate section + +0:13:56.000,0:14:03.519 +called main make that go + +0:13:59.920,0:14:06.399 +source block and then let's + +0:14:03.519,0:14:06.399 +just invoke + +0:14:06.560,0:14:13.360 +that that function + +0:14:10.320,0:14:15.600 +so now you can see that we've got + +0:14:13.360,0:14:17.199 +our scaffolding scaffolding kind of + +0:14:15.600,0:14:20.079 +outline and then we have + +0:14:17.199,0:14:21.360 +the sections that we want to get tangled + +0:14:20.079,0:14:25.440 +or inserted + +0:14:21.360,0:14:27.199 +so i i've kind of used this syntax + +0:14:25.440,0:14:28.560 +it's it's kind of borrowed from + +0:14:27.199,0:14:30.320 +literature programming a little bit with + +0:14:28.560,0:14:32.480 +a plus equals so really it's just saying + +0:14:30.320,0:14:35.760 +that i want to append + +0:14:32.480,0:14:37.600 +this item into the import section so + +0:14:35.760,0:14:39.839 +it's really just to make a little bit + +0:14:37.600,0:14:41.519 +more clear what's going on + +0:14:39.839,0:14:43.519 +when you generate documentation you + +0:14:41.519,0:14:46.160 +won't see these + +0:14:43.519,0:14:49.360 +these these particular property + +0:14:46.160,0:14:51.440 +annotations and so you won't know + +0:14:49.360,0:14:53.839 +immediately that this section goes in + +0:14:51.440,0:14:55.440 +the imports area and so i usually put + +0:14:53.839,0:14:57.760 +a little bit of documentation on top + +0:14:55.440,0:15:01.120 +there so that it's easy to see + +0:14:57.760,0:15:03.040 +and you would probably if this was very + +0:15:01.120,0:15:06.399 +complicated you'd put some + +0:15:03.040,0:15:07.360 +documentation above to explain what you + +0:15:06.399,0:15:10.320 +were doing + +0:15:07.360,0:15:10.320 +maybe right here + +0:15:11.519,0:15:15.040 +you could you could picture yourself + +0:15:13.279,0:15:17.440 +maybe explaining + +0:15:15.040,0:15:18.079 +a complicated algorithm or something up + +0:15:17.440,0:15:21.120 +here + +0:15:18.079,0:15:22.959 +and having a nice way to document it + +0:15:21.120,0:15:25.600 +so now that we've got that here in the + +0:15:22.959,0:15:27.040 +documentation we need to figure out + +0:15:25.600,0:15:29.920 +we need to make sure that it's going to + +0:15:27.040,0:15:33.519 +tangle properly so your best friend + +0:15:29.920,0:15:35.680 +at this point is is uh + +0:15:33.519,0:15:38.240 +is a keyboard shortcut that lets you + +0:15:35.680,0:15:38.959 +preview the tangled operation so if you + +0:15:38.240,0:15:42.560 +say control + +0:15:38.959,0:15:45.120 +c control v control v + +0:15:42.560,0:15:46.480 +it will create a new buffer with the + +0:15:45.120,0:15:49.360 +tangled + +0:15:46.480,0:15:50.639 +contents and so you can see here that + +0:15:49.360,0:15:53.199 +the fmt + +0:15:50.639,0:15:54.720 +import went to the right place that + +0:15:53.199,0:15:56.160 +function went to the right place the + +0:15:54.720,0:15:58.480 +function invocation went to the right + +0:15:56.160,0:16:01.279 +place and so we're feeling good + +0:15:58.480,0:16:02.800 +you can nest these things many layers + +0:16:01.279,0:16:04.800 +deep + +0:16:02.800,0:16:07.199 +actually so like if you came into the + +0:16:04.800,0:16:10.160 +say hello function you could add + +0:16:07.199,0:16:10.160 +more sections + +0:16:10.560,0:16:13.759 +you know and it gets and it'll go + +0:16:12.160,0:16:15.680 +through and it'll + +0:16:13.759,0:16:16.959 +keep track of all that and tangle it for + +0:16:15.680,0:16:18.320 +you so you really get a lot of freedom + +0:16:16.959,0:16:19.600 +and flexibility for how you want to + +0:16:18.320,0:16:22.320 +document things + +0:16:19.600,0:16:25.839 +by doing this so now that we've + +0:16:22.320,0:16:28.639 +previewed it and we feel good about it + +0:16:25.839,0:16:31.440 +we need to uh we need to tangle so we + +0:16:28.639,0:16:34.480 +get the file on the file system + +0:16:31.440,0:16:37.199 +so ctrl c ctrl c and + +0:16:34.480,0:16:37.920 +get just main.go comes back again + +0:16:37.199,0:16:40.959 +control c + +0:16:37.920,0:16:43.839 +control c and no errors come back + +0:16:40.959,0:16:45.600 +and then if we did this right when we + +0:16:43.839,0:16:47.199 +when we run this we should get hello + +0:16:45.600,0:16:51.199 +emacs comp so ctrl c + +0:16:47.199,0:16:54.800 +ctrl c hello emacs comp + +0:16:51.199,0:16:57.120 +so i uh + +0:16:54.800,0:16:58.240 +i think that's pretty pretty cool + +0:16:57.120,0:17:00.160 +actually so we've got + +0:16:58.240,0:17:02.399 +kind of the breadcrumbs of the process + +0:17:00.160,0:17:05.520 +we've gone through to get to this point + +0:17:02.399,0:17:08.000 +this initial this initial + +0:17:05.520,0:17:09.919 +document that has some tangling in it we + +0:17:08.000,0:17:12.799 +have documentation for how to tangle + +0:17:09.919,0:17:14.079 +how to build how to run it's we've + +0:17:12.799,0:17:17.760 +really built a nice + +0:17:14.079,0:17:20.160 +foundation for + +0:17:17.760,0:17:21.439 +moving forward on our project and a nice + +0:17:20.160,0:17:23.280 +way of breaking things out and + +0:17:21.439,0:17:27.120 +documenting further + +0:17:23.280,0:17:30.559 +the last piece that we need to + +0:17:27.120,0:17:34.799 +take care of is the weave that i + +0:17:30.559,0:17:38.640 +that's i showed you in the diagram above + +0:17:34.799,0:17:41.760 +so one more time we'll drop in + +0:17:38.640,0:17:42.400 +some documentation so this time on how + +0:17:41.760,0:17:44.400 +to weave + +0:17:42.400,0:17:47.520 +so it's really just an export function + +0:17:44.400,0:17:49.280 +it's not there's not a separate weave + +0:17:47.520,0:17:50.640 +command going on here we're just going + +0:17:49.280,0:17:52.799 +to export + +0:17:50.640,0:17:55.200 +what we've got here into a markdown + +0:17:52.799,0:17:57.440 +format so we're using org + +0:17:55.200,0:17:58.880 +gfm export to markdown which is the + +0:17:57.440,0:18:02.160 +github style + +0:17:58.880,0:18:05.440 +markdown you can use the other just + +0:18:02.160,0:18:10.320 +more standard type as well so hit ctrl c + +0:18:05.440,0:18:15.280 +ctrl c now you see we've got a readme + +0:18:10.320,0:18:17.440 +file and if you look + +0:18:15.280,0:18:19.120 +in the file system we've got that right + +0:18:17.440,0:18:23.120 +there and so + +0:18:19.120,0:18:29.840 +if you go to something like ghostwriter + +0:18:23.120,0:18:29.840 +and open that file + +0:18:31.679,0:18:35.520 +now you can see that it's generated some + +0:18:34.559,0:18:38.320 +documentation + +0:18:35.520,0:18:39.679 +it puts a index at top at the top i + +0:18:38.320,0:18:42.000 +usually just + +0:18:39.679,0:18:43.679 +i usually turn that off it's easy to do + +0:18:42.000,0:18:44.559 +that by putting a property at the top of + +0:18:43.679,0:18:46.880 +your + +0:18:44.559,0:18:48.559 +your org file but some people like to + +0:18:46.880,0:18:50.799 +have an index + +0:18:48.559,0:18:52.160 +but here you can see that it's generated + +0:18:50.799,0:18:55.200 +pretty nicely and + +0:18:52.160,0:18:56.880 +formatted snippets well + +0:18:55.200,0:18:58.240 +put the diagram in there and then it's + +0:18:56.880,0:19:01.039 +preserved + +0:18:58.240,0:19:02.799 +it's preserved this literate programming + +0:19:01.039,0:19:04.960 +syntax + +0:19:02.799,0:19:06.480 +which is important because that's how we + +0:19:04.960,0:19:07.200 +want to view the documentation that's + +0:19:06.480,0:19:10.559 +what the no + +0:19:07.200,0:19:13.360 +exports um + +0:19:10.559,0:19:14.000 +property was was trying to maintain so + +0:19:13.360,0:19:16.080 +that + +0:19:14.000,0:19:18.400 +no exports means when you export do not + +0:19:16.080,0:19:20.559 +try to tangle so that's + +0:19:18.400,0:19:22.240 +hopefully that makes more sense now but + +0:19:20.559,0:19:26.080 +now you can see all the documentation + +0:19:22.240,0:19:29.919 +and i think it demonstrates a + +0:19:26.080,0:19:33.520 +pretty useful feature that's inside of + +0:19:29.919,0:19:35.039 +emacs and and hopefully + +0:19:33.520,0:19:39.840 +hopefully you'll have as much fun using + +0:19:35.039,0:19:39.840 +that as i have + +0:19:39.919,0:19:43.600 +so thanks + |