mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-07-19 09:24:14 -05:00
d07cf72528
Switches 35 chapter decks (slides/vol1 + slides/vol2) and 2 mlsysim
tutorial decks (mlsysim/tutorial/slides/tutorial_part{1,2}.tex) from
xelatex+fontspec+texgyreheros to pdflatex+helvet+courier.
Why
---
Yesterday's slides-publish-live shipped PDFs with completely blank text
(see https://github.com/harvard-edge/cs249r_book/releases/download/
slides-latest/vol1_00_course_overview.pdf — Liberation Sans was
embedded but glyphs were missing because xelatex on Ubuntu CI could
not find texgyreheros.otf and silently fell back). The mlsysim
tutorial decks fared no better, requiring four rounds of fixes
(Helvetica Neue → texgyreheros → tex-gyre apt + mktexlsr → Latin
Modern) before they would even compile.
The root cause is engine choice: fontspec on xelatex makes runtime
OS-font discovery the build's critical path. If the host TeX install
or fontconfig doesn't have the requested font, fontspec either errors
hard (mlsysim's experience) or silently substitutes (slides' silent
broken-PDF failure mode). Either way the build is fragile.
paper.tex has been using pdflatex+helvet+mathpazo+courier for months
without a single font issue. Bringing slides + mlsysim tutorial onto
the same engine + font convention eliminates the entire failure class.
Changes
-------
* 35 chapter decks: replace
\usepackage{fontspec}
\setsansfont{texgyreheros}[Extension=.otf, ...]
\setmonofont{texgyrecursor}[Extension=.otf, ...]
with
\usepackage[T1]{fontenc}
\usepackage[scaled=0.9]{helvet}
\usepackage{courier}
\renewcommand{\familydefault}{\sfdefault}
Same Helvetica-class look (NimbusSans = URW's Helvetica clone in
helvet), shipped via texlive-fonts-recommended Depends.
* 2 mlsysim tutorial decks: same swap (was Latin Modern from the prior
retry).
* slides/Makefile: LATEX := xelatex → pdflatex.
* mlsysim/tutorial/Makefile: same.
* slides-build-pdfs.yml: drop texlive-xetex (engine), drop
texlive-fonts-extra (was for tex-gyre). Result: smaller apt-install,
no fontspec silent-fallback class of bugs.
* mlsysim-build-pdfs.yml: same engine + apt cleanup; drop JetBrains
Mono manual fc-cache step (we no longer reference JetBrains Mono).
Bar copy
--------
* mlsysim/docs/config/announcement.yml: append Lecture Slides to the
"Alongside the book" row — the mlsysim tutorial deliverable IS slides,
so cross-linking is natural.
* site/config/announcement.yml: drop the "🎓 Teach with it: Lecture
Slides · Instructor Hub" line entirely from the landing bar. Landing
is for learners; teachers find Instructor Hub via the navbar Teach
menu, and Slides via Instructor Hub.
Verification
------------
Local Mac builds with pdflatex:
- vol1/01_introduction: 52 pages, NimbusSans-Regu/Bold embedded
- vol2/05_distributed_training: 48 pages, NimbusSans embedded
- mlsysim tutorial_part1: 90 pages, NimbusSans embedded
- mlsysim tutorial_part2: 47 pages, NimbusSans embedded
All Type 1, sub-set, Unicode tag yes — renders cleanly.
119 lines
4.6 KiB
Makefile
119 lines
4.6 KiB
Makefile
# =============================================================================
|
|
# mlsysim/tutorial/Makefile — Build ISCA tutorial slides
|
|
# =============================================================================
|
|
# Usage:
|
|
# make Build the full tutorial deck (PDF)
|
|
# make svgs Convert all SVGs to PDFs
|
|
# make slides Build slides only (assumes SVGs already converted)
|
|
# make clean Remove build artifacts
|
|
# make check Verify all SVG source files exist
|
|
#
|
|
# Prerequisites:
|
|
# - xelatex (TeX Live or MacTeX)
|
|
# - inkscape (for SVG→PDF conversion)
|
|
# OR
|
|
# - rsvg-convert (alternative SVG→PDF, lighter than inkscape)
|
|
# =============================================================================
|
|
|
|
SHELL := /bin/bash
|
|
|
|
# Directories
|
|
SLIDES_DIR := slides
|
|
SVG_DIR := $(SLIDES_DIR)/images/svg
|
|
PDF_IMG_DIR := $(SLIDES_DIR)/images/pdf
|
|
BUILD_DIR := _build
|
|
|
|
# Source files
|
|
PART1 := $(SLIDES_DIR)/tutorial_part1.tex
|
|
PART2 := $(SLIDES_DIR)/tutorial_part2.tex
|
|
RELATED := $(SLIDES_DIR)/related_work.tex
|
|
|
|
# All SVG sources (auto-detected)
|
|
SVGS := $(wildcard $(SVG_DIR)/*.svg)
|
|
PDFS := $(patsubst $(SVG_DIR)/%.svg,$(PDF_IMG_DIR)/%.pdf,$(SVGS))
|
|
|
|
# LaTeX engine — pdflatex + helvet/courier, matching slides/Makefile
|
|
# and mlsysim/paper. Was xelatex+fontspec, which had silent-fallback
|
|
# rendering issues on Ubuntu CI (see 2026-05-12 publish drama).
|
|
LATEX := pdflatex
|
|
LATEX_FLAGS := -interaction=nonstopmode -halt-on-error -output-directory=$(BUILD_DIR)
|
|
|
|
# SVG converter (try inkscape first, fall back to rsvg-convert)
|
|
SVG2PDF := $(shell command -v inkscape >/dev/null 2>&1 && echo "inkscape --export-type=pdf" || echo "rsvg-convert -f pdf -o")
|
|
|
|
# =============================================================================
|
|
# TARGETS
|
|
# =============================================================================
|
|
|
|
.PHONY: all slides svgs clean check help
|
|
|
|
all: svgs slides ## Build everything (SVGs → PDFs → slide deck)
|
|
|
|
help: ## Show this help
|
|
@echo "mlsysim Tutorial Build System"
|
|
@echo ""
|
|
@echo "Targets:"
|
|
@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " %-12s %s\n", $$1, $$2}'
|
|
|
|
# --- SVG → PDF conversion ---
|
|
svgs: $(PDFS) ## Convert all SVGs to PDF
|
|
|
|
$(PDF_IMG_DIR)/%.pdf: $(SVG_DIR)/%.svg | $(PDF_IMG_DIR)
|
|
@echo "SVG → PDF: $<"
|
|
@if command -v inkscape >/dev/null 2>&1; then \
|
|
inkscape --export-type=pdf --export-filename=$@ $<; \
|
|
elif command -v rsvg-convert >/dev/null 2>&1; then \
|
|
rsvg-convert -f pdf -o $@ $<; \
|
|
else \
|
|
echo "ERROR: Neither inkscape nor rsvg-convert found. Install one."; \
|
|
exit 1; \
|
|
fi
|
|
|
|
$(PDF_IMG_DIR):
|
|
@mkdir -p $@
|
|
|
|
# --- Slide compilation ---
|
|
# Build both decks. Each .tex is compiled twice so cross-references resolve.
|
|
# The output is BUILD_DIR/<name>.pdf (xelatex -output-directory writes there).
|
|
slides: $(BUILD_DIR)/tutorial_part1.pdf $(BUILD_DIR)/tutorial_part2.pdf ## Build both tutorial deck PDFs
|
|
|
|
$(BUILD_DIR)/tutorial_part1.pdf: $(PART1) $(RELATED) $(PDFS) | $(BUILD_DIR)
|
|
@echo "Building tutorial Part 1 (Parts 0-4)..."
|
|
@mkdir -p $(SLIDES_DIR)/$(BUILD_DIR)
|
|
@cd $(SLIDES_DIR) && $(LATEX) $(LATEX_FLAGS) tutorial_part1.tex
|
|
@cd $(SLIDES_DIR) && $(LATEX) $(LATEX_FLAGS) tutorial_part1.tex
|
|
@cp $(SLIDES_DIR)/$(BUILD_DIR)/tutorial_part1.pdf $@
|
|
@echo " ✓ $@"
|
|
|
|
$(BUILD_DIR)/tutorial_part2.pdf: $(PART2) $(RELATED) $(PDFS) | $(BUILD_DIR)
|
|
@echo "Building tutorial Part 2 (Parts 5-9)..."
|
|
@mkdir -p $(SLIDES_DIR)/$(BUILD_DIR)
|
|
@cd $(SLIDES_DIR) && $(LATEX) $(LATEX_FLAGS) tutorial_part2.tex
|
|
@cd $(SLIDES_DIR) && $(LATEX) $(LATEX_FLAGS) tutorial_part2.tex
|
|
@cp $(SLIDES_DIR)/$(BUILD_DIR)/tutorial_part2.pdf $@
|
|
@echo " ✓ $@"
|
|
|
|
$(BUILD_DIR):
|
|
@mkdir -p $@
|
|
|
|
# --- Utilities ---
|
|
check: ## Verify SVG sources and dependencies
|
|
@echo "SVG figures found: $(words $(SVGS))"
|
|
@for svg in $(SVGS); do echo " ✓ $$svg"; done
|
|
@echo ""
|
|
@echo "Checking tools..."
|
|
@command -v $(LATEX) >/dev/null 2>&1 && echo " ✓ $(LATEX)" || echo " ✗ $(LATEX) NOT FOUND"
|
|
@command -v inkscape >/dev/null 2>&1 && echo " ✓ inkscape" || echo " ⚠ inkscape not found (trying rsvg-convert)"
|
|
@command -v rsvg-convert >/dev/null 2>&1 && echo " ✓ rsvg-convert" || echo " ⚠ rsvg-convert not found"
|
|
@echo ""
|
|
@echo "Slide sources:"
|
|
@wc -l $(PART1) $(PART2) $(RELATED) 2>/dev/null || echo " Some files missing"
|
|
|
|
clean: ## Remove all build artifacts
|
|
@rm -rf $(BUILD_DIR)
|
|
@rm -f $(PDF_IMG_DIR)/*.pdf
|
|
@rm -f $(SLIDES_DIR)/*.aux $(SLIDES_DIR)/*.log $(SLIDES_DIR)/*.nav
|
|
@rm -f $(SLIDES_DIR)/*.out $(SLIDES_DIR)/*.snm $(SLIDES_DIR)/*.toc
|
|
@rm -f $(SLIDES_DIR)/*.vrb $(SLIDES_DIR)/*.fls $(SLIDES_DIR)/*.fdb_latexmk
|
|
@echo "Clean."
|