blob: 3179635f57e650e84fb60ef0e60aa0026349870c (
plain) (
tree)
|
|
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
|
