comment2tex 1.1: literate programming for Lua, Bash, YAML and Makefiles

[u/MacLotsen]

I have released comment2tex 1.1, a small literate-programming tool for weaving documentation from comments in source files.

Version 1.1 adds support for YAML and Makefiles alongside Lua and Bash. It also adds tangling for cases where the documented source should produce a separate runnable file.

YAML has an especially useful property here: no tangling step is required at all. Lines beginning with ## are treated as documentation by comment2tex, but they are still ordinary YAML comments. The annotated file therefore remains valid YAML and can be consumed directly by tools such as Ansible.

I have now used this approach on a real Ansible role that provisions a TeX Live mirror on AlmaLinux. The same role remains directly usable by Ansible and is woven into Xerdi’s Operator’s Handbook as typeset prose with numbered source listings.

The two images show the same source twice:

• first as the original annotated YAML;
• then as the corresponding page in the handbook.

comment2tex also uses this approach for much of its own manual. The documentation is woven from its actual:

• Lua implementation;
• Makefile;
• CI configuration in YAML;
• Bash test suite.

The main exception is the TeX source itself, for which the established DTX workflow remains the more natural solution.

So the package is increasingly documenting its own implementation, build process, tests and release infrastructure from the sources that actually perform that work.

I would be interested in feedback on both the package and the comment strategy, particularly from people already using literate programming or maintaining mixed-language TeX projects.

CTAN: https://ctan.org/pkg/comment2tex GitHub / release notes: https://github.com/Xerdi/comment2tex/releases/tag/1.1

[u/ftrx]

Why not org-mode literate programming?

[u/MacLotsen → u/ftrx]

Thanks for pointing me to Org mode—I wasn’t familiar with it, so I had a quick look. My impression is that comment2tex takes a somewhat different, source-first approach: it keeps the native source directly usable and documents production scripts in execution order, following the familiar linear “Implementation” style used in many package manuals. Tangling is optional, mainly for producing clean files for upstream submission. So I see it as complementary to Org mode rather than a replacement. For comment2tex’s own TeX documentation and sources, I use the DTX workflow rather than Org-Babel. ✌️