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

WEBVTT

00:00:03.600 --> 00:00:04.400
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:16.400
and it's usually a markdown file but if

00:00:16.400 --> 00:00:17.600
you use an org

00:00:17.600 --> 00:00:20.720
more an org mode file instead you can

00:00:20.720 --> 00:00:22.560
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.920
starting with an empty org file like you

00:00:51.920 --> 00:00:54.800
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 I r that I've written about

00:01:07.760 --> 00:01:10.840
about my project here so you can kind of

00:01:10.840 --> 00:01:12.240
see

00:01:12.240 --> 00:01:15.280
what this would look like

00:01:15.280 --> 00:01:17.119
so as you can see I have a title and a

00:01:17.119 --> 00:01:20.320
description and then a sub section

00:01:20.320 --> 00:01:23.840
as well as some code snippets

00:01:23.840 --> 00:01:25.520
and you can see that orgmo does a great

00:01:25.520 --> 00:01:28.240
job of formatting lists and

00:01:28.240 --> 00:01:31.280
code sections diagrams and so forth

00:01:31.280 --> 00:01:33.920
it's good or it's as good or better than

00:01:33.920 --> 00:01:35.040
markdown

00:01:35.040 --> 00:01:37.520
but when you use it in the Emacs you can

00:01:37.520 --> 00:01:38.880
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 so 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 control c control c you'll see

00:01:49.439 --> 00:01:51.439
that we generate a

00:01:51.439 --> 00:01:55.439
diagram dynamically you can run

00:01:55.439 --> 00:01:59.200
so 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 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 important most importantly for

00:02:10.640 --> 00:02:11.520
the

00:02:11.520 --> 00:02:14.800
purposes my purpose is here

00:02:14.800 --> 00:02:17.200
orgmo 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.360
and gives you a quick overview of what I

00:02:25.360 --> 00:02:27.520
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:33.920
that we start with a readme.org file on

00:02:33.920 --> 00:02:34.720
top

00:02:34.720 --> 00:02:36.879
at this point we can do one of two

00:02:36.879 --> 00:02:37.920
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
and 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.519
but this is really all that there is to

00:03:01.519 --> 00:03:04.480
it you just

00:03:04.480 --> 00:03:06.400
who are simply using literate illiterate

00:03:06.400 --> 00:03:07.840
source file

00:03:07.840 --> 00:03:10.319
in this case the readme.org to generate

00:03:10.319 --> 00:03:11.680
the rest of the project

00:03:11.680 --> 00:03:17.120
the rest of the project files basically

00:03:17.120 --> 00:03:20.959
so let's dig in to the details of how

00:03:20.959 --> 00:03:22.640
this works

00:03:22.640 --> 00:03:24.560
and 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:28.959
so returning to the file here let's

00:03:28.959 --> 00:03:31.120
assume we have enough documentation now

00:03:31.120 --> 00:03:32.080
that we want to get started

00:03:32.080 --> 00:03:34.159
coding so maybe we'll just start with

00:03:34.159 --> 00:03:35.519
like a hello world

00:03:35.519 --> 00:03:38.159
app 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
so 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:50.319
add

00:03:50.319 --> 00:03:52.239
a source block for literate programming

00:03:52.239 --> 00:03:53.599
quickly

00:03:53.599 --> 00:03:56.959
and there's not much to it

00:03:56.959 --> 00:03:58.799
but there is some important annotations

00:03:58.799 --> 00:04:01.599
here so there's

00:04:01.599 --> 00:04:04.080
excuse me there's a 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
and then there's also a no web property

00:04:13.280 --> 00:04:18.880
called no export

00:04:18.880 --> 00:04:23.759
and basically

00:04:23.759 --> 00:04:26.800
basically the no export will explain

00:04:26.800 --> 00:04:28.639
that a little bit

00:04:28.639 --> 00:04:32.080
more later um it has has to do with how

00:04:32.080 --> 00:04:33.919
the tangling

00:04:33.919 --> 00:04:37.600
is uh done in the tangle step versus the

00:04:37.600 --> 00:04:39.280
weave step and I'll explain that a

00:04:39.280 --> 00:04:41.199
little bit more but the tangle

00:04:41.199 --> 00:04:45.199
field just simply tells tells uh

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
uh you'll 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:02.160
using

00:05:02.160 --> 00:05:05.360
the most lately uh but

00:05:05.360 --> 00:05:07.360
this programming strategy is language

00:05:07.360 --> 00:05:08.400
agnostic

00:05:08.400 --> 00:05:12.080
you could use any language or any mix

