Book Build & Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
The SICP-Rust project provides a modern toolchain for generating high-quality HTML5 and EPUB3 versions of "Structure and Interpretation of Computer Programs." This build system transforms the original Texinfo source into a responsive digital book featuring MathML for equations, SVG diagrams, and syntax highlighting for Scheme and Rust code examples.
The deployment focus is on creating a standard EPUB3 file and a web-hosted HTML version that utilizes modern web technologies like MathJax and embedded fonts to ensure a premium reading experience on both desktop and mobile devices.
Sources: README.md:1-20
Build Environment & Prerequisites
The build process relies on a multi-language toolchain including Perl, Ruby, Node.js, and Texinfo. These tools handle different aspects of the transformation from raw TeX source to formatted web content.
| Requirement | Version / Specification | Purpose |
|---|---|---|
| Texinfo | 5.1 | Primary source parser and HTML converter |
| Perl | 5.12 or later | Cross-reference generation (ex-fig-ref.pl) |
| Ruby | 1.9.3 or newer | EPUB metadata and manifest generation |
| Node.js | Current (replaces PhantomJS) | Math conversion and code prettification |
| Nokogiri | Ruby Gem | XML/HTML parsing for metadata creation |
Sources: README.md:22-30, batch-prettify-node.js:1-10, get-math.js:1-15
Build Workflow Architecture
The build pipeline is orchestrated via a Makefile. The central source of truth is sicp-pocket.texi. Changes made directly to files in the html directory are discouraged as they are overwritten during the build process.
This diagram illustrates the transformation from Texinfo source through various post-processing scripts to the final distribution formats.
Sources: README.md:15-25, create_metafiles.rb:1-15, get-math.js:18-25
Core Build Subsystems
1. Mathematical Rendering Engine
The project uses a two-stage process to handle mathematical notation. LaTeX strings delimited by \( or \[ are extracted and converted to MathML to ensure compatibility with modern e-readers and browsers.
- Extraction:
get-math.jsusesmathjax-fullto scan input files and build a JSON database (json_db) mapping LaTeX to MathML. - Injection:
put-math.jsreads this database and performs a search-and-replace operation across the output HTML files.
Sources: get-math.js:18-40, put-math.js:1-15
2. Metadata and EPUB Structure
The create_metafiles.rb script is responsible for generating the structural components required by the EPUB3 standard.
- NAV File (
toc.xhtml): Generated by extracting the table of contents from the HTMLindex.xhtml. It converts unordered lists (ul) to ordered lists (ol) for EPUB compliance. - OPF File (
content.opf): Acts as the package manifest. It lists all assets, including CSS, fonts, SVGs (using thexprefix for IDs starting with digits), and defines the reading order (spine).
Sources: create_metafiles.rb:10-50, create_metafiles.rb:85-115
3. Syntax Highlighting
Syntax highlighting for code blocks is applied server-side (build-time) using batch-prettify-node.js. This script utilizes JSDOM to simulate a browser environment, allowing the google-code-prettify library to process Scheme and Rust code blocks.
- Supported Languages: Scheme (via
lang-lisp.js) and Rust (vialang-rust.js). - Target Elements:
pre.lisp,pre.rust, andpre.example.
Sources: batch-prettify-node.js:15-35, batch-prettify-node.js:80-95
4. Cross-Reference Generation
The Perl script ex-fig-ref.pl generates tabulated cross-references for exercises and figures. It calculates column fractions for Texinfo @multitable environments based on the number of exercises per chapter.
| Chapter | Exercises | Figures |
|---|---|---|
| 1 | 46 | 5 |
| 2 | 97 | 26 |
| 3 | 82 | 38 |
| 4 | 79 | 6 |
| 5 | 52 | 18 |
Sources: ex-fig-ref.pl:15-35
Styling and Responsive Design
The visual presentation is controlled by html/css/style.css. The design uses "Linux Libertine O" for body text and "Linux Biolinum O" for headings.
Responsive Breakpoints
The build implements scaffolding for responsive design, adjusting font sizes based on screen width:
- Desktop (>720px): 170% base font size.
- Tablets (481px - 720px): 140% font size.
- Mobile (<480px): 120% font size.
Sources: html/css/style.css:45-75, README.md:10-15
Rust Example Integration
While the book build handles the text and diagrams, the associated Rust implementations for SICP exercises are managed separately via Cargo. The project uses a workspace to manage examples for chapters 1 through 5.
The Rust examples are verified using proptest for property-based testing and use im for persistent data structures, mirroring Scheme's functional nature.
Sources: rust-examples/Cargo.toml:1-15, rust-examples/sicp-common/Cargo.toml:1-10
Deployment
Execution of the make command results in:
- HTML Site: A collection of HTML5 files in the
html/directory, optimized for web hosting (e.g., GitHub Pages). - EPUB File: A
sicp.epubfile created in the parent directory, containing all fonts, styles, and MathML-enabled content.
Sources: README.md:15-20, create_metafiles.rb:10-20