Worgle
Description
Worgle is a fast and portable tangler for programs written in a limited subset of org, which includes noweb-style expansion for literate programming.
The source code can be found on sourcehut.
I wrote Worgle as a follow-up to my initial experiences with literate programming using org-mode While org and org-mode have the potential to be great modern-day tools for Knuthian-style literate programming, I found their current implementations to be inferior to CWEB Tangling org-code with emacs is painfully slow, to the point of being unusable. Tangled C/C++ code does not export line declaration macros, making debugging a terribly impractical experience.
Worgle is written in itself, and is bootstrapped using a minimalist ANSI C org tangler called Orgle.
In addition to tangling code, some initially steps have been taken to produce an HTML exporter, a process classically referred to as weaving code. This weaver, called Sorg, is also written in ANSI C using Worgle. While incomplete, it is quite usable. Examples of Sorg being used to generate HTML have been posted for Sorg and Worgle. In order to match the CSS of this website, these pages with sorg via a shell script.
TODO A 5 minute introduction
A fly-by tutorial for how to use Worgle.
Will get to this soon!
Bootstrapping Process
Worgle is itself a literate program written in Org, and can be tangled using itself. To do this, a bootstrapping process is derived.
First, a very primitive org tangler witten in ANSI C called orgle is compiled. This is written as a C file and does not need to be tangled.
Orgle is then used to create worglite, a limited version of
worgle that is somewhere in between orgle and worgle. This
is done by tangling worgle.org with orgle, and then
compiling it with -DWORGLITE. The main worgle.org is
written in such a way that it can be parsed and compiled
by itself with the original orgle program.
Finally, worglite is used to retangle worgle into the full version, where it can then be compiled into worgle. From there, all extra tools/components can use the full Worgle tangler.
TODO Org Subset
To keep the implementation lightweight, worgle uses a small subset of Org code.
Will write more on this later.
Relevant Wiki Pages
sqlite_export_worgle: Overview of the SQLite format Worgle can export too
worgmap: A utility for navigating programs written in Worgle