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
