I'm using the README.org as a "container" to structure simple projects as literate programms. The programs for each project are contained in and built by (tangled from) the file that documents them. Meanwhile, I provide documentation in other formats such as Markdown, generated using org-export.
People sometimes offer edits to those generated files.
When I'm trying to see if something works (meaning does what i need, I assume a given program does what someone wants) I usually prefer the command line, if not an actual script.
I don't mind when a GUI program wraps workflow, usually. In fact, I often select a GUI program just to avoid learning about the underlying programmatic work in more detail. When it comes to my coding workflow, however, I've essentially zero tolerance for tools "lock-in". At least, unless until proven I can script said tool fairly reliably.
I'm using windows, so this "scripting" started with a DOS command:
D:\projects\org-git-hooks\test>c:\emacs\bin\emacs -batch -eval "...elisp..."
The lisp in there isn't so bad, once it's formatted, and such:
(let ((load-path (append (list \"~/.emacs.d/elpa/ox-json-20191225.750\" \"~/.emacs.d/elpa/s-20180406.808\") load-path))) (require 'ox-json) (find-file \"README.org\") (org-export-to-file 'json \"README.json\"))
This creates README.json
D:\projects\org-git-hooks\test>ls -altr total 71 -rw-r--r-- 1 corwi 197609 231 Jul 17 14:41 README.org -rw-r--r-- 1 corwi 197609 1582 Jul 17 14:41 build.el -rw-r--r-- 1 corwi 197609 142 Jul 17 14:42 .env -rw-r--r-- 1 corwi 197609 12288 Jul 17 14:53 .post-commit.swp -rw-r--r-- 1 corwi 197609 169 Jul 17 15:05 README.md~ -rw-r--r-- 1 corwi 197609 10072 Jul 17 15:05 README.html~ -rw-r--r-- 1 corwi 197609 275 Jul 17 15:05 README.txt~ -rwxr-xr-x 1 corwi 197609 1466 Jul 17 15:06 post-commit -rw-r--r-- 1 corwi 197609 169 Jul 17 15:06 README.md -rw-r--r-- 1 corwi 197609 10072 Jul 17 15:06 README.html -rw-r--r-- 1 corwi 197609 275 Jul 17 15:06 README.txt drwxr-xr-x 1 corwi 197609 0 Jul 21 19:46 .. -rw-r--r-- 1 corwi 197609 270 Jul 24 03:06 newfile.org drwxr-xr-x 1 corwi 197609 0 Jul 24 04:12 .git -rw-r--r-- 1 corwi 197609 1875 Jul 24 04:12 README.json drwxr-xr-x 1 corwi 197609 0 Jul 24 04:12 . D:\projects\org-git-hooks\test>
Wait, Why Would You Do That?
The basic contention of work-flows (editing generated files) appears to be a deep problem-space, at least if I trouble for any sort of robust solution.
In fact, while I now use literate teniqutes for rather tribal projects, I have more complex things I'd like to move toward this style. That said, I'm trying to approach this in terms of building blocks. These should be stand-alone programs that I might "composed" into more sophisticated work-flows. I would like to avoid, in particular, providing much new meta-data or mark-up or whatever that needs to be added into whatever documents. We'll see how that goes.
I think I'll prefer maintaining a set of discreet scripts/projects with specific and narrow aims. Beside being more fun to hack on or try writing tests for (at least, to begin with), this seems to maximize the potential some bits of my "architecture" will be useful to others, thus a greater chance of catching subtle errors, etc.
How does This Help?
This particular program is useful to render a single complete org-document into a JSON file.
In the examples above, the source file must be called README.org and the target is always README.json. I often hard-code filenames early on; no sense in adding options to a failed experiment. Hopefully adjusting them to your actual org and desired JSON filenames (and writing shell invocation appropriate to your OS) isn't any real challenge.
Which Leads… Where?
I think there's some hope for a multi-pass system. I'd like to "resync" documents as various generated forms of the underlying content change. This would involve accepting granular edits back into the README.org (from MD and perhaps other formats, as those versions are edited) without "disturbing" the richer set of meta-data org captures.
I'll talk more about how things might works, generally, in another post. Probably sooner, I'll be talking about more tiny-tools like this one.
Meanwhile, this blog is made with a series of org-documents, often duplicating (or referencing, etc) other code. At present, this is a cobbled together mess and involves lots of duplicated files and/or copy-pasting. As pieces such as this one come together into meaningful hunks of my "preferred workflows", I hope to maintain this blog using some of these tools.
While the path toward my ideal "literate blog and related coding workflow" remains unclear, there may be a just bit little less fog.
Thanks for reading.