00:05:12.080 --> 00:05:14.720
of languages you could create some files

00:05:14.720 --> 00:05:16.560
in python some files and go

00:05:16.560 --> 00:05:19.520
some files in in lisp or whatever you

00:05:19.520 --> 00:05:21.520
want

00:05:21.520 --> 00:05:24.720
and so but let's

00:05:24.720 --> 00:05:28.000
uh let's create just a little hello

00:05:28.000 --> 00:05:29.440
world

00:05:29.440 --> 00:05:32.320
let's use another snippet here to

00:05:32.320 --> 00:05:33.520
generate

00:05:33.520 --> 00:05:36.560
the basics of a go program

00:05:36.560 --> 00:05:40.240
so 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.320
let's make it a section in our

00:05:52.320 --> 00:05:55.280
file so now you can see we've got this

00:05:55.280 --> 00:05:56.400
snippet

00:05:56.400 --> 00:05:59.600
um 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:02.880
into a

00:06:02.880 --> 00:06:04.960
language specific buffer by typing

00:06:04.960 --> 00:06:07.680
control c single quote

00:06:07.680 --> 00:06:10.240
so you can see now I have a a go 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:18.800
normally if you hit ctrl c

00:06:18.800 --> 00:06:20.800
single quote again then it goes back and

00:06:20.800 --> 00:06:22.639
any changes you

00:06:22.639 --> 00:06:25.280
make would will be updated there but you

00:06:25.280 --> 00:06:26.160
can do quite a bit

00:06:26.160 --> 00:06:28.000
just inside of here too there's quite a

00:06:28.000 --> 00:06:29.199
bit of

00:06:29.199 --> 00:06:33.360
language specific

00:06:33.360 --> 00:06:35.440
functionality just in place and so you

00:06:35.440 --> 00:06:36.880
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
but it's a it's a nice option sometimes

00:06:42.319 --> 00:06:44.319
but 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.560
but right now it just lives here in this

00:06:48.560 --> 00:06:50.240
documentation

00:06:50.240 --> 00:06:52.160
so 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:05.280
bit more

00:07:05.280 --> 00:07:12.240
documentation really quick here

00:07:12.240 --> 00:07:17.360
okay all right so just kind of as a

00:07:17.360 --> 00:07:21.520
kind of as a side note I like to follow

00:07:21.520 --> 00:07:24.800
this process uh whenever having whenever

00:07:24.800 --> 00:07:26.639
I have an operation to perform I

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 in line

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 I take the

00:07:40.319 --> 00:07:41.680
take the time to figure out what it is

00:07:41.680 --> 00:07:43.440
and document it and so then it's

00:07:43.440 --> 00:07:44.879
recorded

00:07:44.879 --> 00:07:48.400
and so here we find that to do a tangle

00:07:48.400 --> 00:07:49.120
operation

00:07:49.120 --> 00:07:51.680
you run the command or babel tangled

00:07:51.680 --> 00:07:52.560
which is a

00:07:52.560 --> 00:07:55.840
e-list command so if you hit ctrl c

00:07:55.840 --> 00:07:59.199
ctrl c to run it in place you get the

00:07:59.199 --> 00:08:00.080
result

00:08:00.080 --> 00:08:02.720
of main dot 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
and you can see that that's true

00:08:11.039 --> 00:08:14.000
if you go to the file system and you

00:08:14.000 --> 00:08:14.400
look

00:08:14.400 --> 00:08:17.840
so now in uh in our demo directory

00:08:17.840 --> 00:08:20.960
we have a readme.org we have that png

00:08:20.960 --> 00:08:22.479
that we generated but we also have a

00:08:22.479 --> 00:08:23.440
main.go

00:08:23.440 --> 00:08:26.080
and if you if you visit that file you'll

00:08:26.080 --> 00:08:27.759
see that it's just the source code that

00:08:27.759 --> 00:08:29.280
was in our documentation which is

00:08:29.280 --> 00:08:31.039
exactly what we expected and what we

00:08:31.039 --> 00:08:32.880
wanted so that's good

00:08:32.880 --> 00:08:36.560
so if we return to

00:08:36.560 --> 00:08:41.120
to where we are at

00:08:41.120 --> 00:08:42.959
now we're we're at the point where we

00:08:42.959 --> 00:08:44.640
have a file on the file system so now we

00:08:44.640 --> 00:08:45.760
need

00:08:45.760 --> 00:08:48.959
um now we need to build it and to

00:08:48.959 --> 00:08:53.600
run it so let's follow the same

