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