# README-Driven Design
Adam Ard

[[!template id=vid src="https://mirror.csclub.uwaterloo.ca/emacsconf/2020/emacsconf-2020--14-readme-driven-design--adam-ard.webm"]] 

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
programming to generate all of your source code directly from the
documentation. This strategy is a great way to keep your documentation
from getting outdated, and it allows you to use all the other
wonderful features of org-mode. Watch "README-Driven Design" to see
exactly how to make your README file a powerful literate document.
-   [Companion Blog Post](http://adamard.com/literate_programming.html)
-   [Extended Version of Demo File](https://github.com/adam-ard/literate-demo)
-   [Literate Static Website](https://github.com/adam-ard/static-website-literate-demo)
<!-- from the pad --->
-   Actual start and end time (EST): Start 2020-11-28T14.15.00; End: 2020-11-28T14.34.46


# Questions


## If you put all your code in an org file (in addition to prose), doesn't that make the file very large for medium/large projects? (Since all the code across all files is tangled from a single README.org)

You are right it would get pretty large. I haven't hit that point yet, but plan to experiment with separate org files that are imported into a master file.


## If a collaborator edits the tangled file(s), is reverse-tangling in org reliable? How do you integrate the reverse in a safe way?

So, I actually think this is the big unsolved problem right now. How to do reverse tangling. As far as I know, emacs doesn't do that. But it would really cool. I think it is probably a hard problem.
-   actually it does! you have to enable comments that mark the boundaries of the code blocks. (org-babel-detangle) -> org-babel-detangle is pretty fragile right now.
-   Oh wonderful! I will have to check that out. There is always more to discover in emacs. Thanks!


## Would this approach make it harder to collaborate with contributors who don't use org?/How to rectify these difficulties? (Thank you!)

I have had some sucess at work by managing an org file myself, then I commit the tangled code and a README.md. I have to manually update my org file though when someone makes a change to the raw source files. That process can be a pain. It would be awesome to find a way to make this easier. So that non-emacs users can collaborate and be unaware of the source org file. To have an annotation free reverse tangling process would be the holy grail of literate programming. Would be a great thesis project for someone.


## Interesting. Did you ever use this approach on a large project? Could one incorporate also TDD into this workflow?

I have only really hit the medium size. But would love to try a larger one. I have seen people write whole books in literate progamming though. (Not sure if they were using emacs) (one example: <http://www.pbr-book.org/> ). Here is a pretty large one I found on github: <https://github.com/nakkaya/ferret>

TDD is an interesting idea. I haven't tried doing that, but org seems flexible enough to build a workflow around that.


## Could you share the snippet for adding these source code blocks, it seems much better than the one I am using currently. Thanks!

Sure, it is documented in the literate programming demo here (<https://github.com/adam-ard/literate-demo> )


## In Python, indentation is part of the syntax. How is this handled when <a id="orgd70b75b"></a>-syntax is used for functions or even a few lines of codes that are get re-used in multiple functions? Does the user have to define different <a id="org3552e1e"></a> snippets for different indentations but otherwise identical code?

Not the speaker, but :noweb will add the prefix characters to all lines, see <https://orgmode.org/manual/Noweb-Reference-Syntax.html>. Python identation is fine (and used as an example in the manual :))
-   exactly, I have done a lot of python this way, it works great!


## Could this structure be used with a SQL query with the output being an Org table?

Yep, I have done that before too. Org will send the query to a database and insert the results. It is super nice. You can add block properties to set the hostname of the database too, so it isn't limited to just databases running on your local machine.


## Why do you export to Markdown when GitHub and others are supporting rendering Org directly?

Good question. I do this because I usually work with people that don't use emacs :( so I usually take the source files and the markdown and commit them to git. I keep the org file to myself. If everyone used emacs, I wouldn't bother with that step.


## This file would be very useful to have for us for reference, could you also share it please?

Yep! See the links below for a couple template files. An extended one from the talk is at: <https://github.com/adam-ard/literate-demo>


# Notes
-  Adam Ard: I'll be answering questions here in the pad or in #emacsconf (aard3)
-  Companion Blog Post: <http://adamard.com/literate_programming.html>
-  Extended Version of Demo File: <https://github.com/adam-ard/literate-demo>
-  Literate Static Website: <https://github.com/adam-ard/static-website-literate-demo>
-  If you want to learn what GitHub is able to render in Org syntax: <https://github.com/novoid/github-orgmode-tests>
-  <https://en.wikipedia.org/wiki/Literate_programming>
-  I am thinking about org-transclusion; similar ideas to deal with notes instead of codes
  - FYI: <https://github.com/alphapapa/transclusion-in-emacs>