00:08:53.600 --> 00:08:57.040
philosophy where let's document

00:08:57.040 --> 00:08:58.720
these operations that we're going to

00:08:58.720 --> 00:09:00.160
perform

00:09:00.160 --> 00:09:04.560
so I'm dropping in a

00:09:04.560 --> 00:09:07.839
a build instruction section and a run

00:09:07.839 --> 00:09:13.360
instruction section

00:09:13.360 --> 00:09:15.279
so 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:20.000
and another batch source block this one

00:09:20.000 --> 00:09:22.000
compiles the go build command is what

00:09:22.000 --> 00:09:25.440
compiles a file and then

00:09:25.440 --> 00:09:26.880
the file that gets generated should be

00:09:26.880 --> 00:09:30.080
called demo

00:09:30.080 --> 00:09:32.959
and uh so we just run it here so if if I

00:09:32.959 --> 00:09:34.000
type control c

00:09:34.000 --> 00:09:37.839
control c we get an empty results block

00:09:37.839 --> 00:09:40.640
when you compile things no news is good

00:09:40.640 --> 00:09:41.360
news

00:09:41.360 --> 00:09:44.399
so it means there's no errors so

00:09:44.399 --> 00:09:46.560
presumably we've created an executable

00:09:46.560 --> 00:09:48.000
that's called demo

00:09:48.000 --> 00:09:51.440
so let's uh

00:09:51.440 --> 00:09:54.560
let's look again at the file system and

00:09:54.560 --> 00:10:02.480
regenerate

00:10:02.480 --> 00:10:05.760
yep and what we have here is a demo

00:10:05.760 --> 00:10:07.200
executable which is exactly what we

00:10:07.200 --> 00:10:07.760
wanted

00:10:07.760 --> 00:10:12.079
so let's go back

00:10:12.079 --> 00:10:14.160
so now we should be able to run it so

00:10:14.160 --> 00:10:16.079
ctrl c ctrl 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 you can do that much

00:10:30.839 --> 00:10:33.040
um but

00:10:33.040 --> 00:10:34.560
that's really just kind of the tip of

00:10:34.560 --> 00:10:37.839
the iceberg to uh to really

00:10:37.839 --> 00:10:41.040
kind of um

00:10:41.040 --> 00:10:43.440
use the more impressive features of

00:10:43.440 --> 00:10:46.160
literate programming we need to uh

00:10:46.160 --> 00:10:49.920
we need to do a little bit more

00:10:49.920 --> 00:10:53.200
so or at least

00:10:53.200 --> 00:10:55.519
at least really to get the full benefit

00:10:55.519 --> 00:10:56.480
of it then

00:10:56.480 --> 00:10:59.600
we need to do

00:10:59.600 --> 00:11:02.959
add some sections that will cause uh

00:11:02.959 --> 00:11:06.320
Emacs to have to to tangle or assemble

00:11:06.320 --> 00:11:06.720
this

00:11:06.720 --> 00:11:09.760
this file from different pieces so

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 in

00:11:24.399 --> 00:11:29.360
imports section

00:11:29.360 --> 00:11:32.399
in a functions section

00:11:32.399 --> 00:11:35.040
and then maybe just a main section and

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.000
like a template or a scaffolding or

00:11:42.000 --> 00:11:42.880
outline

00:11:42.880 --> 00:11:46.000
for what what our file is going to be it

00:11:46.000 --> 00:11:48.399
looks a little bit like pseudocode

00:11:48.399 --> 00:11:50.800
and what we're going to have literate

00:11:50.800 --> 00:11:52.399
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
maybe called say hello so we want

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
um 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 but it's

00:12:27.839 --> 00:12:31.040
it just has a few differences so say we

00:12:31.040 --> 00:12:31.680
want to

00:12:31.680 --> 00:12:34.160
drop code into the import section and we

00:12:34.160 --> 00:12:36.639
want it to be in go

00:12:36.639 --> 00:12:39.120
here we use the same noed no web no

00:12:39.120 --> 00:12:40.720
export syntax

00:12:40.720 --> 00:12:43.200
but then we've added this no web refs

00:12:43.200 --> 00:12:44.560
imports

00:12:44.560 --> 00:12:48.240
and this ties that slot

00:12:48.240 --> 00:12:51.120
basically to this reference it tells

00:12:51.120 --> 00:12:53.760
Emacs that when you tangle

00:12:53.760 --> 00:12:56.880
we want to stick whatever's in here in

00:12:56.880 --> 00:12:58.240
that spot

