Image in the Background (Hack)
LectureDoc is an authoring system for creating lecture material; i. e., lecture slides, notes and exercises from a single document.
A single LectureDoc document contains discussions of topis which are then used as templates for creating advanced slides as well as a standard document. LectureDoc is intended to be used in combination with rst2ld (reStructuredText to LectureDoc) which is a tool that converts reStructuredText documents into LectureDoc and makes authoring slides as easy as writing a text document.
This tutorial is written in reStructuredText (rst in the following) and can be used as a template for creating your own lecture slides. The code of this tutorial is available on GitHub: https://github.com/Delors/reStructuredTextToLectureDoc2/blob/main/ld_base_example.en.rst.
A basic slide consists of a (section) header and some reStructuredText content.
Embed math equations using reStructuredText's default directive (.. math::) and role (:math:`...`).
You can use no-title in combination with the class directive to avoid that the title is shown on the slide/document. However, the title is still used for indexes.
Basic appear animations can be created using the (CSS) class incremental[1]. You can also define a corresponding custom role (.. role:: incremental) to animate parts of a text.
In case of (un-)ordered and definition lists (ol or ul in HTML) it is sufficient to associate the class incremental-list using the class directive with the list. It is also possible, to only specify the incremental class attribute for the required list items.
The slide dimensions can be controlled by specifying the corresponding meta information. If not specified, the dimension is set to \(1920 \times 1200\) (default); i.e., a ratio of 16:10.
Many functions in LectureDoc2 - e.g. persistence of the slide progress - require that a document is associated with a unique id. This id can be set using the meta directive. If no id is set, the respective functions are not available.
Adding information that should not be on the slides, but provide additional information/explanations, can be added using the supplemental directive.
Formatting Slides
Creating heavily formatted slides is easily possible using rst directives and roles which are mapped to CSS classes.
Creating a slide which marks the beginning of a new section can be done using the new-section class.
Slide transitions can be controlled using the transition-... classes[2]:
transition-fade
transition-move-left
transition-move-to-top
transition-scale
transition-flip
Adding code can be done using reStructuredText's code directive.
LectureDoc2 supports links to external resources:
The title of a slide can be used as a link target ➠ Advanced Formatting
An element which is explicitly marked as a target can be used as a link target:
Citations are fully supported in LectureDoc2.
A reference to a book: [Martin2017] (Details are found in the bibliography (see next slide)).
Clean Architecture: A Craftsman's Guide to Software Structure and Design; Robert C. Martin, Addison-Wesley, 2017
...
LectureDoc comes with a set of predefined (CSS) classes that can be used to format the slides. Some of these classes have explicit support by LectureDoc and will be rendered differently in the different situations (e.g., document view vs. slide view will render stacked layouts or supplemental information differently).
red
peripheral
obsolete
See the LectureDoc2 Cheat Sheet for a comprehensive list of predefined CSS classes.
Stacked layouts enables updating parts of a slide by putting the content into layers and then showing the layers incrementally.
Presenter notes can be added to a slide using the presenter-note directive.
A presenter note - including its presence - is only visible after entering the master password (press m and then enter: 123456).
Exercises can be integrated into the slide set.
If you have multiple exercises, you can define a master password (123456) to unlock all solutions at once (press m to open the dialog).
.. meta::
:master-password: 123456Inline SVGs are fully supported by LectureDoc, but styles and definitions that are used in multiple inline SVGs have to be centralized!
This is due to the copying of the slide templates which - if you use ids to reference definitions in the SVGs - makes them no longer unique. This is a violation of the spec and causes troubles in Chrome and Firefox.
Adding Shared Definitions
To add shared SVG definitions, use the .. meta:: directive and the :svg-defs: property.
Defining Shared Styles
To add shared SVG styles, use the .. meta:: directive and the :svg-style: property.
The example also demonstrates how to define an SVG whose size is completely dependent on the size of the surrounding font-size.
In general, embeddings images is done using the image directive. However, due to the fact that we render the topic once as classical slides and once in a document-oriented way, it is important to understand how LectureDoc handles images.
General Guidelines
In general an image should be designed/generated/created with its usage on a slide in mind. That is, an image should fit on a slide with a logical resolution of 1900 by 1080/1200 pixels. Hence, if text is found on the image it should not be smaller than 30px; ideally it should use the same font size as used by the slide. Those images should then be added to the document using the image directive. In this case it is optional to specify the width and/or height. Such images will be automatically scaled by LectureDoc when the content is shown in the document view. The scaling factor is determined by the ratio between the default font-size used for the document and the default font-size used for the slides.
HighDPI Images
As said, images are generally assumed to have a resolution that fits a slide. However, in many cases the source image may have a resolution that is (much) higher. In this case, it is possible to scale the image using the directive's width and/or height attribute. LectureDoc will then update the width and height attributes when shown in document mode. This requires that the images' width and heights are given in pixels.
Images/SVGs With Font-size Dependent Sizing
SVGs where the size is (alread) dependent on the font-size should not specify any width or height attributes.