prezento 1.1.1

Features

• Semantic RST Authoring: Define slides using clean, human-readable structural text without manual HTML/DOM manipulation.

• Granular Step-by-Step Expansion: A mathematically precise AST (Abstract Syntax Tree) unrolling engine that creates perfect frame-by-frame PDF handouts mirroring your live presentation clicks.

• Native Graphviz Integration: Embed complex architecture diagrams directly in your slides using the custom grafo directive, with automated SVG sanitization and CSS scaling.

• Presenter Console Support: Private speaker notes injected seamlessly into the b6plus presenter dashboard via the komento directive.

• Offline-First Architecture: Zero runtime reliance on external CDNs or APIs. Presentations render flawlessly in air-gapped environments or low-connectivity lecture halls.

• Multi-Format Generation: Simultaneously compiles your single source text into a live presentation, a flat summary document, and a frame-by-frame handout.

Why prezento?

The original prezentprogramo relied heavily on impress.js. While visually impressive, impress.js introduced immense structural DOM complexities that made generating clean, static PDF handouts highly problematic. After years of field-testing in university lecture settings, prezento was redesigned from scratch to solve these fundamental limitations:

• Strict Decoupling: Complete separation of the static layout generation from the interactive JavaScript presentation layer.

• Modernized Docutils Pipeline: Eradication of legacy Docutils hooks in favor of clean, isolated HTML5 tree translators and native node visiting.

• Framework Migration: Transitioning to b6plus, an elegant, lightweight presentation package maintained by the W3C presentation community, which handles progressive reveals (incremental classes) and hierarchical lists far more gracefully.

Sample Slides

Real-world examples of prezento in use are located here:

https://github.com/yoosofan/slide

The following samples shows more details for learning and using prezento.

Assets Requirement

The generated HTML slides require the following asset:

• assets/b6plus.js: b6plus javasrcript library for on screen presentation

Important: After generating HTML files, you must have an assets/ folder next to them containing this file.

These assets are taken from the b6plus project. You can update them whenever a newer version is released.

You can download them from my slides too.

Installation

pip install prezento

From source (recommended during early development):

git clone https://github.com/yoosofan/prezento.git
cd prezento
pip install -e .

Usage

Basic usage:

prezento your_slides.rst

This will generate two output files in the same directory:

• your_slides.concise4pdf.html — Standard version (good for printing)

• your_slides.presentation.html — b6plus interactive version

Options:

prezento input.rst -o output4presentation.html
prezento input.rst -s  # Generate input.substep4pdf.html — Step-by-step version
prezento input.rst -np # Skip b6plus version for screen presentation

Output Targets Pipeline

A single execution of prezento generates up to three distinct structural outputs, tailored for different instructional needs:

1. Concise Handout Mode (``*.concise4pdf.html``) Outputs a flattened, continuous HTML document. All animation states and incremental steps are fully visible immediately. This is optimized for quick student reference, screen readers, or standard single-pass PDF printing.

2. Step Handout Mode (``*.step4pdf.html``) Powered by a custom AST deep-cloning engine. If a slide contains progressive steps, the engine clones the slide node entirely for each step, altering the visibility classes sequentially. This produces a long-form HTML file that, when printed to PDF, acts as a perfect flip-book mimicking the exact timing and progression of the live lecture.

3. Interactive Presentation Mode (``*.presentation.html``) The dynamic projector mode. It automatically maps your logical slide boundaries and step flags into b6plus native classes (like incremental) and injects the necessary CSS/JS routing for live speaker delivery.

Syntax and File Structure

Presentations are written as standard .rst files. The document must begin with the prezento directive to establish global metadata, followed by four-space indented slido blocks.

.. prezento:: Advanced Memory Management (By Dr. Turing)
   :css: assets/theme.css
   :js: assets/custom_interactions.js

.. slido:: Introduction to Paging
   :id: slide-paging-intro

   Paging eliminates external fragmentation by dividing physical memory into fixed-sized blocks.

   * Block size is defined by the hardware.
   * Typical sizes range from 4 KB to 8 KB.

.. slido:: The Translation Look-aside Buffer (TLB)
   :class: custom-slide-bg

   The TLB is a specialized hardware cache for page table entries.

   #. CPU generates a logical address.
   #. The page number is sent to the TLB.
   #. If a **TLB Hit** occurs, the frame is returned immediately.
   #. If a **TLB Miss** occurs, a memory access is required.

Custom Directives Reference

prezento extends docutils with presentation-specific domain hooks:

.. grafo::
   :align: center
   :scale: 120

   digraph G {
       node [shape=box];
       "Logical Address" -> "Page Table" [class="step"];
       "Page Table" -> "Physical Memory" [class="step"];
   }

.. slido:: Addressing Hardware

   * Page Offset (d)
   * Page Number (p)

   .. komento::

      Make sure to write the formula "m - n" on the whiteboard before switching to the next slide.

Project Structure (Development)

prezento/
├── src/
│   └── prezento/
│       ├── __init__.py
│       └── main.py     # Core translation pipeline & CLI entry point
├── docs/
│   └── CHANGELOG.rst   # Version history and migration notes
└── tools/
    ├── readme.rst
    ├── slido_ls.py     # Language Server Protocol (LSP) for IDEs and editors
    ├── build.sh        # Packaging and deployment script
    └── clean.sh        # Environment scrub utility

Contributing

Contributions from the educational and open-source communities are highly encouraged. As the project remains in active development, you can assist by:

• Opening detailed issues for rendering bugs or feature requests.

• Submitting Pull Requests to enhance the HTML5 translator logic or add new directive capabilities.

• Testing the pipeline against massive, highly complex academic slide decks to identify edge-case layout breaks.

License

This project is licensed under the GNU General Public License v3.0 (GPLv3).

See the LICENSE file in the repository root for the full legal text. You are free to use, modify, and distribute this software strictly under the terms of this license.

Acknowledgments

• Architecture heavily inspired by Hovercraft and the historical framework of prezentprogramo.

• Interactive projector routing powered entirely by the excellent b6plus framework.

• Structural tree manipulation built on top of the robust Python docutils engine.

Author

Ahmad Yoosofan

• GitHub: https://github.com/yoosofan

• Slides: https://github.com/yoosofan/slide