00:12:58.240 --> 00:13:02.079
so 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 you're

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:18.839
so let's add another section for uh

00:13:18.839 --> 00:13:22.240
functions and let's create a

00:13:22.240 --> 00:13:25.519
let's just create a function called

00:13:25.519 --> 00:13:30.240
say hello that

00:13:30.240 --> 00:13:32.839
doesn't have any arguments no return

00:13:32.839 --> 00:13:34.000
types

00:13:34.000 --> 00:13:35.760
all it does is kind of pretty much the

00:13:35.760 --> 00:13:37.440
same thing as we did before

00:13:37.440 --> 00:13:39.199
just print something but let's just say

00:13:39.199 --> 00:13:41.360
hello

00:13:41.360 --> 00:13:45.760
Emacs comp this time

00:13:45.760 --> 00:13:49.519
okay so now we have a function and now

00:13:49.519 --> 00:13:51.040
the function won't do anything unless we

00:13:51.040 --> 00:13:52.720
invoke it so 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 and then let's

00:14:03.519 --> 00:14:06.560
just invoke

00:14:06.560 --> 00:14:10.320
that that function

00:14:10.320 --> 00:14:13.360
so now you can see that we've got

00:14:13.360 --> 00:14:15.600
our scaffolding scaffolding kind of

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
so I I've kind of used this syntax

00:14:25.440 --> 00:14:27.199
it's it's kind of borrowed from

00:14:27.199 --> 00:14:28.560
literature programming a little bit with

00:14:28.560 --> 00:14:30.320
a plus equals 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 so

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.519
when you generate documentation you

00:14:41.519 --> 00:14:43.519
won't see these

00:14:43.519 --> 00:14:46.160
these these particular property

00:14:46.160 --> 00:14:49.360
annotations and so you won't know

00:14:49.360 --> 00:14:51.440
immediately that this section goes in

00:14:51.440 --> 00:14:53.839
the imports area and 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
and 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.399
documentation above to explain what you

00:15:06.399 --> 00:15:07.360
were doing

00:15:07.360 --> 00:15:11.519
maybe right here

00:15:11.519 --> 00:15:13.279
you could you could picture yourself

00:15:13.279 --> 00:15:15.040
maybe explaining

00:15:15.040 --> 00:15:17.440
a complicated algorithm or something up

00:15:17.440 --> 00:15:18.079
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:29.920
tangle properly so your best friend

00:15:29.920 --> 00:15:33.519
at this point is is uh

00:15:33.519 --> 00:15:35.680
is a keyboard shortcut that lets you

00:15:35.680 --> 00:15:38.240
preview the tangled operation so if you

00:15:38.240 --> 00:15:38.959
say control

00:15:38.959 --> 00:15:42.560
c control v control v

00:15:42.560 --> 00:15:45.120
it will create a new buffer with the

00:15:45.120 --> 00:15:46.480
tangled

00:15:46.480 --> 00:15:49.360
contents and so you can see here that

00:15:49.360 --> 00:15:50.639
the fmt

00:15:50.639 --> 00:15:53.199
import went to the right place that

00:15:53.199 --> 00:15:54.720
function went to the right place the

00:15:54.720 --> 00:15:56.160
function invocation went to the right

00:15:56.160 --> 00:15:58.480
place and so we're feeling good

00:15:58.480 --> 00:16:01.279
you can nest these things many layers

00:16:01.279 --> 00:16:02.800
deep

00:16:02.800 --> 00:16:04.800
actually so like if you came into the

00:16:04.800 --> 00:16:07.199
say hello function you could add

00:16:07.199 --> 00:16:10.560
more sections

00:16:10.560 --> 00:16:12.160
you know and it gets and it'll go

00:16:12.160 --> 00:16:13.759
through and it'll

00:16:13.759 --> 00:16:15.680
keep track of all that and tangle it for

00:16:15.680 --> 00:16:16.959
you 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:19.600
document things

00:16:19.600 --> 00:16:22.320
by doing this so now that we've

00:16:22.320 --> 00:16:25.839
previewed it and we feel good about it

00:16:25.839 --> 00:16:28.639
we need to uh we need to tangle so we

00:16:28.639 --> 00:16:31.440
get the file on the file system

00:16:31.440 --> 00:16:34.480
so ctrl c ctrl c and

00:16:34.480 --> 00:16:37.199
get just main.go comes back again

00:16:37.199 --> 00:16:37.920
control c

00:16:37.920 --> 00:16:40.959
control c and no errors come back

00:16:40.959 --> 00:16:43.839
and then if we did this right when we

