Skip to content

Documentation and Presentation Tools

Beyond API documentation (this very site is built with zensical), Phoenix2 also needs to produce teaching material and scientific presentations: lecture websites for courses, and slide decks for conference talks. A dedicated family of tools, grouped under static-site-generator, covers this end-to-end, from a lightweight custom markup format down to the image processing that feeds the final HTML pages and slide decks.

flowchart TB
    Src[".ptex sources /<br/>numbered slide fragments"] --> Spell["PhoenixSpelling<br/>(check wording)"]
    Spell --> Engine["PhoenixTex2Html / PhoenixLecture<br/>(RustyPhoenixLecture)"]
    Spell --> Beamer["PhoenixBeamerCreator"]
    Spell --> Slider["PhoenixSlider"]
    Engine --> HTML["Lecture website"]
    Beamer --> PDF["Beamer / PDF deck"]
    Slider --> Web["HTML slider / web deck"]
    SVG["SVG diagrams"] --> Ink["PhoenixInkscape"] --> PNG
    PNG["PhoenixPNG"] --> Engine
    PNG --> Beamer
    PNG --> Slider

From markup to lecture website: PhoenixTex2Html and PhoenixLecture

PhoenixTex2Html is the core rendering engine: it parses a custom, LaTeX-inspired markup (.ptex) and turns it into a themed HTML site. Judging from its extensive test suite, the supported content is rich: sections, itemized lists, tables, quotes, verse, math formulas, bibliographies and references, footnotes, syntax-highlighted code, timetables (handy for course schedules), speaker notes, embedded video, "work in progress" markers, environment-variable substitution, and both light and dark themes, including a dedicated "book" theme for long-form, multi-page content.

PhoenixLecture packages this engine with the configuration and project structure needed to assemble a complete lecture or course website, so that writing a new course means writing .ptex content, not wiring up a build.

RustyPhoenixLecture is a modern Rust rewrite of this same content model, a checkbox, a collapsible detail block, an environment, a footnote, a formula, a media embed, a reference, speaker notes, a table, a timetable, a title, a url, syntax highlighting, each implemented as its own content type, reproducing PhoenixTex2Html's feature set natively in Rust.

From slide fragments to a talk: PhoenixPresentation, PhoenixBeamerCreator and PhoenixSlider

Presentations follow a simple convention: a talk is described as a sequence of numbered slide fragments (000-title.tex, 010-introduction.tex, 020-diagram.svg, ...), each fragment being either a LaTeX/Beamer snippet or a ready-made image, assembled in order into a full deck.

  • PhoenixBeamerCreator assembles these fragments into a LaTeX Beamer presentation (PDF), with a choice of visual themes.
  • PhoenixSlider assembles the same kind of numbered fragments, this time including images, videos, or raw HTML, into an interactive HTML slider for the web, so the same content can be published as a webpage instead of, or alongside, a PDF.
  • PhoenixPresentation drives the LaTeX/SVG compilation behind a talk. Fittingly, its own test suite is built from the slide sources of the "double backend" PHOENIX2 conference paper (000-title.tex, 010-Problematic.tex, 020-proxy-principle.svg, 090-Summary.tex, 100-FutureWork.tex), the same proxy-principle diagram also shows up as a conversion test case for PhoenixInkscape below.

Supporting image tools: PhoenixInkscape and PhoenixPNG

PhoenixInkscape batch-converts SVG diagrams into PNG images using Inkscape, so that vector diagrams (architecture schemas, for instance) can be embedded wherever a raster image is expected, such as a Beamer slide.

PhoenixPNG (and its Rust counterpart, RustyPhoenixPng) is a small library to read, write, and color-map PNG images, used wherever these tools need to manipulate images directly rather than shelling out to an external program.

Keeping the writing clean: PhoenixSpelling

PhoenixSpelling spell-checks .tex source files in both English and French against a maintained dictionary. A "training" mode lets the dictionary learn new, project-specific technical vocabulary, so that lectures and presentations full of domain-specific terms don't drown the review in false positives.

Why a dedicated toolchain

  • Consistency: lectures and presentations across Phoenix2 share the same source conventions, in both C++ and Rust.
  • One source, several outputs: the same numbered slide fragments can be rendered as a PDF (PhoenixBeamerCreator) or a webpage (PhoenixSlider), a duality similar in spirit to Phoenix2's real/mock backend design described in Mock testing.
  • Quality by default: automated spell-checking catches wording mistakes before they reach a published lecture site or a printed deck.