Literate Programming is a great way to write computer software, particularly in fields like data science where data processing workflows are complex and often need much background information. I started to write about Literate Programming a few months ago, and now it is the time to formalize how I create Literate Programming applications.<\/p>\n
This blog post belong to a series of posts about Literate [Clojure] Programming:<\/p>\n
<\/p>\n
The structure of a programming project can vary a lot. The structure I am using when developing Clojure is the one created by Leiningen<\/a> which I use for creating and managing my Clojure projects. The structure of a simple project (in this case, the org-mode-clj-tests-utils<\/a> project that I created for another blog post) looks like this:<\/p>\n There are 4 main components to this structure:<\/p>\n This kind of project outline is really simple and typical. Now let’s see what the structure would look like if this project would be created using Literate [Clojure] Programming.<\/p>\n<\/div>\n<\/div>\n The best way and cleanest way I found to create and manage the Org-mode files is to create a The new structure would look like that:<\/p>\n The idea here is that all the files that needs to be modified related to the project would become a Org-mode file. Such files are the code source files, the test files, possible other documentation files and the Anything I am writing for this project comes from a Org-mode file. All the development occurs in Org-mode. If someone would want to modify such a Literate Clojure application, then they would have to modify the Org-mode file and not the source files otherwise the changes would be overwritten by the next tangling operation.<\/p>\n<\/div>\n<\/div>\n Finally, I created a series of Org-mode files that are used to perform special tasks such as:<\/p>\n These are Org-mode files that can be executed to perform these tasks. In the case of tangling all project files at once, it would be necessary to use it if you haven’t changed the behavior of your Emacs to automatically tangle files on save.<\/p>\n The second file is to publish These two files are directly located into the As you can see, a Literate Clojure application is not much different. The way to program such an application is more profound than the small changes that occur at the level of the folder structure.<\/p>\n There is still an open question related to publishing this kind of Literate work on repositories such as Git: should only the The next blog post of that series will explain how the Org-mode source files are actually created, what is their internal structure, how they are organized and used.<\/p>\n<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":" Literate Programming is a great way to write computer software, particularly in fields like data science where data processing workflows are complex and often need much background information. I started to write about Literate Programming a few months ago, and now it is the time to formalize how I create Literate Programming applications. This blog […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[251,279,277,66],"tags":[252,254,274,276],"class_list":["post-3241","post","type-post","status-publish","format-standard","hentry","category-clojure","category-emacs","category-literate-programming","category-programming","tag-clojure-2","tag-emacs","tag-literateprogramming","tag-orgmode"],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts\/3241","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/comments?post=3241"}],"version-history":[{"count":11,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts\/3241\/revisions"}],"predecessor-version":[{"id":3617,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts\/3241\/revisions\/3617"}],"wp:attachment":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/media?parent=3241"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/categories?post=3241"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/tags?post=3241"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}- CHANGELOG.md\n- LICENCE\n- README.md\n- resources\n- pom.xml\n- project.clj\n- src\n - org_mode_clj_tests_utils\n - core.clj\n- target\n- test\n - org_mode_clj_tests_utils\n - core_test.clj\n<\/pre>\n
\n
project.clj<\/code> file which is used by Leiningen to configure the project<\/li>\nsrc<\/code> folder where the project’s code files [to be compiled] are located<\/li>\ntarget<\/code> folder is where the compiled files will be available, and<\/li>\ntest<\/code> folder where the unit tests for the code sources are located<\/li>\n<\/ol>\nLiterate Clojure Folder Structure<\/h3>\n
org<\/code> directory at the same level as the src<\/code> one. Then to replicate the same folder structure that exists in the src<\/code> folder. The names of the source files should be the same except that they have the .org<\/code> file extension. For example, the src\/core.clj<\/code> file would become org\/core.org<\/code> in the Org-mode folder, and the org\/core.org<\/code> file is used to tangle<\/i> (create) the src\/core.clj<\/code> file.<\/p>\n- CHANGELOG.md\n- LICENCE\n- README.md\n- resources\n- org\n - project.org\n - org_mode_clj_tests_utils\n - core.org\n- pom.xml\n- project.clj\n- src\n - org_mode_clj_tests_utils\n - core.clj\n- target\n- test\n - org_mode_clj_tests_utils\n - core_test.clj\n<\/pre>\n
project.clj<\/code> file. When the Org-mode files will be tangled, then all the appropriate files, required by the Clojure project would be generated.<\/p>\nUtilities Org-mode Files<\/h3>\n
\n
weaved<\/code> documentation in multiple different formats (HTML, LaTeX, etc.) as required, all at once.<\/p>\n\/org\/<\/code> folder. I will explain how they work in a subsequent post in that series. The final structure of a Literate Clojure project is:<\/p>\n- CHANGELOG.md\n- LICENCE\n- README.md\n- resources\n- org\n - project.org\n - publish.org\n - tangle-all.org\n - setup.org\n - org_mode_clj_tests_utils\n - core.org\n- pom.xml\n- project.clj\n- src\n - org_mode_clj_tests_utils\n - core.clj\n- target\n- test\n - org_mode_clj_tests_utils\n - core_test.clj\n<\/pre>\n<\/div>\n<\/div>\n
Conclusion<\/h3>\n
org<\/code> folder be added to a Git repository, or should we also add the files that get tangled as well? In an ideal World, only the org<\/code> files would need to go into the repository. However, depending on the nature of work (work only accessible by you, or work accessible by a group of people that know Org-mode, or making the project public on GitHub, etc.) we may have to commit the tangled files too. In the case of an open source project, I think it is required since many people unfamiliar with Org-mode won’t be able to use the codebase because they won’t be able to tangle it from the Org files. For this specific reason, I tend to publish the org<\/code> files along with all the files that get tangled from them. That way I am sure that even if the users of the library doesn’t know anything about Org-mode or Literate Programming they could still use the code. The only thing I try to take care of is to commit the Org file and the tangled file related to a specific change in the same commit, and I try not to create two commits, one for each file.<\/p>\n