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, 0 insertions, 1426 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 deleted file mode 100644 index 3179635f..00000000 --- a/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.vtt +++ /dev/null @@ -1,1426 +0,0 @@ -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 |