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

0:00:03.600,0:00:06.560
hello

0:00:04.400,0:00:08.400
welcome to readme driven design in Emacs

0:00:06.560,0:00:10.800
by adam aard

0:00:08.400,0:00:12.559
if you're a programmer you're accustomed

0:00:10.800,0:00:13.759
to putting a readme file at the root of

0:00:12.559,0:00:16.400
your project

0:00:13.759,0:00:17.600
and it's usually a markdown file but if

0:00:16.400,0:00:20.720
you use an org

0:00:17.600,0:00:22.560
more an org mode file instead you can

0:00:20.720,0:00:24.400
take advantage of the great features

0:00:22.560,0:00:25.920
that org mode provides including

0:00:24.400,0:00:28.000
literate programming

0:00:25.920,0:00:31.840
which lets you generate your source code

0:00:28.000,0:00:34.719
and markdown documentation dynamically

0:00:31.840,0:00:37.120
I want to walk you through a little bit

0:00:34.719,0:00:39.440
of what this looks like

0:00:37.120,0:00:41.280
when you start a project especially if

0:00:39.440,0:00:43.320
if you use something like github you

0:00:41.280,0:00:47.039
begin with an automatically generated

0:00:43.320,0:00:50.239
readme.md file so just delete that

0:00:47.039,0:00:51.920
and instead create a readme.org file

0:00:50.239,0:00:54.800
starting with an empty org file like you

0:00:51.920,0:00:56.559
see here you can begin

0:00:54.800,0:00:59.440
by recording important information about

0:00:56.559,0:01:01.920
your project goals you can add diagrams

0:00:59.440,0:01:03.520
code snippets to-do lists time tracking

0:01:01.920,0:01:05.360
and much more

0:01:03.520,0:01:07.760
I'm going to drop in some documentation

0:01:05.360,0:01:10.840
that I r that I've written about

0:01:07.760,0:01:12.240
about my project here so you can kind of

0:01:10.840,0:01:15.280
see

0:01:12.240,0:01:17.119
what this would look like

0:01:15.280,0:01:20.320
so as you can see I have a title and a

0:01:17.119,0:01:23.840
description and then a sub section

0:01:20.320,0:01:25.520
as well as some code snippets

0:01:23.840,0:01:28.240
and you can see that orgmo does a great

0:01:25.520,0:01:31.280
job of formatting lists and

0:01:28.240,0:01:33.920
code sections diagrams and so forth

0:01:31.280,0:01:35.040
it's good or it's as good or better than

0:01:33.920,0:01:37.520
markdown

0:01:35.040,0:01:38.880
but when you use it in the Emacs you can

0:01:37.520,0:01:40.479
do a lot more

0:01:38.880,0:01:43.360
for example you can dynamically create

0:01:40.479,0:01:45.200
diagrams using graphviz

0:01:43.360,0:01:46.560
from a text description so if you go to

0:01:45.200,0:01:49.439
this source block here

0:01:46.560,0:01:51.439
and hit control c control c you'll see

0:01:49.439,0:01:55.439
that we generate a

0:01:51.439,0:01:59.200
diagram dynamically you can run

0:01:55.439,0:02:00.799
so you can run these code snippets in

0:01:59.200,0:02:03.040
place and get the results

0:02:00.799,0:02:06.640
to show up inside of your your file

0:02:03.040,0:02:06.640
which is a really powerful paradigm

0:02:08.000,0:02:11.520
but most important most importantly for

0:02:10.640,0:02:14.800
the

0:02:11.520,0:02:17.200
purposes my purpose is here

0:02:14.800,0:02:19.520
orgmo provides you the ability to do

0:02:17.200,0:02:21.440
literate programming

0:02:19.520,0:02:23.200
so take a quick look at this diagram

0:02:21.440,0:02:25.360
that I generated here

0:02:23.200,0:02:27.520
and gives you a quick overview of what I

0:02:25.360,0:02:31.200
mean by literate programming

0:02:27.520,0:02:33.920
and how I'm using it you can see

0:02:31.200,0:02:34.720
that we start with a readme.org file on

0:02:33.920,0:02:36.879
top

0:02:34.720,0:02:37.920
at this point we can do one of two

0:02:36.879,0:02:41.280
things

