summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt297
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).