hello
welcome to readme driven design in Emacs
by adam aard
if you're a programmer you're accustomed
to putting a readme file at the root of
your project
and it's usually a markdown file but if
you use an org
more an org mode file instead you can
take advantage of the great features
that org mode provides including
literate programming
which lets you generate your source code
and markdown documentation dynamically
I want to walk you through a little bit
of what this looks like
when you start a project especially if
if you use something like github you
begin with an automatically generated
readme.md file so just delete that
and instead create a readme.org file
starting with an empty org file like you
see here you can begin
by recording important information about
your project goals you can add diagrams
code snippets to-do lists time tracking
and much more
I'm going to drop in some documentation
that I r that I've written about
about my project here so you can kind of
see
what this would look like
so as you can see I have a title and a
description and then a sub section
as well as some code snippets
and you can see that orgmo does a great
job of formatting lists and
code sections diagrams and so forth
it's good or it's as good or better than
markdown
but when you use it in the Emacs you can
do a lot more
for example you can dynamically create
diagrams using graphviz
from a text description so if you go to
this source block here
and hit control c control c you'll see
that we generate a
diagram dynamically you can run
so you can run these code snippets in
place and get the results
to show up inside of your your file
which is a really powerful paradigm
but most important most importantly for
the
purposes my purpose is here
orgmo provides you the ability to do
literate programming
so take a quick look at this diagram
that I generated here
and gives you a quick overview of what I
mean by literate programming
and how I'm using it you can see
that we start with a readme.org file on
top
at this point we can do one of two
things
tangle or weave tangle is used to
describe the process of
generating source code while weave
is the process of generating
documentation these are terms that
donald knuth used
and he's the one that came up with the
idea of literate programming
in the early 1980s
but this is really all that there is to
it you just
who are simply using literate illiterate
source file
in this case the readme.org to generate
the rest of the project
the rest of the project files basically
so let's dig in to the details of how
this works
and I hope you hopefully you'll see how
cool this is
so returning to the file here let's
assume we have enough documentation now
that we want to get started
coding so maybe we'll just start with
like a hello world
app just so we can make sure that our
environment is set up correctly
so let's get started with a code block
so I created a little snippet to help me
add
a source block for literate programming
quickly
and there's not much to it
but there is some important annotations
here so there's
excuse me there's a there's a property
called tangle
and that takes a value of a file name
and then there's also a no web property
called no export
and basically
basically the no export will explain
that a little bit
more later um it has has to do with how
the tangling
is uh done in the tangle step versus the
weave step and I'll explain that a
little bit more but the tangle
field just simply tells tells uh
Emacs where it needs to generate the
main.go file and where it needs to put
it on the file system
uh you'll you'll notice that we we're
going to use go
that's just the language that I've been
using
the most lately uh but
this programming strategy is language
agnostic
you could use any language or any mix
of languages you could create some files
in python some files and go
some files in in lisp or whatever you
want
and so but let's
uh let's create just a little hello
world
let's use another snippet here to
generate
the basics of a go program
so I'm just going to print
hello world
so that's and then
let's make it a section in our
file so now you can see we've got this
snippet
um when you have a source block in
inside of org mode you can easily pop
into a
language specific buffer by typing
control c single quote
so you can see now I have a a go a
buffer that's in go mode
and gives you all the ability to edit
like you would
normally if you hit ctrl c
single quote again then it goes back and
any changes you
make would will be updated there but you
can do quite a bit
just inside of here too there's quite a
bit of
language specific
functionality just in place and so you
don't always have to go over to a
separate buffer
but it's a it's a nice option sometimes
but now that you have the code in here
you're going to want to run it
but right now it just lives here in this
documentation
so you need to get a copy of it into a
separate file
and that's the tangle process that you
you need to follow there so I'm gonna
drop in a little bit more doc a little
bit more
documentation really quick here
okay all right so just kind of as a
kind of as a side note I like to follow
this process uh whenever having whenever
I have an operation to perform I
I'd like to document it here with a
snippet that can be executed in line
then I don't have to leave org mode and
I don't have to try to remember what I
did later so instead of just
trying to do an operation the first time
I do something I take the
take the time to figure out what it is
and document it and so then it's
recorded
and so here we find that to do a tangle
operation
you run the command or babel tangled
which is a
e-list command so if you hit ctrl c
ctrl c to run it in place you get the
result
of main dot go which basically is
telling us that
we've tangled one file called main.go
and you can see that that's true
if you go to the file system and you
look
so now in uh in our demo directory
we have a readme.org we have that png
that we generated but we also have a
main.go
and if you if you visit that file you'll
see that it's just the source code that
was in our documentation which is
exactly what we expected and what we
wanted so that's good
so if we return to
to where we are at
now we're we're at the point where we
have a file on the file system so now we
need
um now we need to build it and to
run it so let's follow the same
philosophy where let's document
these operations that we're going to
perform
so I'm dropping in a
a build instruction section and a run
instruction section
so as you can see here we have a little
a bash source block
and another batch source block this one
compiles the go build command is what
compiles a file and then
the file that gets generated should be
called demo
and uh so we just run it here so if if I
type control c
control c we get an empty results block
when you compile things no news is good
news
so it means there's no errors so
presumably we've created an executable
that's called demo
so let's uh
let's look again at the file system and
regenerate
yep and what we have here is a demo
executable which is exactly what we
wanted
so let's go back
so now we should be able to run it so
ctrl c ctrl c
and we get hello world as a result
which was exactly what we were expecting
so that's already pretty cool
you can you can do that much
um but
that's really just kind of the tip of
the iceberg to uh to really
kind of um
use the more impressive features of
literate programming we need to uh
we need to do a little bit more
so or at least
at least really to get the full benefit
of it then
we need to do
add some sections that will cause uh
Emacs to have to to tangle or assemble
this
this file from different pieces so
imagine that we wanted to take this file
and maybe kind of templatize it
so using literature programming syntax
this angle bracket syntax
let's say that we want to create an in
imports section
in a functions section
and then maybe just a main section and
we'll get rid of this
so now you see we've created something
that looks a little bit like a
like a template or a scaffolding or
outline
for what what our file is going to be it
looks a little bit like pseudocode
and what we're going to have literate
programming do
is dynamically insert those things into
those slots
so the first thing we need to do
is so let's create a section
maybe called say hello so we want
we want to add some functionality that
makes our program say hello
so using a different snippet that I have
for creating something
that I call like a literate section
um basically we create a
another source block that's almost the
same as the one for the file but it's
it just has a few differences so say we
want to
drop code into the import section and we
want it to be in go
here we use the same noed no web no
export syntax
but then we've added this no web refs
imports
and this ties that slot
basically to this reference it tells
Emacs that when you tangle
we want to stick whatever's in here in
that spot
so you skip the tangle file name section
because you're not actually creating a
file name you're
you're putting information into an
existing file
so here we would just add the fmt
for the imports
so let's add another section for uh
functions and let's create a
let's just create a function called
say hello that
doesn't have any arguments no return
types
all it does is kind of pretty much the
same thing as we did before
just print something but let's just say
hello
Emacs comp this time
okay so now we have a function and now
the function won't do anything unless we
invoke it so let's do
one last literate section
called main make that go
source block and then let's
just invoke
that that function
so now you can see that we've got
our scaffolding scaffolding kind of
outline and then we have
the sections that we want to get tangled
or inserted
so I I've kind of used this syntax
it's it's kind of borrowed from
literature programming a little bit with
a plus equals so really it's just saying
that I want to append
this item into the import section so
it's really just to make a little bit
more clear what's going on
when you generate documentation you
won't see these
these these particular property
annotations and so you won't know
immediately that this section goes in
the imports area and so I usually put
a little bit of documentation on top
there so that it's easy to see
and you would probably if this was very
complicated you'd put some
documentation above to explain what you
were doing
maybe right here
you could you could picture yourself
maybe explaining
a complicated algorithm or something up
here
and having a nice way to document it
so now that we've got that here in the
documentation we need to figure out
we need to make sure that it's going to
tangle properly so your best friend
at this point is is uh
is a keyboard shortcut that lets you
preview the tangled operation so if you
say control
c control v control v
it will create a new buffer with the
tangled
contents and so you can see here that
the fmt
import went to the right place that
function went to the right place the
function invocation went to the right
place and so we're feeling good
you can nest these things many layers
deep
actually so like if you came into the
say hello function you could add
more sections
you know and it gets and it'll go
through and it'll
keep track of all that and tangle it for
you so you really get a lot of freedom
and flexibility for how you want to
document things
by doing this so now that we've
previewed it and we feel good about it
we need to uh we need to tangle so we
get the file on the file system
so ctrl c ctrl c and
get just main.go comes back again
control c
control c and no errors come back
and then if we did this right when we
when we run this we should get hello
Emacs comp so ctrl c
ctrl c hello Emacs comp
so I uh
I think that's pretty pretty cool
actually so we've got
kind of the breadcrumbs of the process
we've gone through to get to this point
this initial this initial
document that has some tangling in it we
have documentation for how to tangle
how to build how to run it's we've
really built a nice
foundation for
moving forward on our project and a nice
way of breaking things out and
documenting further
the last piece that we need to
take care of is the weave that I
that's I showed you in the diagram above
so one more time we'll drop in
some documentation so this time on how
to weave
so it's really just an export function
it's not there's not a separate weave
command going on here we're just going
to export
what we've got here into a markdown
format so we're using org
gfm export to markdown which is the
github style
markdown you can use the other just
more standard type as well so hit ctrl c
ctrl c now you see we've got a readme
file and if you look
in the file system we've got that right
there and so
if you go to something like ghostwriter
and open that file
now you can see that it's generated some
documentation
it puts a index at top at the top I
usually just
I usually turn that off it's easy to do
that by putting a property at the top of
your
your org file but some people like to
have an index
but here you can see that it's generated
pretty nicely and
formatted snippets well
put the diagram in there and then it's
preserved
it's preserved this literate programming
syntax
which is important because that's how we
want to view the documentation that's
what the no
exports um
property was was trying to maintain so
that
no exports means when you export do not
try to tangle so that's
hopefully that makes more sense now but
now you can see all the documentation
and I think it demonstrates a
pretty useful feature that's inside of
Emacs and and hopefully
hopefully you'll have as much fun using
that as I have
so thanks