0:02:37.920,0:02:42.720
tangle or weave tangle is used to

0:02:41.280,0:02:46.319
describe the process of

0:02:42.720,0:02:47.599
generating source code while weave

0:02:46.319,0:02:49.840
is the process of generating

0:02:47.599,0:02:51.920
documentation these are terms that

0:02:49.840,0:02:53.840
donald knuth used

0:02:51.920,0:02:55.519
and he's the one that came up with the

0:02:53.840,0:02:59.920
idea of literate programming

0:02:55.519,0:03:01.519
in the early 1980s

0:02:59.920,0:03:04.480
but this is really all that there is to

0:03:01.519,0:03:06.400
it you just

0:03:04.480,0:03:07.840
who are simply using literate illiterate

0:03:06.400,0:03:10.319
source file

0:03:07.840,0:03:11.680
in this case the readme.org to generate

0:03:10.319,0:03:15.680
the rest of the project

0:03:11.680,0:03:15.680
the rest of the project files basically

0:03:17.120,0:03:22.640
so let's dig in to the details of how

0:03:20.959,0:03:24.560
this works

0:03:22.640,0:03:26.159
and I hope you hopefully you'll see how

0:03:24.560,0:03:28.959
cool this is

0:03:26.159,0:03:31.120
so returning to the file here let's

0:03:28.959,0:03:32.080
assume we have enough documentation now

0:03:31.120,0:03:34.159
that we want to get started

0:03:32.080,0:03:35.519
coding so maybe we'll just start with

0:03:34.159,0:03:38.159
like a hello world

0:03:35.519,0:03:41.519
app just so we can make sure that our

0:03:38.159,0:03:47.120
environment is set up correctly

0:03:41.519,0:03:49.519
so let's get started with a code block

0:03:47.120,0:03:50.319
so I created a little snippet to help me

0:03:49.519,0:03:52.239
add

0:03:50.319,0:03:53.599
a source block for literate programming

0:03:52.239,0:03:56.959
quickly

0:03:53.599,0:03:58.799
and there's not much to it

0:03:56.959,0:04:01.599
but there is some important annotations

0:03:58.799,0:04:04.080
here so there's

0:04:01.599,0:04:05.200
excuse me there's a there's a property

0:04:04.080,0:04:09.360
called tangle

0:04:05.200,0:04:13.280
and that takes a value of a file name

0:04:09.360,0:04:16.560
and then there's also a no web property

0:04:13.280,0:04:16.560
called no export

0:04:18.880,0:04:22.000
and basically

0:04:23.759,0:04:28.639
basically the no export will explain

0:04:26.800,0:04:32.080
that a little bit

0:04:28.639,0:04:33.919
more later um it has has to do with how

0:04:32.080,0:04:37.600
the tangling

0:04:33.919,0:04:39.280
is uh done in the tangle step versus the

0:04:37.600,0:04:41.199
weave step and I'll explain that a

0:04:39.280,0:04:45.199
little bit more but the tangle

0:04:41.199,0:04:48.320
field just simply tells tells uh

0:04:45.199,0:04:50.320
Emacs where it needs to generate the

0:04:48.320,0:04:53.280
main.go file and where it needs to put

0:04:50.320,0:04:53.280
it on the file system

0:04:55.360,0:04:59.040
uh you'll you'll notice that we we're

0:04:57.680,0:05:01.440
going to use go

0:04:59.040,0:05:02.160
that's just the language that I've been

0:05:01.440,0:05:05.360
using

0:05:02.160,0:05:07.360
the most lately uh but

0:05:05.360,0:05:08.400
this programming strategy is language

0:05:07.360,0:05:12.080
agnostic

0:05:08.400,0:05:14.720
you could use any language or any mix

0:05:12.080,0:05:16.560
of languages you could create some files

0:05:14.720,0:05:19.520
in python some files and go

0:05:16.560,0:05:21.520
some files in in lisp or whatever you

0:05:19.520,0:05:24.720
want

0:05:21.520,0:05:28.000
and so but let's

0:05:24.720,0:05:29.440
uh let's create just a little hello

0:05:28.000,0:05:32.320
world

0:05:29.440,0:05:33.520
let's use another snippet here to

0:05:32.320,0:05:36.560
generate

