diff options
Diffstat (limited to '2020/info/14.md')
| -rw-r--r-- | 2020/info/14.md | 436 |
1 files changed, 435 insertions, 1 deletions
diff --git a/2020/info/14.md b/2020/info/14.md index 9d7ee315..e6e4e127 100644 --- a/2020/info/14.md +++ b/2020/info/14.md @@ -2,7 +2,8 @@ Adam Ard [[!template id=vid src="https://mirror.csclub.uwaterloo.ca/emacsconf/2020/emacsconf-2020--14-readme-driven-design--adam-ard.webm" subtitles="/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt"]] -[Download compressed .webm video (21.4M)](https://mirror.csclub.uwaterloo.ca/emacsconf/2020/smaller/emacsconf-2020--14-readme-driven-design--adam-ard--vp9-q56-video-original-audio.webm) +[Download compressed .webm video (21.4M)](https://mirror.csclub.uwaterloo.ca/emacsconf/2020/smaller/emacsconf-2020--14-readme-driven-design--adam-ard--vp9-q56-video-original-audio.webm) +[View transcript](#transcript) Many source code projects these days begin with a README file. While most people use markdown, if you use org-mode, you can use literate @@ -104,3 +105,436 @@ from the talk is at: <https://github.com/adam-ard/literate-demo> - I am thinking about org-transclusion; similar ideas to deal with notes instead of codes. - FYI: <https://github.com/alphapapa/transclusion-in-emacs>. + +<a name="transcript"></a> +# Transcript + +00:00:03.600 --> 00:00:37.120 +Adam: 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. It's usually a Markdown +file But if you use 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. + +00:00:37.120 --> 00:01:03.520 +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. + +00:01:03.520 --> 00:01:38.880 +I'm going to drop in some documentation +that I've written about about my project +here, so you can see what this would +look like. As you can see, I have a +title, and a description, and then a +subsection as well as some code +snippets. You can see that Org Mode does +a great job of formatting lists, code +sections, diagrams, and so forth. It's +as good or better than Markdown, but +when you use it in Emacs you can do a +lot more. + +00:01:38.880 --> 00:02:08.000 +For example, you can dynamically create +diagrams using Graphviz from a text +description. If you go to this source +block here and hit C-c C-c, you'll see +that we generate a diagram dynamically +You can run these code snippets in place +and get the results to show up inside of +your file, which is a really powerful +paradigm. + +00:02:08.000 --> 00:02:19.520 +But most importantly, for my purposes +here, Org Mode provides you the ability +to do literate programming. + +00:02:19.520 --> 00:02:34.720 +So take a quick look at this diagram +that I generated here. It 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. + +00:02:34.720 --> 00:03:17.120 +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. 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... You are simply using a +literate source file, in this case the +README.org, to generate the rest of the +project files, basically. + +00:03:17.120 --> 00:03:59.479 +So let's dig in to the details of how +this works. 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. 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. There's not much to it, but +there are some important annotations +here. + +00:04:01.599 --> 00:04:55.360 +Excuse me. There's a property called +:tangle and that takes a value of a file +name. Then there's also a :noweb +property called no-export. Basically, +the noexport--we'll explain that a +little bit more later It has to do with +how the tangling is done in the tangle +step versus the weave step. I'll explain +that a little bit more. But the tangle +field just simply tells Emacs where it +needs to generate the main.go file and +where it needs to put it on the file +system. + +00:04:55.360 --> 00:05:21.520 +You'll notice that we're going to use +Go. That's just the language that I've +been using the most lately, 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 in Go, some files in Lisp, or +whatever you want. + +00:05:24.720 --> 00:05:56.400 +Let's create just a little Hello World. +Let's use another snippet here to +generate the basics of a Go program. 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. + +00:05:56.400 --> 00:06:42.319 +When you have a source block in inside +of Org Mode, you can easily pop into a +language-specific buffer by typing C-c ' +(single quote). So you can see, now I +have a buffer that's in go-mode and +gives you all the ability to edit like +you would normally. If you hit C-c ' +(single quote) again, it goes back and +any changes you make 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, so you don't always have to go +over to a separate buffer. It's a nice +option sometimes. + +00:06:42.319 --> 00:07:12.240 +Now that you have the code in here, +you're going to want to run it. Right +now, it just lives here in this +documentation. 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. + +00:07:12.240 --> 00:07:44.879 +Okay, all right. So just as a side note, +I like to follow this process. Whenever +I have an operation to perform, I'd like +to document it here with a snippet that +can be executed inline. 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 time to figure out +what it is and document it, so then it's +recorded. + +00:07:44.879 --> 00:08:14.400 +So here we find that to do a tangle +operation, you run the command +org-babel-tangle, which is an Elisp +command. If you hit C-c C-c to run it in +place, you get the result of main.go, +which basically is telling us that we've +tangled one file called main.go. You can +see that that's true if you go to the +file system and you look. + +00:08:14.400 --> 00:08:41.120 +Now in our demo directory, we have a +README.org, we have that PNG that we +generated, but we also have a main.go. +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 where we were at... + +00:08:41.120 --> 00:09:43.012 +Now we're at the point where we have a +file on the file system. 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. I'm dropping in a a +build instruction section and a run +instruction section. As you can see +here, we have a little a bash source +block, and another bash source block. +This one compiles. The go build command +is what compiles a file. Then the file +that gets generated should be called +demo. So we just run it here. If I type +C-c C-c, we get an empty results block. +When you compile things, no news is good +news. It means there's no errors. + +00:09:43.012 --> 00:10:30.839 +So presumably, we've created an +executable that's called demo. Let's +look again at the file system and +regenerate... Yep. What we have here is +a demo executable, which is exactly what +we wanted. Let's go back. Now we should +be able to run it. C-c C-c, and we get +Hello World as a result, which was +exactly what we were expecting. So +that's already pretty cool. You can do +that much. + +00:10:33.040 --> 00:11:09.760 +That's really just the tip of the +iceberg. To really use the more +impressive features of literate +programming, we need to do a little bit +more at least. Really, to get the full +benefit of it, we need to add some +sections that will cause Emacs to have +to tangle or assemble this file from +different pieces. + +00:11:09.760 --> 00:11:36.240 +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 imports +section, a functions section, and then +maybe just a main section. We'll get rid +of this. + +00:11:36.240 --> 00:11:56.639 +So now you see, we've created something +that looks a little bit like a template +or a scaffolding or outline for what our +file is going to be. It looks a little +bit like pseudocode. What we're going to +have literate programming do is +dynamically insert those things into +those slots. + +00:11:56.639 --> 00:12:36.639 +So the first thing we need to do is... +So let's create a section called "Say +Hello." 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, basically, +we create a another source block that's +almost the same as the one for the file. +It just has a few differences. Say we +want to drop code into the import +section and we want it to be in Go. + +00:12:36.639 --> 00:13:14.399 +Here we use the same :noweb no-export +syntax, but then we've added this +:noweb-ref imports, and this ties that +slot to this reference. It tells Emacs +that when you tangle, we want to stick +whatever's in here in that spot. You +skip the tangle file name section +because you're not actually creating a +file name. You're putting information +into an existing file. So here, we would +just add the "fmt" for the imports. + +00:13:14.399 --> 00:14:10.320 +Let's add another section for functions. +Let's just create a function called +sayHello that doesn't have any +arguments. No return types. All it does +is pretty much the same thing as we did +before: just print something. Let's just +say "Hello EmacsConf" this time. Now we +have a function, and now the function +won't do anything unless we invoke it. +Let's do one last literate section +called main. Make that Go source block. +Then let's invoke that function. + +00:14:10.320 --> 00:14:39.839 +Now you can see that we've got our +scaffolding outline, and then we have +the sections that we want to get tangled +or inserted. I've used this syntax. It's +kinda borrowed from literate programming +a little bit with a +=, so really it's +just saying that I want to append this +item into the import section It's really +just to make a little bit more clear +what's going on. + +00:14:39.839 --> 00:14:57.760 +When you generate documentation, you +won't see these particular property +annotations, and so you won't know +immediately that this section goes in +the imports area. So I usually put a +little bit of documentation on top +there, so that it's easy to see. + +00:14:57.760 --> 00:15:21.120 +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 +picture yourself maybe explaining a +complicated algorithm or something up +here and having a nice way to document +it. + +00:15:21.120 --> 00:15:28.045 +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. + +00:15:28.045 --> 00:16:20.479 +Your best friend at this point is a +keyboard shortcut that lets you preview +the tangled operation. If you say C-c +C-v C-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. We're feeling +good. You can nest these things many +layers deep. If you came into the +sayHello function, you could add more +sections. 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. + +00:16:20.479 --> 00:16:57.645 +So now that we've previewed it and we +feel good about it, we need to tangle so +we get the file on the file system. so +C-c C-c and get... just main.go comes +back again. C-c C-c and no errors come +back. Then if we did this right, when we +run this, we should get "Hello, +EmacsConf." So C-c C-c, Hello EmacsConf. +I think that's pretty, pretty cool, +actually. + +00:16:57.645 --> 00:17:23.280 +So we've got the breadcrumbs of the +process we've gone through to get to +this point, this initial document that +has some tangling in it. We have +documentation for how to tangle, how to +build, how to run. We've really built a +nice foundation for moving forward on +our project and a nice way of breaking +things out and documenting further. + +00:17:23.280 --> 00:17:38.640 +The last piece that we need to +take care of is the weave that +I showed you in the diagram above. +So one more time, we'll drop in + +00:17:38.640 --> 00:18:35.520 +some documentation, this time on how to +weave. 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. We're +using org-gfm-export-to-markdown, which +is the Github style markdown. You can +use the other, more standard type as +well. Hit C-c C-c. Now you see we've got +a README file, and if you look in the +file system, we've got that right there. +If you go to something like ghostwriter +and open that file, now you can see that +it's generated some documentation. + +00:18:35.520 --> 00:18:48.559 +It puts a index at top at the top. I +usually turn that off. It's easy to do +that by putting a property at the top of +your Org file, but some people like to +have an index. + +00:18:48.559 --> 00:19:22.802 +Here you can see that it has generated +pretty nicely and formatted snippets +well, put the diagram in there, and then +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 property was trying to +maintain. no-exports means when you +export, do not try to tangle. + +00:19:22.802 --> 00:19:43.600 +Hopefully that makes more sense now. Now +you can see all the documentation. I +think it demonstrates a pretty useful +feature that's inside of Emacs. +Hopefully you'll have as much fun using +that as I have. So thanks! |