reStructuredText to LectureDoc² (rst2ld)

rst2ld enables the conversion of lecture slides authored in reStructuredText to LectureDoc2 format.

Getting Started - Setup a Project

1. create a directory in which you want to store your slides; e.g., mkdir slides
2. change to the directory: cd slides
3. initialize git: git init
4. add the LectureDoc2 and restructuredTextToLectureDoc2 projects as submodules:
   • git submodule add https://github.com/delors/LectureDoc2
   • git submodule add https://github.com/delors/reStructuredTextToLectureDoc2

Getting Started - Optional

1. add a script to (automatically) generate slides (e.g., https://github.com/Delors/Lectures/blob/main/gen-slides.zsh)
2. add docutils.conf when necessary (https://github.com/Delors/Lectures/blob/main/docutils.conf); i.e., if you have mathematical (.. math::) expressions in your slides and want to refer to a specific version of MathJax.
3. add .gitignore file with \*.rst.html if you don't want to archive the generated web pages

Generating PDFs

In general, PDFs are generated by converting the HTML files to PDFs using a browser. As of 2024, Safari has the best support for printing HTML to PDF (don't use the Export as PDF... feature; use Print → PDF). Chrome works in most cases reasonably well, Firefox often fails miserably.

A script (https://github.com/Delors/Lectures/blob/main/gen-pdfs-from-slides.zsh) for generating PDFs using Safari (tested on Mac OS 14 (Sonoma)) is available. This script requires that LectureDoc is found in the LectureDoc2 subfolder. This script basically automates Safari by simulating user input. Hence, don't use your Mac while the script is running.