HTML/EPUB Build Pipeline

Relevant source files

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

• create_metafiles.rb
• README.md
• get-math.js
• put-math.js
• batch-prettify-node.js
• html/css/style.css

The HTML/EPUB build pipeline for the SICP-Rust project is a multi-stage transformation process that converts Texinfo source material into modern, accessible digital formats. The pipeline integrates several technologies, including Ruby for metadata generation, Node.js for mathematical typesetting and code highlighting, and CSS for responsive design.

The primary goal of this system is to generate an EPUB3-compliant ebook and an optimized HTML5 web version of "Structure and Interpretation of Computer Programs." It utilizes scalable vector graphics (SVG), MathML for mathematical notation, and specialized syntax highlighting for Scheme and Rust code blocks.

Sources: README.md:1-20, create_metafiles.rb:1-10

Pipeline Overview and Workflow

The build process is initiated via a standard make command, which orchestrates various scripts to process the sicp-pocket.texi source file. The pipeline moves from source extraction to asset processing, finally generating the metadata required for EPUB packaging.

Build Stages

1. Source Conversion: Conversion of Texinfo to base HTML5.
2. Mathematical Processing: Extraction of LaTeX fragments and conversion to MathML.
3. Code Prettification: Server-side syntax highlighting for code blocks.
4. Metafile Generation: Creation of navigation (NAV) and Package Document (OPF) files for EPUB3.

This diagram illustrates the sequential flow of data from the initial Texinfo source to the final distribution formats.
Sources: README.md:24-35, get-math.js:10-20, create_metafiles.rb:160-165

Mathematical Typesetting System

The project uses a two-step process to handle mathematical formulas, moving away from legacy image-based math to modern MathML.

LaTeX Extraction and Conversion

The script get-math.js identifies LaTeX strings delimited by \( and \) (inline) or \[ and \] (display). It uses MathJax v3 to convert these strings into MathML and stores the results in a JSON database (json_db) to avoid redundant conversions.

MathML Insertion

The put-math.js script reads the JSON database and performs a find-and-replace operation on the HTML output files, substituting the original LaTeX markup with the corresponding MathML blocks. If a mapping is missing, the script highlights the LaTeX in blue for debugging purposes.

Component	Responsibility	Technology
get-math.js	Scans files for LaTeX and converts to MathML database	Node.js, MathJax v3
put-math.js	Replaces LaTeX placeholders with MathML in HTML files	Node.js
json_db	Persistent storage for LaTeX-to-MathML mappings	JSON

Sources: get-math.js:1-60, put-math.js:1-40

Code Highlighting and Prettification

Code blocks in Scheme, Rust, and general examples are processed using a server-side highlighting utility.

Node.js Prettification

The script batch-prettify-node.js utilizes jsdom to simulate a browser environment. It injects the Google Code Prettify library and specific language handlers (lang-lisp.js, lang-rust.js) to apply syntax highlighting directly to the HTML files. This eliminates the need for client-side JavaScript execution during reading.

Key logic in batch-prettify-node.js:

• Identifies <pre> blocks with classes lisp, rust, or example.
• Applies the prettyprint class.
• Runs the prettyPrint() function synchronously within the JSDOM instance.
• Serializes the modified DOM back to the file system.

Sources: batch-prettify-node.js:1-70, js/highlight/prettify.js:1-50

EPUB3 Metafile Generation

The final stage of the pipeline involves creating the structural files required for the EPUB3 standard, handled by create_metafiles.rb.

Navigation and Manifest Logic

The Ruby script performs the following tasks:

• TOC Generation: Extracts the table of contents from index.xhtml and converts unordered lists (ul) to ordered lists (ol) for the toc.xhtml navigation file.
• Manifest Creation: Scans the html/ directory to build the <manifest> in content.opf. It automatically detects media types (e.g., image/svg+xml, application/font-woff).
• Property Detection: Checks files for specific tags (like <math> or <object>) to apply mandatory EPUB3 properties like mathml or svg to manifest items.

This sequence shows how the metadata generator interacts with processed HTML to build the EPUB container files.
Sources: create_metafiles.rb:15-150

Styling and Responsive Design

The visual presentation is managed by html/css/style.css, which includes specific adjustments for different viewing environments.

Feature	Implementation
Font Face	Uses Linux Libertine O (serif) and Linux Biolinum O (sans-serif)
Responsive Rules	Media queries adjust font-size and margins for screens < 480px and 481px-720px
EPUB Overrides	Comments indicate rules that should be toggled (e.g., .jump visibility) for EPUB generation
Math Integration	Specific padding and font-matching for MathML elements (mtd, mi)

Sources: html/css/style.css:1-150, html/css/style.css:350-410

Summary

The build pipeline transforms technical source material into a modern digital book by layering mathematical conversion, code highlighting, and EPUB3 structural metadata onto base HTML5 output. By utilizing server-side Node.js and Ruby scripts, the project ensures that the final output is highly compatible with various ebook readers and web browsers while maintaining advanced features like MathML and syntax-highlighted Rust examples.

Sources: README.md:10-20, create_metafiles.rb:1-10