0:05:33.520,0:05:39.840
the basics of a go program

0:05:36.560,0:05:39.840
so I'm just going to print

0:05:40.240,0:05:42.960
hello world

0:05:44.960,0:05:48.240
so that's and then

0:05:48.560,0:05:55.280
let's make it a section in our

0:05:52.320,0:05:56.400
file so now you can see we've got this

0:05:55.280,0:05:59.600
snippet

0:05:56.400,0:06:01.600
um when you have a source block in

0:05:59.600,0:06:02.880
inside of org mode you can easily pop

0:06:01.600,0:06:04.960
into a

0:06:02.880,0:06:07.680
language specific buffer by typing

0:06:04.960,0:06:10.240
control c single quote

0:06:07.680,0:06:12.160
so you can see now I have a a go a

0:06:10.240,0:06:14.240
buffer that's in go mode

0:06:12.160,0:06:15.520
and gives you all the ability to edit

0:06:14.240,0:06:18.800
like you would

0:06:15.520,0:06:20.800
normally if you hit ctrl c

0:06:18.800,0:06:22.639
single quote again then it goes back and

0:06:20.800,0:06:25.280
any changes you

0:06:22.639,0:06:26.160
make would will be updated there but you

0:06:25.280,0:06:28.000
can do quite a bit

0:06:26.160,0:06:29.199
just inside of here too there's quite a

0:06:28.000,0:06:32.400
bit of

0:06:29.199,0:06:32.400
language specific

0:06:33.360,0:06:36.880
functionality just in place and so you

0:06:35.440,0:06:38.080
don't always have to go over to a

0:06:36.880,0:06:42.319
separate buffer

0:06:38.080,0:06:44.319
but it's a it's a nice option sometimes

0:06:42.319,0:06:46.720
but now that you have the code in here

0:06:44.319,0:06:48.560
you're going to want to run it

0:06:46.720,0:06:50.240
but right now it just lives here in this

0:06:48.560,0:06:52.160
documentation

0:06:50.240,0:06:53.840
so you need to get a copy of it into a

0:06:52.160,0:06:57.440
separate file

0:06:53.840,0:07:01.360
and that's the tangle process that you

0:06:57.440,0:07:03.360
you need to follow there so I'm gonna

0:07:01.360,0:07:05.280
drop in a little bit more doc a little

0:07:03.360,0:07:08.960
bit more

0:07:05.280,0:07:08.960
documentation really quick here

0:07:12.240,0:07:21.520
okay all right so just kind of as a

0:07:17.360,0:07:24.800
kind of as a side note I like to follow

0:07:21.520,0:07:26.639
this process uh whenever having whenever

0:07:24.800,0:07:28.880
I have an operation to perform I

0:07:26.639,0:07:31.680
I'd like to document it here with a

0:07:28.880,0:07:33.280
snippet that can be executed in line

0:07:31.680,0:07:34.639
then I don't have to leave org mode and

0:07:33.280,0:07:36.800
I don't have to try to remember what I

0:07:34.639,0:07:38.960
did later so instead of just

0:07:36.800,0:07:40.319
trying to do an operation the first time

0:07:38.960,0:07:41.680
I do something I take the

0:07:40.319,0:07:43.440
take the time to figure out what it is

0:07:41.680,0:07:44.879
and document it and so then it's

0:07:43.440,0:07:48.400
recorded

0:07:44.879,0:07:49.120
and so here we find that to do a tangle

0:07:48.400,0:07:51.680
operation

0:07:49.120,0:07:52.560
you run the command or babel tangled

0:07:51.680,0:07:55.840
which is a

0:07:52.560,0:07:59.199
e-list command so if you hit ctrl c

0:07:55.840,0:08:00.080
ctrl c to run it in place you get the

0:07:59.199,0:08:02.720
result

0:08:00.080,0:08:03.759
of main dot go which basically is

0:08:02.720,0:08:07.680
telling us that

0:08:03.759,0:08:11.039
we've tangled one file called main.go

0:08:07.680,0:08:14.000
and you can see that that's true

0:08:11.039,0:08:14.400
if you go to the file system and you

0:08:14.000,0:08:17.840
look

0:08:14.400,0:08:20.960
so now in uh in our demo directory

