How hott/book works
Project type and purpose
• This is a LaTeX‐based textbook repository (“HoTT Book”) whose sole purpose is to maintain source files, automate the build of a complex multi‐output PDF book (and errata), and publish nightly/official builds.
File structure
• Top‐level:
• .github/workflows/ci.yml and .travis.yml → CI/CD definitions
• Makefile → orchestrates all build targets (hott-*.pdf, errata, version.tex)
• Numerous .tex files (chapters, frontmatter, backmatter), .sty style files, .bib reference database
• cover/ directory with image assets and symbols script
• other/ directory with helper scripts (Python, Agda) for indices, errata filtering
• Patterns: single monolithic repo, Make‐driven build automation, separation of source (tex + styles + scripts) vs. outputs (PDFs).
README for additional insights
• Describes target build variants (online, ebook, print, arXiv), required LaTeX packages, usage of make, nightly builds, distribution channels (website, GitHub wiki).
• Emphasizes that version.tex is generated on-the-fly by the Makefile.
1. Source Repository (GitHub)
– .tex, .sty, .bib, scripts, Makefile, CI configs
2. Local Development Environment
– Developer machine running TeXLive + make + editor
3. Build Engine
– Make utility + LaTeX engines (pdfLaTeX/XeLaTeX) + Python/Agda scripts
4. CI/CD Systems
– GitHub Actions (ci.yml), Travis CI (.travis.yml)
5. External Dependencies
– TeXLive packages, Python runtime, Agda
6. Output Artifacts
– Multi‐format PDFs (hott-online.pdf, hott-ebook.pdf, …), errata.pdf, versioned tex outputs
7. Distribution Channels
– GitHub Wiki (nightly builds), homotopytypetheory.org, arXiv, Lulu.com
• Developer → pushes to → GitHub Repo
• GitHub Repo → triggers → CI/CD Systems
• CI/CD Systems → invoke → Build Engine (Make + TeXLive + scripts)
• Build Engine → consumes → Source files + External dependencies
• Build Engine → produces → Output Artifacts
• Output Artifacts → published to → Distribution Channels
• Developer (locally) → runs → Makefile → Build Engine → Output Artifacts
c. Architectural patterns & design principles:
• Single‐source monolithic content repository
• Make‐driven declarative build pipeline
• Continuous integration for documentation
• Automated version injection (version.tex)
• Separation of concerns: source vs. build vs. distribution
d. Key technologies, frameworks, libraries:
• LaTeX (pdfLaTeX/XeLaTeX), TeXLive packages
• GNU Make
• GitHub Actions & Travis CI
• Python (other/*.py)
• Agda (example code)
• Creative-Commons licensing metadata
Key detail reminders
• Build targets (hott-*.pdf, errata, version.tex).
• Scripts in /other and their roles (index helper, errata filter).
• Both GitHub Actions and Travis CI flows, even if one is deprecated.
• Distribution to multiple channels (wiki, website, arXiv, Lulu).