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: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
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.898
that Org Mode provides,
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
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.607
When you start a project,
00:00:39.607 --> 00:00:41.179
especially if you use something like Github
00:00:41.179 --> 00:00:45.913
you begin with an automatically generated
README.md file.
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.
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.295
by recording important information
00:00:56.295 --> 00:00:59.440
about your project goals. You can add diagrams,
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 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.870
As you can see, I have a title,
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.210
You can see that Org Mode does
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.
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:43.360
For example, you can dynamically create
diagrams using Graphviz
00:01:43.360 --> 00:01:45.553
from a text description.
00:01:45.553 --> 00:01:48.266
If you go to this source block here
and hit C-c C-c,
00:01:48.266 --> 00:01:52.979
you'll see that we generate a diagram
dynamically.
00:01:55.439 --> 00:02:00.519
You can run these code snippets in
place
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,
00:02:03.040 --> 00:02:08.000
which is a really powerful paradigm.
00:02:08.000 --> 00:02:14.800
But most importantly, for my purposes here,
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
00:02:21.440 --> 00:02:23.200
that I generated here.
00:02:23.200 --> 00:02:25.912
It gives you a quick overview
00:02:25.912 --> 00:02:27.520
of what I mean by literate programming
00:02:27.520 --> 00:02:30.973
and how I'm using it.
00:02:30.973 --> 00:02:34.720
You can see that we start with a README.org file on top.
00:02:34.720 --> 00:02:40.501
At this point, we can do one of two things:
tangle or weave.
00:02:40.501 --> 00:02:43.611
Tangle is used to describe the process
00:02:43.611 --> 00:02:45.463
of generating source code,
00:02:45.463 --> 00:02:48.495
while weave is the process of generating
documentation.
00:02:48.495 --> 00:02:51.920
These are terms that Donald Knuth used.
00:02:51.920 --> 00:02:53.388
He's the one that came up
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.
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.575
in this case the README.org,
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.
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,
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.326
add a source block
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: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: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...
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
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:46.719
But the tangle field just simply tells
Emacs
00:04:46.719 --> 00:04:48.320
where it needs to generate the
00:04:48.320 --> 00:04:49.951
main.go file
00:04:49.951 --> 00:04:55.360
and where it needs to put it on the file system.
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.578
That's just the language
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
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:15.377
You could create some files
in Python,
00:05:15.377 --> 00:05:16.560
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:44.960
I'm just going to print 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:52.779 --> 00:05:56.400
So now you can see, we've got this snippet.
00:05:56.400 --> 00:06:01.600
When you have a source block in
inside of Org Mode,
00:06:01.600 --> 00:06:04.960
you can easily pop 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'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 documentation, 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!