00:16:43.839 --> 00:16:45.600
when we run this we should get hello

00:16:45.600 --> 00:16:47.199
Emacs comp so ctrl c

00:16:47.199 --> 00:16:51.199
ctrl c hello Emacs comp

00:16:51.199 --> 00:16:54.800
so I uh

00:16:54.800 --> 00:16:57.120
I think that's pretty pretty cool

00:16:57.120 --> 00:16:58.240
actually so we've got

00:16:58.240 --> 00:17:00.160
kind of the breadcrumbs of the process

00:17:00.160 --> 00:17:02.399
we've gone through to get to this point

00:17:02.399 --> 00:17:05.520
this initial this initial

00:17:05.520 --> 00:17:08.000
document that has some tangling in it we

00:17:08.000 --> 00:17:09.919
have documentation for how to tangle

00:17:09.919 --> 00:17:12.799
how to build how to run it's we've

00:17:12.799 --> 00:17:14.079
really built a nice

00:17:14.079 --> 00:17:17.760
foundation for

00:17:17.760 --> 00:17:20.160
moving forward on our project and a nice

00:17:20.160 --> 00:17:21.439
way of breaking things out and

00:17:21.439 --> 00:17:23.280
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 I

00:17:30.559 --> 00:17:34.799
that's 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 so this time on how

00:17:41.760 --> 00:17:42.400
to weave

00:17:42.400 --> 00:17:44.400
so it's really just an export function

00:17:44.400 --> 00:17:47.520
it's not there's not a separate weave

00:17:47.520 --> 00:17:49.280
command going on here we're just going

00:17:49.280 --> 00:17:50.640
to export

00:17:50.640 --> 00:17:52.799
what we've got here into a markdown

00:17:52.799 --> 00:17:55.200
format so we're using org

00:17:55.200 --> 00:17:57.440
gfm export to markdown which is the

00:17:57.440 --> 00:17:58.880
github style

00:17:58.880 --> 00:18:02.160
markdown you can use the other just

00:18:02.160 --> 00:18:05.440
more standard type as well so hit ctrl c

00:18:05.440 --> 00:18:10.320
ctrl c now you see we've got a readme

00:18:10.320 --> 00:18:15.280
file and if you look

00:18:15.280 --> 00:18:17.440
in the file system we've got that right

00:18:17.440 --> 00:18:19.120
there and so

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:34.559
now you can see that it's generated some

00:18:34.559 --> 00:18:35.520
documentation

00:18:35.520 --> 00:18:38.320
it puts a index at top at the top I

00:18:38.320 --> 00:18:39.679
usually just

00:18:39.679 --> 00:18:42.000
I usually turn that off it's easy to do

00:18:42.000 --> 00:18:43.679
that by putting a property at the top of

00:18:43.679 --> 00:18:44.559
your

00:18:44.559 --> 00:18:46.880
your org file but some people like to

00:18:46.880 --> 00:18:48.559
have an index

00:18:48.559 --> 00:18:50.799
but here you can see that it's generated

00:18:50.799 --> 00:18:52.160
pretty nicely and

00:18:52.160 --> 00:18:55.200
formatted snippets well

00:18:55.200 --> 00:18:56.880
put the diagram in there and then it's

00:18:56.880 --> 00:18:58.240
preserved

00:18:58.240 --> 00:19:01.039
it's preserved this literate programming

00:19:01.039 --> 00:19:02.799
syntax

00:19:02.799 --> 00:19:04.960
which is important because that's how we

00:19:04.960 --> 00:19:06.480
want to view the documentation that's

00:19:06.480 --> 00:19:07.200
what the no

00:19:07.200 --> 00:19:10.559
exports um

00:19:10.559 --> 00:19:13.360
property was was trying to maintain so

00:19:13.360 --> 00:19:14.000
that

00:19:14.000 --> 00:19:16.080
no exports means when you export do not

00:19:16.080 --> 00:19:18.400
try to tangle so that's

00:19:18.400 --> 00:19:20.559
hopefully that makes more sense now but

00:19:20.559 --> 00:19:22.240
now you can see all the documentation

00:19:22.240 --> 00:19:26.080
and I think it demonstrates a

00:19:26.080 --> 00:19:29.919
pretty useful feature that's inside of

00:19:29.919 --> 00:19:33.520
Emacs and and hopefully

00:19:33.520 --> 00:19:35.039
hopefully you'll have as much fun using

00:19:35.039 --> 00:19:39.919
that as I have

00:19:39.919 --> 00:19:43.600
so thanks