0:08:17.840,0:08:22.479
we have a readme.org we have that png

0:08:20.960,0:08:23.440
that we generated but we also have a

0:08:22.479,0:08:26.080
main.go

0:08:23.440,0:08:27.759
and if you if you visit that file you'll

0:08:26.080,0:08:29.280
see that it's just the source code that

0:08:27.759,0:08:31.039
was in our documentation which is

0:08:29.280,0:08:32.880
exactly what we expected and what we

0:08:31.039,0:08:36.000
wanted so that's good

0:08:32.880,0:08:36.000
so if we return to

0:08:36.560,0:08:39.919
to where we are at

0:08:41.120,0:08:44.640
now we're we're at the point where we

0:08:42.959,0:08:45.760
have a file on the file system so now we

0:08:44.640,0:08:48.959
need

0:08:45.760,0:08:53.600
um now we need to build it and to

0:08:48.959,0:08:57.040
run it so let's follow the same

0:08:53.600,0:08:58.720
philosophy where let's document

0:08:57.040,0:09:00.160
these operations that we're going to

0:08:58.720,0:09:03.920
perform

0:09:00.160,0:09:03.920
so I'm dropping in a

0:09:04.560,0:09:11.200
a build instruction section and a run

0:09:07.839,0:09:11.200
instruction section

0:09:13.360,0:09:17.839
so as you can see here we have a little

0:09:15.279,0:09:20.000
a bash source block

0:09:17.839,0:09:22.000
and another batch source block this one

0:09:20.000,0:09:25.440
compiles the go build command is what

0:09:22.000,0:09:26.880
compiles a file and then

0:09:25.440,0:09:29.519
the file that gets generated should be

0:09:26.880,0:09:29.519
called demo

0:09:30.080,0:09:34.000
and uh so we just run it here so if if I

0:09:32.959,0:09:37.839
type control c

0:09:34.000,0:09:40.640
control c we get an empty results block

0:09:37.839,0:09:41.360
when you compile things no news is good

0:09:40.640,0:09:44.399
news

0:09:41.360,0:09:46.560
so it means there's no errors so

0:09:44.399,0:09:48.000
presumably we've created an executable

0:09:46.560,0:09:51.440
that's called demo

0:09:48.000,0:09:54.560
so let's uh

0:09:51.440,0:09:57.519
let's look again at the file system and

0:09:54.560,0:09:57.519
regenerate

0:10:02.480,0:10:07.200
yep and what we have here is a demo

0:10:05.760,0:10:07.760
executable which is exactly what we

0:10:07.200,0:10:12.079
wanted

0:10:07.760,0:10:14.160
so let's go back

0:10:12.079,0:10:16.079
so now we should be able to run it so

0:10:14.160,0:10:20.320
ctrl c ctrl c

0:10:16.079,0:10:20.320
and we get hello world as a result

0:10:20.399,0:10:26.560
which was exactly what we were expecting

0:10:23.440,0:10:30.240
so that's already pretty cool

0:10:26.560,0:10:30.240
you can you can do that much

0:10:30.839,0:10:34.560
um but

0:10:33.040,0:10:37.839
that's really just kind of the tip of

0:10:34.560,0:10:41.040
the iceberg to uh to really

0:10:37.839,0:10:43.440
kind of um

0:10:41.040,0:10:46.160
use the more impressive features of

0:10:43.440,0:10:49.519
literate programming we need to uh

0:10:46.160,0:10:49.519
we need to do a little bit more

0:10:49.920,0:10:55.519
so or at least

0:10:53.200,0:10:56.480
at least really to get the full benefit

0:10:55.519,0:10:59.120
of it then

0:10:56.480,0:10:59.120
we need to do

0:10:59.600,0:11:06.320
add some sections that will cause uh

0:11:02.959,0:11:06.720
Emacs to have to to tangle or assemble

0:11:06.320,0:11:09.760
this

0:11:06.720,0:11:13.120
this file from different pieces so

0:11:09.760,0:11:16.720
imagine that we wanted to take this file

0:11:13.120,0:11:19.120
and maybe kind of templatize it

0:11:16.720,0:11:21.279
so using literature programming syntax

0:11:19.120,0:11:24.399
this angle bracket syntax

