-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 -- cgit v1.2.3