path: root/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt

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!