0:11:21.279,0:11:29.360
let's say that we want to create an in

0:11:24.399,0:11:32.399
imports section

0:11:29.360,0:11:35.040
in a functions section

0:11:32.399,0:11:36.240
and then maybe just a main section and

0:11:35.040,0:11:37.920
we'll get rid of this

0:11:36.240,0:11:39.760
so now you see we've created something

0:11:37.920,0:11:42.000
that looks a little bit like a

0:11:39.760,0:11:42.880
like a template or a scaffolding or

0:11:42.000,0:11:46.000
outline

0:11:42.880,0:11:48.399
for what what our file is going to be it

0:11:46.000,0:11:50.800
looks a little bit like pseudocode

0:11:48.399,0:11:52.399
and what we're going to have literate

0:11:50.800,0:11:54.800
programming do

0:11:52.399,0:11:56.639
is dynamically insert those things into

0:11:54.800,0:12:00.079
those slots

0:11:56.639,0:12:03.200
so the first thing we need to do

0:12:00.079,0:12:08.079
is so let's create a section

0:12:03.200,0:12:09.519
maybe called say hello so we want

0:12:08.079,0:12:12.720
we want to add some functionality that

0:12:09.519,0:12:15.680
makes our program say hello

0:12:12.720,0:12:17.600
so using a different snippet that I have

0:12:15.680,0:12:20.800
for creating something

0:12:17.600,0:12:24.079
that I call like a literate section

0:12:20.800,0:12:26.000
um basically we create a

0:12:24.079,0:12:27.839
another source block that's almost the

0:12:26.000,0:12:31.040
same as the one for the file but it's

0:12:27.839,0:12:31.680
it just has a few differences so say we

0:12:31.040,0:12:34.160
want to

0:12:31.680,0:12:36.639
drop code into the import section and we

0:12:34.160,0:12:39.120
want it to be in go

0:12:36.639,0:12:40.720
here we use the same noed no web no

0:12:39.120,0:12:43.200
export syntax

0:12:40.720,0:12:44.560
but then we've added this no web refs

0:12:43.200,0:12:48.240
imports

0:12:44.560,0:12:51.120
and this ties that slot

0:12:48.240,0:12:53.760
basically to this reference it tells

0:12:51.120,0:12:56.880
Emacs that when you tangle

0:12:53.760,0:12:58.240
we want to stick whatever's in here in

0:12:56.880,0:13:02.079
that spot

0:12:58.240,0:13:03.279
so you skip the tangle file name section

0:13:02.079,0:13:04.240
because you're not actually creating a

0:13:03.279,0:13:06.160
file name you're

0:13:04.240,0:13:07.680
you're putting information into an

0:13:06.160,0:13:10.720
existing file

0:13:07.680,0:13:13.680
so here we would just add the fmt

0:13:10.720,0:13:13.680
for the imports

0:13:14.399,0:13:22.240
so let's add another section for uh

0:13:18.839,0:13:25.519
functions and let's create a

0:13:22.240,0:13:30.240
let's just create a function called

0:13:25.519,0:13:32.839
say hello that

0:13:30.240,0:13:34.000
doesn't have any arguments no return

0:13:32.839,0:13:35.760
types

0:13:34.000,0:13:37.440
all it does is kind of pretty much the

0:13:35.760,0:13:39.199
same thing as we did before

0:13:37.440,0:13:41.360
just print something but let's just say

0:13:39.199,0:13:45.760
hello

0:13:41.360,0:13:49.519
Emacs comp this time

0:13:45.760,0:13:51.040
okay so now we have a function and now

0:13:49.519,0:13:52.720
the function won't do anything unless we

0:13:51.040,0:13:56.000
invoke it so let's do

0:13:52.720,0:13:59.920
one last literate section

0:13:56.000,0:14:03.519
called main make that go

0:13:59.920,0:14:06.399
source block and then let's

0:14:03.519,0:14:06.399
just invoke

0:14:06.560,0:14:13.360
that that function

0:14:10.320,0:14:15.600
so now you can see that we've got

0:14:13.360,0:14:17.199
our scaffolding scaffolding kind of

0:14:15.600,0:14:20.079
outline and then we have

0:14:17.199,0:14:21.360
the sections that we want to get tangled

