Add subtitles for 13, 14, 15

1 files changed, 1297 insertions, 0 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
new file mode 100644
index 00000000..608729bd
--- /dev/null
+++ b/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt
@@ -0,0 +1,1297 @@
+WEBVTT
+
+00:00:03.600 --> 00:00:04.400
+Adam: 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:15.845
+It's usually a Markdown file
+
+00:00:15.845 --> 00:00:20.579
+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
+
+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.712
+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: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 that I've written about
+
+00:01:07.760 --> 00:01:12.240
+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:17.119 --> 00:01:20.320
+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:25.520 --> 00:01:28.240
+job of formatting lists,
+
+00:01:28.240 --> 00:01:31.280
+code sections, diagrams, and so forth.
+
+00:01:31.280 --> 00:01:35.040
+It's as good or better than Markdown,
+
+00:01:35.040 --> 00:01:37.179
+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
+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:46.560 --> 00:01:49.439
+and hit C-c C-c, you'll see
+
+00:01:49.439 --> 00:01:52.979
+that we generate a diagram dynamically
+
+00:01:55.439 --> 00:01:59.200
+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 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: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: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.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:31.200 --> 00:02:34.720
+that we start with a README.org file
+on top.
+
+00:02:34.720 --> 00:02:37.920
+At this point, we can do one of two
+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
+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.945
+But this is really all that there is to
+it.
+
+00:03:01.945 --> 00:03:05.412
+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:11.680 --> 00:03:17.120
+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.
+
+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: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,
+
+00:03:31.120 --> 00:03:32.679
+that we want to get started
+coding.
+
+00:03:32.679 --> 00:03:34.159
+So maybe we'll just start with
+
+00:03:34.159 --> 00:03:35.845
+like a Hello World app,
+
+00:03:35.845 --> 00:03:38.159
+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
+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:51.612 --> 00:03:53.599
+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
+
+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
+Then there's also a :noweb property
+
+00:04:13.280 --> 00:04:18.880
+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
+
+00:04:29.645 --> 00:04:32.080
+It has has to do with how
+
+00:04:32.080 --> 00:04:36.845
+the tangling is done in the tangle
+step
+
+00:04:36.845 --> 00:04:38.479
+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
+But the tangle field just simply tells
+
+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
+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:03.379
+using the most lately,
+
+00:05:03.379 --> 00:05:06.845
+but this programming strategy
+
+00:05:06.845 --> 00:05:08.400
+is language-agnostic.
+
+00:05:08.400 --> 00:05:11.279
+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
+You could create some files
+
+00:05:14.720 --> 00:05:16.560
+in Python, some files in Go,
+
+00:05:16.560 --> 00:05:19.179
+some files in Lisp,
+
+00:05:19.179 --> 00:05:21.520
+or whatever you want.
+
+00:05:24.720 --> 00:05:29.440
+Let's create just a little
+Hello World.
+
+00:05:29.440 --> 00:05:31.379
+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: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.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
+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:04.960
+into a language-specific buffer
+by typing
+
+00:06:04.960 --> 00:06:07.680
+C-c ' (single quote).
+
+00:06:07.680 --> 00:06:10.240
+So you can see, now I have 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:19.945
+normally. If you hit C-c '
+(single quote)
+
+00:06:19.945 --> 00:06:20.800
+again, it goes back and
+
+00:06:20.800 --> 00:06:25.045
+any changes you make will be
+updated there.
+
+00:06:25.045 --> 00:06:26.160
+But you can do quite a bit
+
+00:06:26.160 --> 00:06:27.879
+just inside of here too.
+
+00:06:27.879 --> 00:06:29.199
+There's quite a bit of
+
+00:06:29.199 --> 00:06:34.479
+language-specific functionality
+
+00:06:34.479 --> 00:06:35.312
+just in place,
+
+00:06:35.312 --> 00:06:36.880
+so you 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
+It's a nice option sometimes.
+
+00:06:42.319 --> 00:06:44.319
+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.179
+Right now, it just lives here
+
+00:06:48.179 --> 00:06:50.240
+in this documentation.
+
+00:06:50.240 --> 00:06:52.160
+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:12.240
+bit more documentation really quick here.
+
+00:07:12.240 --> 00:07:19.112
+Okay, all right. So just as a side note,
+
+00:07:19.112 --> 00:07:22.845
+I like to follow this process.
+
+00:07:22.845 --> 00:07:26.639
+Whenever I have an operation to perform,
+
+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 inline.
+
+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,
+
+00:07:40.319 --> 00:07:41.680
+I take the time to figure out what it is
+
+00:07:41.680 --> 00:07:44.879
+and document it, so then it's
+recorded.
+
+00:07:44.879 --> 00:07:49.120
+So here we find that to do a tangle
+operation,
+
+00:07:49.120 --> 00:07:51.680
+you run the command org-babel-tangle,
+
+00:07:51.680 --> 00:07:53.779
+which is an Elisp command.
+
+00:07:53.779 --> 00:07:58.712
+If you hit C-c C-c to run it in place,
+
+00:07:58.712 --> 00:08:00.080
+you get the result
+
+00:08:00.080 --> 00:08:02.720
+of main.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
+You can see that that's true
+
+00:08:11.039 --> 00:08:12.879
+if you go to the file system
+
+00:08:12.879 --> 00:08:14.400
+and you look.
+
+00:08:14.400 --> 00:08:17.840
+Now in our demo directory,
+
+00:08:17.840 --> 00:08:19.712
+we have a README.org,
+
+00:08:19.712 --> 00:08:22.045
+we have that PNG that we generated,
+
+00:08:22.045 --> 00:08:23.440
+but we also have a main.go.
+
+00:08:23.440 --> 00:08:25.945
+If you visit that file,
+
+00:08:25.945 --> 00:08:27.045
+you'll see that it's just
+
+00:08:27.045 --> 00:08:28.212
+the source code that was
+
+00:08:28.212 --> 00:08:29.280
+in our documentation, which is
+
+00:08:29.280 --> 00:08:30.679
+exactly what we expected
+
+00:08:30.679 --> 00:08:32.880
+and what we wanted. So that's good.
+
+00:08:32.880 --> 00:08:41.120
+So if we return to where we were at...
+
+00:08:41.120 --> 00:08:42.959
+Now we're at the point where we
+
+00:08:42.959 --> 00:08:44.479
+have a file on the file system.
+
+00:08:45.760 --> 00:08:48.379
+Now we need to build it
+
+00:08:48.379 --> 00:08:49.612
+and to run it.
+
+00:08:49.612 --> 00:08:57.040
+So let's follow the same philosophy,
+where let's document
+
+00:08:57.040 --> 00:09:00.160
+these operations that we're going to
+perform.
+
+00:09:00.160 --> 00:09:04.560
+I'm dropping in a
+
+00:09:04.560 --> 00:09:07.112
+a build instruction section
+
+00:09:07.112 --> 00:09:13.360
+and a run instruction section.
+
+00:09:13.360 --> 00:09:15.279
+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:19.245
+and another bash source block.
+
+00:09:19.245 --> 00:09:21.812
+This one compiles. The go build command
+
+00:09:21.812 --> 00:09:25.440
+is what compiles a file. Then
+
+00:09:25.440 --> 00:09:26.579
+the file that gets generated
+
+00:09:26.579 --> 00:09:30.080
+should be called demo.
+
+00:09:30.080 --> 00:09:32.412
+So we just run it here.
+
+00:09:32.412 --> 00:09:37.839
+If I type C-c C-c, we get an
+empty results block.
+
+00:09:37.839 --> 00:09:38.979
+When you compile things,
+
+00:09:38.979 --> 00:09:41.360
+no news is good news.
+
+00:09:41.360 --> 00:09:43.012
+It means there's no errors
+
+00:09:43.012 --> 00:09:45.912
+So presumably, we've created
+
+00:09:45.912 --> 00:09:48.000
+an executable that's called demo.
+
+00:09:51.440 --> 00:09:53.312
+Let's look again at the file system
+
+00:09:53.312 --> 00:10:02.480
+and regenerate...
+
+00:10:02.480 --> 00:10:06.479
+Yep. What we have here is a demo
+executable,
+
+00:10:06.479 --> 00:10:07.760
+which is exactly what we
+wanted.
+
+00:10:07.760 --> 00:10:12.079
+Let's go back.
+
+00:10:12.079 --> 00:10:14.160
+Now we should be able to run it.
+
+00:10:14.160 --> 00:10:16.079
+C-c C-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 do that much.
+
+00:10:33.040 --> 00:10:34.560
+That's really just the tip of
+
+00:10:34.560 --> 00:10:37.839
+the iceberg. To really
+
+00:10:41.040 --> 00:10:43.440
+use the more impressive features of
+
+00:10:43.440 --> 00:10:46.160
+literate programming,
+
+00:10:46.160 --> 00:10:49.920
+we need to do a little bit more
+
+00:10:53.200 --> 00:10:54.512
+at least. Really,
+
+00:10:54.512 --> 00:10:56.480
+to get the full benefit of it,
+
+00:10:56.480 --> 00:11:01.079
+we need to add some sections
+
+00:11:01.079 --> 00:11:04.412
+that will cause Emacs to have to
+
+00:11:04.412 --> 00:11:06.720
+tangle or assemble
+
+00:11:06.720 --> 00:11:09.760
+this file from different pieces.
+
+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
+
+00:11:24.399 --> 00:11:29.360
+imports section,
+
+00:11:29.360 --> 00:11:32.399
+a functions section,
+
+00:11:32.399 --> 00:11:35.040
+and then maybe just a main section.
+
+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.880
+template or a scaffolding or outline
+
+00:11:42.880 --> 00:11:45.812
+for what our file is going to be.
+
+00:11:45.812 --> 00:11:48.399
+It looks a little bit like pseudocode.
+
+00:11:48.399 --> 00:11:50.612
+What we're going to have
+
+00:11:50.612 --> 00:11:52.399
+literate 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
+called "Say Hello."
+
+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
+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.
+
+00:12:27.839 --> 00:12:29.412
+It just has a few differences
+
+00:12:29.412 --> 00:12:34.079
+Say we want to drop code into the import
+section
+
+00:12:34.079 --> 00:12:36.639
+and we want it to be in Go.
+
+00:12:36.639 --> 00:12:40.720
+Here we use the same :noweb no-export syntax,
+
+00:12:40.720 --> 00:12:44.560
+but then we've added this :noweb-ref imports,
+
+00:12:44.560 --> 00:12:48.240
+and this ties that slot
+
+00:12:48.240 --> 00:12:51.120
+to this reference. It tells
+
+00:12:51.120 --> 00:12:53.760
+Emacs that when you tangle,
+
+00:12:53.760 --> 00:12:55.479
+we want to stick whatever's in here
+
+00:12:55.479 --> 00:12:58.240
+in that spot.
+
+00:12:58.240 --> 00:13:02.079
+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.
+
+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:16.145
+Let's add another section
+
+00:13:16.145 --> 00:13:22.240
+for functions.
+
+00:13:22.240 --> 00:13:23.812
+Let's just create a function
+
+00:13:23.812 --> 00:13:28.079
+called sayHello
+
+00:13:28.079 --> 00:13:31.745
+that doesn't have any arguments.
+
+00:13:31.745 --> 00:13:34.000
+No return types.
+
+00:13:34.000 --> 00:13:35.760
+All it does is pretty much the
+
+00:13:35.760 --> 00:13:37.440
+same thing as we did before:
+
+00:13:37.440 --> 00:13:38.479
+just print something.
+
+00:13:38.479 --> 00:13:45.760
+Let's just say "Hello EmacsConf"
+this time.
+
+00:13:45.760 --> 00:13:47.279
+Now we have a function,
+
+00:13:47.279 --> 00:13:50.779
+and now the function won't do anything
+
+00:13:50.779 --> 00:13:52.720
+unless we invoke it. 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. Then let's
+
+00:14:03.519 --> 00:14:10.320
+invoke that function.
+
+00:14:10.320 --> 00:14:13.360
+Now you can see that we've got
+
+00:14:13.360 --> 00:14:15.600
+our scaffolding
+
+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
+I've used this syntax.
+
+00:14:25.440 --> 00:14:27.199
+It's kinda borrowed from
+
+00:14:27.199 --> 00:14:28.479
+literate programming a little bit
+
+00:14:28.479 --> 00:14:30.320
+with a +=, 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
+
+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.445
+When you generate documentation,
+
+00:14:41.445 --> 00:14:43.519
+you won't see these
+
+00:14:43.519 --> 00:14:46.979
+particular property annotations,
+
+00:14:46.979 --> 00:14:50.145
+and so you won't know immediately
+
+00:14:50.145 --> 00:14:51.779
+that this section goes in the
+
+00:14:51.779 --> 00:14:53.839
+imports area. 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
+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.245
+documentation above to explain
+
+00:15:06.245 --> 00:15:07.360
+what you were doing,
+
+00:15:07.360 --> 00:15:11.519
+maybe right here.
+
+00:15:11.519 --> 00:15:13.279
+You could picture yourself
+
+00:15:13.279 --> 00:15:15.040
+maybe explaining
+
+00:15:15.040 --> 00:15:16.745
+a complicated algorithm
+
+00:15:16.745 --> 00:15:18.079
+or something up 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:28.045
+tangle properly.
+
+00:15:28.045 --> 00:15:33.519
+Your best friend at this point
+
+00:15:33.519 --> 00:15:35.680
+is a keyboard shortcut that lets you
+
+00:15:35.680 --> 00:15:37.945
+preview the tangled operation.
+
+00:15:37.945 --> 00:15:42.560
+If you say C-c C-v C-v,
+
+00:15:42.560 --> 00:15:44.079
+it will create a new buffer
+
+00:15:44.079 --> 00:15:47.212
+with the tangled contents
+
+00:15:47.212 --> 00:15:49.179
+and so you can see here
+
+00:15:49.179 --> 00:15:52.345
+that the fmt import went to the right
+place,
+
+00:15:52.345 --> 00:15:54.679
+that function went to the right place,
+
+00:15:54.679 --> 00:15:56.079
+the function invocation went to
+
+00:15:56.079 --> 00:15:58.480
+the right place. We're feeling good.
+
+00:15:58.480 --> 00:16:00.912
+You can nest these things
+
+00:16:00.912 --> 00:16:02.800
+many layers deep.
+
+00:16:02.800 --> 00:16:06.045
+If you came into the sayHello function,
+
+00:16:06.045 --> 00:16:10.560
+you could add more sections.
+
+00:16:10.560 --> 00:16:13.759
+It'll go through and it'll
+
+00:16:13.759 --> 00:16:15.345
+keep track of all that
+
+00:16:15.345 --> 00:16:16.212
+and tangle it for you
+
+00:16:16.212 --> 00:16:16.959
+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:20.479
+document things by doing this.
+
+00:16:20.479 --> 00:16:23.079
+So now that we've previewed it
+
+00:16:23.079 --> 00:16:25.839
+and we feel good about it,
+
+00:16:25.839 --> 00:16:28.639
+we need to tangle so
+
+00:16:28.639 --> 00:16:31.440
+we get the file on the file system.
+
+00:16:31.440 --> 00:16:34.979
+so C-c C-c and get...
+
+00:16:34.979 --> 00:16:37.199
+just main.go comes back again.
+
+00:16:37.199 --> 00:16:40.959
+C-c C-cc and no errors come back.
+
+00:16:40.959 --> 00:16:43.279
+Then if we did this right,
+
+00:16:43.279 --> 00:16:45.079
+when we run this, we should get
+
+00:16:45.079 --> 00:16:45.600
+"Hello, EmacsConf."
+
+00:16:45.600 --> 00:16:51.199
+So C-c C-c, Hello EmacsConf.
+
+00:16:54.800 --> 00:16:57.645
+I think that's pretty, pretty cool,
+actually.
+
+00:16:57.645 --> 00:16:59.579
+So we've got the breadcrumbs
+
+00:16:59.579 --> 00:17:01.212
+of the process we've gone through
+
+00:17:01.212 --> 00:17:02.399
+to get to this point,
+
+00:17:02.399 --> 00:17:07.545
+this initial document that has some
+tangling in it.
+
+00:17:07.545 --> 00:17:09.919
+We have documentation for how to tangle,
+
+00:17:09.919 --> 00:17:11.345
+how to build, how to run.
+
+00:17:11.345 --> 00:17:15.045
+We've really built a nice foundation
+
+00:17:15.045 --> 00:17:19.379
+for moving forward on our project
+
+00:17:19.379 --> 00:17:21.439
+and a nice way of breaking things
+out
+
+00:17:21.439 --> 00:17:23.280
+and 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
+
+00:17:30.559 --> 00:17:34.799
+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 documentatio, this time on how
+
+00:17:41.760 --> 00:17:42.400
+to weave.
+
+00:17:42.400 --> 00:17:44.400
+It's really just an export function.
+
+00:17:44.400 --> 00:17:46.245
+it's not... There's not a separate
+
+00:17:46.245 --> 00:17:49.012
+weave command going on here.
+
+00:17:49.012 --> 00:17:50.640
+we're just going to export
+
+00:17:50.640 --> 00:17:53.512
+what we've got here into a Markdown
+format.
+
+00:17:53.512 --> 00:17:57.045
+We're using org-gfm-export-to-markdown,
+
+00:17:57.045 --> 00:17:59.745
+which is the Github style markdown.
+
+00:17:59.745 --> 00:18:02.160
+You can use the other,
+
+00:18:02.160 --> 00:18:03.812
+more standard type as well.
+
+00:18:03.812 --> 00:18:08.479
+Hit C-c C-c. Now you see
+
+00:18:08.479 --> 00:18:11.312
+we've got a README file,
+
+00:18:11.312 --> 00:18:16.512
+and if you look in the file system,
+
+00:18:16.512 --> 00:18:19.120
+we've got that right there.
+
+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:32.879
+now you can see that
+
+00:18:32.879 --> 00:18:35.520
+it's generated some documentation.
+
+00:18:35.520 --> 00:18:37.645
+It puts a index at top at the top.
+
+00:18:39.679 --> 00:18:41.145
+I usually turn that off.
+
+00:18:41.145 --> 00:18:42.379
+It's easy to do that by
+
+00:18:42.379 --> 00:18:43.179
+putting a property at the
+
+00:18:43.179 --> 00:18:46.145
+top of your Org file,
+
+00:18:46.145 --> 00:18:46.880
+but some people like to
+
+00:18:46.880 --> 00:18:48.559
+have an index.
+
+00:18:48.559 --> 00:18:50.799
+Here you can see that it has generated
+
+00:18:50.799 --> 00:18:55.200
+pretty nicely and formatted
+snippets well,
+
+00:18:55.200 --> 00:18:56.880
+put the diagram in there, and then
+
+00:18:58.240 --> 00:19:02.799
+it's preserved this
+literate programming syntax,
+
+00:19:02.799 --> 00:19:04.960
+which is important because that's how we
+
+00:19:04.960 --> 00:19:06.112
+want to view the documentation.
+
+00:19:06.112 --> 00:19:11.312
+That's what the no-exports property
+
+00:19:11.312 --> 00:19:13.360
+was trying to maintain.
+
+00:19:13.360 --> 00:19:15.979
+no-exports means when you export,
+
+00:19:15.979 --> 00:19:18.400
+do not try to tangle.
+
+00:19:18.400 --> 00:19:20.559
+Hopefully that makes more sense now.
+
+00:19:20.559 --> 00:19:22.240
+Now you can see all the documentation.
+
+00:19:22.240 --> 00:19:26.080
+I think it demonstrates a
+
+00:19:26.080 --> 00:19:33.520
+pretty useful feature that's inside of
+Emacs.
+
+00:19:33.520 --> 00:19:34.979
+Hopefully you'll have as much fun
+
+00:19:34.979 --> 00:19:39.919
+using that as I have.
+
+00:19:39.919 --> 00:19:43.600
+So thanks!