diff options
| -rw-r--r-- | 2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt | 297 |
1 files changed, 125 insertions, 172 deletions
diff --git a/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt index 72962cf1..78d044e8 100644 --- a/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt +++ b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt @@ -12,11 +12,8 @@ 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:10.800 --> 00:00:13.759 +to putting a README file at the root of your project. 00:00:13.759 --> 00:00:15.845 It's usually a Markdown file @@ -25,14 +22,13 @@ It's usually a Markdown file But if you use an Org Mode file instead, 00:00:20.579 --> 00:00:22.560 -you can take advantage of the -great features +you can take advantage of the great features -00:00:22.560 --> 00:00:24.400 -that Org Mode provides, including +00:00:22.560 --> 00:00:24.898 +that Org Mode provides, -00:00:24.400 --> 00:00:25.920 -literate programming, +00:00:24.898 --> 00:00:25.920 +including literate programming, 00:00:25.920 --> 00:00:28.000 which lets you generate your source code @@ -46,20 +42,21 @@ 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:37.120 --> 00:00:39.607 +When you start a project, -00:00:39.440 --> 00:00:41.280 -if you use something like Github you +00:00:39.607 --> 00:00:41.179 +especially if you use something like Github -00:00:41.280 --> 00:00:43.320 -begin with an automatically generated +00:00:41.179 --> 00:00:45.913 +you begin with an automatically generated +README.md file. -00:00:43.320 --> 00:00:47.039 -README.md file. So just delete that +00:00:45.913 --> 00:00:47.039 +So just delete that 00:00:47.039 --> 00:00:50.239 -and instead create a README.org file. +and instead, create a README.org file. 00:00:50.239 --> 00:00:51.712 Starting with an empty Org file, @@ -67,23 +64,21 @@ Starting with an empty Org file, 00:00:51.712 --> 00:00:54.800 like you see here, you can begin -00:00:54.800 --> 00:00:56.559 -by recording important information about - -00:00:56.559 --> 00:00:59.440 -your project goals. You can add diagrams, +00:00:54.800 --> 00:00:56.295 +by recording important information -00:00:59.440 --> 00:01:01.920 -code snippets, to-do lists, time tracking +00:00:56.295 --> 00:00:59.440 +about your project goals. You can add diagrams, -00:01:01.920 --> 00:01:03.520 -and much more. +00:00:59.440 --> 00:01:03.520 +code snippets, to-do lists, time +tracking, and much more. 00:01:03.520 --> 00:01:05.360 I'm going to drop in some documentation 00:01:05.360 --> 00:01:07.760 -that that I've written about +that I've written about 00:01:07.760 --> 00:01:12.240 about my project here, so you can see @@ -91,20 +86,20 @@ about my project here, so you can see 00:01:12.240 --> 00:01:15.280 what this would look like. -00:01:15.280 --> 00:01:17.119 -As you can see, I have a title, and a +00:01:15.280 --> 00:01:17.870 +As you can see, I have a title, -00:01:17.119 --> 00:01:20.320 -description, and then a subsection +00:01:17.870 --> 00:01:20.320 +and a description, and then a subsection 00:01:20.320 --> 00:01:23.840 as well as some code snippets. -00:01:23.840 --> 00:01:25.520 -You can see that Org Mode does a great +00:01:23.840 --> 00:01:25.210 +You can see that Org Mode does -00:01:25.520 --> 00:01:28.240 -job of formatting lists, +00:01:25.210 --> 00:01:28.240 +a great job of formatting lists, 00:01:28.240 --> 00:01:31.280 code sections, diagrams, and so forth. @@ -113,34 +108,32 @@ code sections, diagrams, and so forth. It's as good or better than Markdown, 00:01:35.040 --> 00:01:37.179 -but when you use it in Emacs +but when you use it in Emacs, 00:01:37.179 --> 00:01:38.880 you can do a lot more. -00:01:38.880 --> 00:01:40.479 +00:01:38.880 --> 00:01:43.360 For example, you can dynamically create - -00:01:40.479 --> 00:01:43.360 diagrams using Graphviz -00:01:43.360 --> 00:01:45.200 -from a text description. If you go to - -00:01:45.200 --> 00:01:46.560 -this source block here +00:01:43.360 --> 00:01:45.553 +from a text description. -00:01:46.560 --> 00:01:49.439 -and hit C-c C-c, you'll see +00:01:45.553 --> 00:01:48.266 +If you go to this source block here +and hit C-c C-c, -00:01:49.439 --> 00:01:52.979 -that we generate a diagram dynamically +00:01:48.266 --> 00:01:52.979 +you'll see that we generate a diagram +dynamically. -00:01:55.439 --> 00:01:59.200 +00:01:55.439 --> 00:02:00.519 You can run these code snippets in +place -00:01:59.200 --> 00:02:00.799 -place and get the results +00:02:00.519 --> 00:02:00.799 +and get the results 00:02:00.799 --> 00:02:03.040 to show up inside of your file, @@ -148,17 +141,11 @@ to show up inside of your file, 00:02:03.040 --> 00:02:08.000 which is a really powerful paradigm. -00:02:08.000 --> 00:02:10.640 -But most importantly, for +00:02:08.000 --> 00:02:14.800 +But most importantly, for my purposes here, -00:02:10.640 --> 00:02:14.800 -my purposes here, - -00:02:14.800 --> 00:02:17.200 -Org Mode provides you the ability to do - -00:02:17.200 --> 00:02:19.520 -literate programming. +00:02:14.800 --> 00:02:19.520 +Org Mode provides you the ability to do literate programming. 00:02:19.520 --> 00:02:21.440 So take a quick look at this diagram @@ -166,53 +153,46 @@ So take a quick look at this diagram 00:02:21.440 --> 00:02:23.200 that I generated here. -00:02:23.200 --> 00:02:25.312 -It gives you a quick overview of what - -00:02:25.312 --> 00:02:27.520 -I mean by literate programming - -00:02:27.520 --> 00:02:31.200 -and how I'm using it. You can see +00:02:23.200 --> 00:02:25.912 +It gives you a quick overview -00:02:31.200 --> 00:02:34.720 -that we start with a README.org file -on top. +00:02:25.912 --> 00:02:27.520 +of what I mean by literate programming -00:02:34.720 --> 00:02:37.920 -At this point, we can do one of two -things: +00:02:27.520 --> 00:02:30.973 +and how I'm using it. -00:02:37.920 --> 00:02:41.280 -tangle or weave. Tangle is used to +00:02:30.973 --> 00:02:34.720 +You can see that we start with a README.org file on top. -00:02:41.280 --> 00:02:42.720 -describe the process of +00:02:34.720 --> 00:02:40.501 +At this point, we can do one of two things: +tangle or weave. -00:02:42.720 --> 00:02:46.319 -generating source code, while weave +00:02:40.501 --> 00:02:43.611 +Tangle is used to describe the process -00:02:46.319 --> 00:02:47.599 -is the process of generating +00:02:43.611 --> 00:02:45.463 +of generating source code, -00:02:47.599 --> 00:02:49.840 -documentation. These are terms that +00:02:45.463 --> 00:02:48.495 +while weave is the process of generating +documentation. -00:02:49.840 --> 00:02:51.920 -Donald Knuth used. +00:02:48.495 --> 00:02:51.920 +These are terms that Donald Knuth used. -00:02:51.920 --> 00:02:53.840 -He's the one that came up with the +00:02:51.920 --> 00:02:53.388 +He's the one that came up -00:02:53.840 --> 00:02:55.519 -idea of literate programming +00:02:53.388 --> 00:02:55.519 +with the idea of literate programming 00:02:55.519 --> 00:02:59.920 in the early 1980s. 00:02:59.920 --> 00:03:01.945 -But this is really all that there is to -it. +But this is really all that there is to it. 00:03:01.945 --> 00:03:05.412 You just... You are simply @@ -220,32 +200,26 @@ You just... You are simply 00:03:05.412 --> 00:03:07.840 using a literate source file, -00:03:07.840 --> 00:03:10.319 -in this case the README.org, to generate +00:03:07.840 --> 00:03:10.575 +in this case the README.org, -00:03:11.680 --> 00:03:17.120 -the rest of the project files, basically. +00:03:10.575 --> 00:03:17.120 +to generate the rest of the project files, basically. 00:03:17.120 --> 00:03:22.640 -So let's dig in to the details of how -this works. +So let's dig in to the details of how this works. -00:03:22.640 --> 00:03:24.560 -I hope you... Hopefully you'll see how - -00:03:24.560 --> 00:03:26.159 -cool this is. +00:03:22.640 --> 00:03:26.159 +I hope you... Hopefully you'll see how cool this is. 00:03:26.159 --> 00:03:27.545 So returning to the file here. 00:03:27.545 --> 00:03:31.120 -Let's assume we have enough -documentation now, +Let's assume we have enough documentation now, 00:03:31.120 --> 00:03:32.679 -that we want to get started -coding. +that we want to get started coding. 00:03:32.679 --> 00:03:34.159 So maybe we'll just start with @@ -265,46 +239,38 @@ Let's get started with a code block. 00:03:47.120 --> 00:03:49.519 So I created a little snippet to help me -00:03:49.519 --> 00:03:51.612 -add a source block for +00:03:49.519 --> 00:03:51.326 +add a source block -00:03:51.612 --> 00:03:53.599 -literate programming quickly. +00:03:51.326 --> 00:03:53.599 +for literate programming quickly. 00:03:53.599 --> 00:03:56.959 There's not much to it, 00:03:56.959 --> 00:03:59.479 -but there are some important annotations -here. - -00:04:01.599 --> 00:04:04.080 -Excuse me. There's a property +but there are some important annotations here. -00:04:04.080 --> 00:04:05.200 -called :tangle +00:04:01.599 --> 00:04:05.200 +Excuse me. There's a property called :tangle 00:04:05.200 --> 00:04:09.360 and that takes a value of a file name. -00:04:09.360 --> 00:04:13.280 -Then there's also a :noweb property - -00:04:13.280 --> 00:04:18.880 -called no-export. +00:04:09.360 --> 00:04:18.880 +Then there's also a :noweb property called no-export. 00:04:23.759 --> 00:04:26.800 Basically, the noexport--we'll explain 00:04:26.800 --> 00:04:29.645 -that a little bit more later +that a little bit more later... 00:04:29.645 --> 00:04:32.080 It has to do with how 00:04:32.080 --> 00:04:36.845 -the tangling is done in the tangle -step +the tangling is done in the tangle step 00:04:36.845 --> 00:04:38.479 versus the weave step. @@ -312,29 +278,27 @@ versus the weave step. 00:04:38.479 --> 00:04:40.212 I'll explain that a little bit more. -00:04:40.212 --> 00:04:45.199 +00:04:40.212 --> 00:04:46.719 But the tangle field just simply tells +Emacs -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:46.719 --> 00:04:48.320 +where it needs to generate the -00:04:50.320 --> 00:04:55.360 -it on the file system. +00:04:48.320 --> 00:04:49.951 +main.go file -00:04:55.360 --> 00:04:57.680 -You'll notice that we we're +00:04:49.951 --> 00:04:55.360 +and where it needs to put it on the file system. -00:04:57.680 --> 00:04:59.040 -going to use Go. +00:04:55.360 --> 00:04:59.040 +You'll notice that we're going to use Go. -00:04:59.040 --> 00:05:01.440 -That's just the language that I've been +00:04:59.040 --> 00:05:01.578 +That's just the language -00:05:01.440 --> 00:05:03.379 -using the most lately, +00:05:01.578 --> 00:05:03.379 +that I've been using the most lately, 00:05:03.379 --> 00:05:06.845 but this programming strategy @@ -348,11 +312,12 @@ You could use any language 00:05:11.279 --> 00:05:13.145 or any mix of languages. -00:05:13.145 --> 00:05:14.720 +00:05:13.145 --> 00:05:15.377 You could create some files +in Python, -00:05:14.720 --> 00:05:16.560 -in Python, some files in Go, +00:05:15.377 --> 00:05:16.560 +some files in Go, 00:05:16.560 --> 00:05:19.179 some files in Lisp, @@ -361,8 +326,7 @@ some files in Lisp, or whatever you want. 00:05:24.720 --> 00:05:29.440 -Let's create just a little -Hello World. +Let's create just a little Hello World. 00:05:29.440 --> 00:05:31.379 Let's use another snippet here @@ -370,33 +334,22 @@ Let's use another snippet here 00:05:31.379 --> 00:05:36.560 to generate the basics of a Go program. -00:05:36.560 --> 00:05:40.240 -I'm just going to print +00:05:36.560 --> 00:05:44.960 +I'm just going to print Hello World. -00:05:40.240 --> 00:05:44.960 -Hello World. +00:05:44.960 --> 00:05:52.779 +So that's... And then let's make it a section in our file. -00:05:44.960 --> 00:05:48.560 -So that's... And then +00:05:52.779 --> 00:05:56.400 +So now you can see, we've got this snippet. -00:05:48.560 --> 00:05:52.779 -let's make it a section in our file. - -00:05:52.779 --> 00:05:55.045 -So now you can see, we've got - -00:05:55.045 --> 00:05:56.400 -this snippet. - -00:05:56.400 --> 00:05:59.600 +00:05:56.400 --> 00:06:01.600 When you have a source block in - -00:05:59.600 --> 00:06:01.600 -inside of Org Mode, you can easily pop +inside of Org Mode, 00:06:01.600 --> 00:06:04.960 -into a language-specific buffer -by typing +you can easily pop into a +language-specific buffer by typing 00:06:04.960 --> 00:06:07.680 C-c ' (single quote). |