0:14:20.079,0:14:25.440
or inserted

0:14:21.360,0:14:27.199
so I I've kind of used this syntax

0:14:25.440,0:14:28.560
it's it's kind of borrowed from

0:14:27.199,0:14:30.320
literature programming a little bit with

0:14:28.560,0:14:32.480
a plus equals so really it's just saying

0:14:30.320,0:14:35.760
that I want to append

0:14:32.480,0:14:37.600
this item into the import section so

0:14:35.760,0:14:39.839
it's really just to make a little bit

0:14:37.600,0:14:41.519
more clear what's going on

0:14:39.839,0:14:43.519
when you generate documentation you

0:14:41.519,0:14:46.160
won't see these

0:14:43.519,0:14:49.360
these these particular property

0:14:46.160,0:14:51.440
annotations and so you won't know

0:14:49.360,0:14:53.839
immediately that this section goes in

0:14:51.440,0:14:55.440
the imports area and so I usually put

0:14:53.839,0:14:57.760
a little bit of documentation on top

0:14:55.440,0:15:01.120
there so that it's easy to see

0:14:57.760,0:15:03.040
and you would probably if this was very

0:15:01.120,0:15:06.399
complicated you'd put some

0:15:03.040,0:15:07.360
documentation above to explain what you

0:15:06.399,0:15:10.320
were doing

0:15:07.360,0:15:10.320
maybe right here

0:15:11.519,0:15:15.040
you could you could picture yourself

0:15:13.279,0:15:17.440
maybe explaining

0:15:15.040,0:15:18.079
a complicated algorithm or something up

0:15:17.440,0:15:21.120
here

0:15:18.079,0:15:22.959
and having a nice way to document it

0:15:21.120,0:15:25.600
so now that we've got that here in the

0:15:22.959,0:15:27.040
documentation we need to figure out

0:15:25.600,0:15:29.920
we need to make sure that it's going to

0:15:27.040,0:15:33.519
tangle properly so your best friend

0:15:29.920,0:15:35.680
at this point is is uh

0:15:33.519,0:15:38.240
is a keyboard shortcut that lets you

0:15:35.680,0:15:38.959
preview the tangled operation so if you

0:15:38.240,0:15:42.560
say control

0:15:38.959,0:15:45.120
c control v control v

0:15:42.560,0:15:46.480
it will create a new buffer with the

0:15:45.120,0:15:49.360
tangled

0:15:46.480,0:15:50.639
contents and so you can see here that

0:15:49.360,0:15:53.199
the fmt

0:15:50.639,0:15:54.720
import went to the right place that

0:15:53.199,0:15:56.160
function went to the right place the

0:15:54.720,0:15:58.480
function invocation went to the right

0:15:56.160,0:16:01.279
place and so we're feeling good

0:15:58.480,0:16:02.800
you can nest these things many layers

0:16:01.279,0:16:04.800
deep

0:16:02.800,0:16:07.199
actually so like if you came into the

0:16:04.800,0:16:10.160
say hello function you could add

0:16:07.199,0:16:10.160
more sections

0:16:10.560,0:16:13.759
you know and it gets and it'll go

0:16:12.160,0:16:15.680
through and it'll

0:16:13.759,0:16:16.959
keep track of all that and tangle it for

0:16:15.680,0:16:18.320
you so you really get a lot of freedom

0:16:16.959,0:16:19.600
and flexibility for how you want to

0:16:18.320,0:16:22.320
document things

0:16:19.600,0:16:25.839
by doing this so now that we've

0:16:22.320,0:16:28.639
previewed it and we feel good about it

0:16:25.839,0:16:31.440
we need to uh we need to tangle so we

0:16:28.639,0:16:34.480
get the file on the file system

0:16:31.440,0:16:37.199
so ctrl c ctrl c and

0:16:34.480,0:16:37.920
get just main.go comes back again

0:16:37.199,0:16:40.959
control c

0:16:37.920,0:16:43.839
control c and no errors come back

0:16:40.959,0:16:45.600
and then if we did this right when we

0:16:43.839,0:16:47.199
when we run this we should get hello

0:16:45.600,0:16:51.199
Emacs comp so ctrl c

0:16:47.199,0:16:54.800
ctrl c hello Emacs comp

