As I slowly continue to document parts of the Cortex-M ports, I want to be able to make the process more accurate and integrated with the source code. Ideally, the documentation should never diverge from the sources, so the parts where code was quoted by copying and pasting it into preformatted sections needed to be automated. I was also unhappy with the basic functioning of the Markdown toolchain I was using, and took the chance to reduce the number of dependencies in play.
Previously, I would run markdown_py and fix up broken links with an Awk script. Since I would rather not have to fix links at all, and since I'm not really using Markdown's markup extensively, I decided to replace it with a more complicated Awk script. I could probably have written an extension to markdown_py, but thought it was more interesting to switch to Awk and implement a minimal set of markup.
I also wanted to keep the documentation and code in sync, so I introduced some markup to refer to source files, using regular expressions to select the lines of text to quote, as in the following example.
<<< sources/inferno-os/os/apollo3/l.s line: TEXT _usage_fault before: MOVW to: ADD
This extracts an excerpt of code from a locally-cloned repository:
TEXT _usage_fault(SB), THUMB, $-4
MOVW SP, R1 /* Record the interrupted stack pointer. */
ADD $0x68, R1 /* Includes FP registers. */
This reminds me of how qdoc works and is a lot simpler than other over-engineered documentation systems, though perhaps there's room for some kind of multi-line matching system.
I'm accustomed to seeing syntax highlighted code these days, so plain text in documentation is harder for me to parse. I didn't want to go all-in on highlighting, and especially didn't want to include Pygments as a dependency after dropping Python with the Markdown toolchain, so I added simple keyword highlighting. If I feel I'm missing out, I might look into doing something a bit more complex. It's not a high priority.