Book Post-Processing Scripts

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• create_metafiles.rb
• batch-prettify-node.js
• batch-prettify.js
• get-math.js
• put-math.js

The Book Post-Processing Scripts are a collection of utility programs written in Node.js, Ruby, and Perl designed to transform raw HTML output into a polished, modern digital book. These scripts bridge the gap between the static output of the Texinfo documentation system and the requirements of high-quality HTML5 and EPUB3 formats, handling tasks such as syntax highlighting, mathematical formula rendering, and metadata generation.

The primary workflow involves cleaning up HTML files generated from the sicp-pocket.texi source, injecting sophisticated features like MathML for equations and prettified code blocks for Scheme and Rust examples. This automated pipeline ensures that the final "Structure and Interpretation of Computer Programs" (SICP) digital versions remain responsive and visually consistent across various devices.
Sources: README.md:1-25, batch-prettify-node.js:1-10

Build Pipeline Overview

The post-processing phase is triggered via the project's Makefile. It requires a runtime environment consisting of Texinfo 5.1, Perl 5.12+, Ruby 1.9.3+, and Node.js. The pipeline transforms TeX source into a directory of HTML files, which are then sequentially modified by the scripts described below.
Sources: README.md:27-38

The diagram shows the sequence of transformations applied to the book content after initial HTML generation.
Sources: README.md:27-38, create_metafiles.rb:160-165

Syntax Highlighting Implementation

Code blocks in the SICP-Rust project are highlighted using a server-side execution of the Google Code Prettify library. The project utilizes two iterations of this logic: a legacy PhantomJS script and a modern Node.js implementation.

Batch Prettification Logic

The script batch-prettify-node.js uses jsdom to simulate a browser environment. It performs the following steps:

1. Environment Setup: Loads prettify.js and language-specific handlers for Lisp (lang-lisp.js) and Rust (lang-rust.js).
2. DOM Manipulation: Identifies <pre> blocks with classes lisp, rust, or example and adds the prettyprint class.
3. Execution: Runs the prettyPrint() function within the virtual DOM to inject <span> tags with CSS classes for syntax tokens.
4. Cleanup: Removes the temporary script tags from the document before serializing the modified HTML back to disk.
   Sources: batch-prettify-node.js:35-95, batch-prettify.js:40-65

Script	Runtime	Key Dependency	Purpose
batch-prettify-node.js	Node.js	jsdom	Modern, synchronous HTML prettification.
batch-prettify.js	PhantomJS	webpage	Legacy asynchronous prettification (deprecated).
Sources: batch-prettify-node.js:1-10, batch-prettify.js:1-15

Mathematical Formula Rendering

Mathematical content in the project is written in LaTeX but rendered as MathML for native browser and EPUB3 compatibility. This is achieved through a two-stage process using MathJax v3.

1. Extraction and Conversion (get-math.js)

This script scans HTML files for LaTeX delimiters—\( \) for inline and \[ \] for display math. It builds a JSON database (json_db) that maps unique LaTeX strings to their corresponding MathML representation.

• Optimization: The script loads the existing database and only converts new LaTeX expressions to minimize processing time.
• Technology: Uses mathjax-full with TeX input and SerializedMmlVisitor.
  Sources: get-math.js:15-60, get-math.js:95-140

2. Injection (put-math.js)

The put-math.js script reads the JSON database and replaces the LaTeX text in the HTML files with the generated MathML tags. If a mapping is missing, it wraps the LaTeX in a blue-colored span for debugging.
Sources: put-math.js:1-45

The sequence diagram illustrates the decoupled extraction and injection phases of the math processing system.
Sources: get-math.js:70-90, put-math.js:30-45

EPUB3 Metadata and Navigation Generation

The create_metafiles.rb script is responsible for generating the structural files required for an EPUB3 package: the Navigation Document (toc.xhtml) and the Package Document (content.opf).

Package Manifest and Spine

The script uses the Ruby Nokogiri gem to:

• Manifest: List every resource in the book, including HTML chapters, CSS styles, SVG diagrams, and WOFF fonts.
• Spine: Define the linear reading order of the documents.
• Properties: Automatically detect and flag documents containing MathML or SVG content using the properties="mathml" or properties="svg" attributes in the manifest.
  Sources: create_metafiles.rb:50-100, create_metafiles.rb:140-155

Table of Contents Generation

The make_toc procedure extracts the original Table of Contents from index.xhtml. It transforms unordered lists (<ul>) into ordered lists (<ol>) and adjusts relative links to point to the correct subdirectories within the EPUB structure.
Sources: create_metafiles.rb:102-115

File Generated	Purpose	Standard
toc.xhtml	Human-readable navigation and EPUB3 TOC.	EPUB3 Nav
content.opf	Metadata (Title, Creator), Manifest, and Spine.	EPUB3 Package
Sources: create_metafiles.rb:10-25

Conclusion

The post-processing scripts are essential for maintaining the high typographical standards of the SICP-Rust project. By automating syntax highlighting, mathematical conversion via MathJax, and EPUB3 metadata management, these tools ensure the book's transition from technical source code to a professional digital publication is seamless and error-free.
Sources: README.md:10-20, batch-prettify-node.js:5-15