0:16:51.199,0:16:57.120
so I uh

0:16:54.800,0:16:58.240
I think that's pretty pretty cool

0:16:57.120,0:17:00.160
actually so we've got

0:16:58.240,0:17:02.399
kind of the breadcrumbs of the process

0:17:00.160,0:17:05.520
we've gone through to get to this point

0:17:02.399,0:17:08.000
this initial this initial

0:17:05.520,0:17:09.919
document that has some tangling in it we

0:17:08.000,0:17:12.799
have documentation for how to tangle

0:17:09.919,0:17:14.079
how to build how to run it's we've

0:17:12.799,0:17:17.760
really built a nice

0:17:14.079,0:17:20.160
foundation for

0:17:17.760,0:17:21.439
moving forward on our project and a nice

0:17:20.160,0:17:23.280
way of breaking things out and

0:17:21.439,0:17:27.120
documenting further

0:17:23.280,0:17:30.559
the last piece that we need to

0:17:27.120,0:17:34.799
take care of is the weave that I

0:17:30.559,0:17:38.640
that's I showed you in the diagram above

0:17:34.799,0:17:41.760
so one more time we'll drop in

0:17:38.640,0:17:42.400
some documentation so this time on how

0:17:41.760,0:17:44.400
to weave

0:17:42.400,0:17:47.520
so it's really just an export function

0:17:44.400,0:17:49.280
it's not there's not a separate weave

0:17:47.520,0:17:50.640
command going on here we're just going

0:17:49.280,0:17:52.799
to export

0:17:50.640,0:17:55.200
what we've got here into a markdown

0:17:52.799,0:17:57.440
format so we're using org

0:17:55.200,0:17:58.880
gfm export to markdown which is the

0:17:57.440,0:18:02.160
github style

0:17:58.880,0:18:05.440
markdown you can use the other just

0:18:02.160,0:18:10.320
more standard type as well so hit ctrl c

0:18:05.440,0:18:15.280
ctrl c now you see we've got a readme

0:18:10.320,0:18:17.440
file and if you look

0:18:15.280,0:18:19.120
in the file system we've got that right

0:18:17.440,0:18:23.120
there and so

0:18:19.120,0:18:29.840
if you go to something like ghostwriter

0:18:23.120,0:18:29.840
and open that file

0:18:31.679,0:18:35.520
now you can see that it's generated some

0:18:34.559,0:18:38.320
documentation

0:18:35.520,0:18:39.679
it puts a index at top at the top I

0:18:38.320,0:18:42.000
usually just

0:18:39.679,0:18:43.679
I usually turn that off it's easy to do

0:18:42.000,0:18:44.559
that by putting a property at the top of

0:18:43.679,0:18:46.880
your

0:18:44.559,0:18:48.559
your org file but some people like to

0:18:46.880,0:18:50.799
have an index

0:18:48.559,0:18:52.160
but here you can see that it's generated

0:18:50.799,0:18:55.200
pretty nicely and

0:18:52.160,0:18:56.880
formatted snippets well

0:18:55.200,0:18:58.240
put the diagram in there and then it's

0:18:56.880,0:19:01.039
preserved

0:18:58.240,0:19:02.799
it's preserved this literate programming

0:19:01.039,0:19:04.960
syntax

0:19:02.799,0:19:06.480
which is important because that's how we

0:19:04.960,0:19:07.200
want to view the documentation that's

0:19:06.480,0:19:10.559
what the no

0:19:07.200,0:19:13.360
exports um

0:19:10.559,0:19:14.000
property was was trying to maintain so

0:19:13.360,0:19:16.080
that

0:19:14.000,0:19:18.400
no exports means when you export do not

0:19:16.080,0:19:20.559
try to tangle so that's

0:19:18.400,0:19:22.240
hopefully that makes more sense now but

0:19:20.559,0:19:26.080
now you can see all the documentation

0:19:22.240,0:19:29.919
and I think it demonstrates a

0:19:26.080,0:19:33.520
pretty useful feature that's inside of

0:19:29.919,0:19:35.039
Emacs and and hopefully

0:19:33.520,0:19:39.840
hopefully you'll have as much fun using

0:19:35.039,0:19:39.840
that as I have

0:19:39.919,0:19:43.600
so thanks