racket-and-asciidoc.adoc

Converting .adoc to .html

Racket preprocessor

After all the $ADOC…​ batch files have been populated, the build runs a Racket preprocessor on the entries in $ADOCABLES_INPUT to create the .cached/*.asc files.

This is because the .adoc files created by the curriculum authors contains some directives in addition to the commands provided by raw AsciiDoc. A Racket program preprocesses these away to create a raw AsciiDoc file. This has the extension .asc and is situated in a .cached subdir alongside the .adoc file penned by the author.

The additional keyword values provided in the $ADOCABLES_INPUT enables the Racket preprocessor to correctly address the different types of .adoc files we have (workbook pages, lesson plans, narratives, etc.).

A single Racket call is sufficient to process all the entries in $ADOCABLES_INPUT.

Primitives used

When processing lesson files (whether lesson plan, work page, or a file included by them), the primitives found in it are stored in temp files in .cached. These become useful when creating a collective description of all the courses and lessons.

Exercise files

Special directives — @printable-exercise, @opt-printable-exercise, @handout — are used to include files within the lesson directory that are meant to be exercises. Their names are stored in .cached/.lesson-exercises.txt.kp. Again these are useful for the collective description.

Calling Asciidoctor

Once the Racket preprocessor done, we have a bunch of .cached/*.asc files in the distribution, and the list of these we have already captured in the file $ADOC_INPUT.

These files are now ready to be processed by Asciidoctor to produce the corresponding .html.

The asciidoctor command can take a bunch of input files as command-line input, so we pass it the contents of $ADOC_INPUT.