1.1 Design Goals

Granular configurability was the first goal. Dslide’s predecessor, org-tree-slide, could only be configured at the level of the entire document, using customize variables. Dslide aims to be configureable over each element of each heading.

Programmability quickly became primary motivation to develop dslide further. Org babel blocks can be used as steps of a dslide presentation. By scripting Emacs via Elisp within org babel blocks, because Emacs sits on top of all your other programming tools and sub-processes, so does dslide. The action system is a framework for attaching reusable, configurable programmed behavior to multiple headings.

High productivity was another goal. With a decent org configuration, use basic markup to obtain a decent presentation. Org mode’s properties and keywords are used to attach and configure reusable behavior to elements and headings. Dslide respects export settings, allowing content to vary between presentation and export. You can use the presentation org document itself the same way you use other org documents, to store, organize, and publish information.

1.2 Strengths

Dslide is particularly good for presentations that are for internal use or intended for closed audiences, where lavish graphics that would be directed at end consumers is unneeded and could even be seen as an inappropriate expense of time:

• Tech demos where you need programming tools
• Early stage startup pitches
• Conducting team meetings

3.1 Org Mode Terms

Select org mode terms more frequently used by dslide. Don’t miss (org)Org Syntax (org).

• ‘Element’: org documents are parsed into elements and objects. Headings, plain lists, and blocks are examples of elements. See the org element api documentation. Dslide makes heavy use of org’s element parser to implement its features.
• ‘Keyword’: A single ‘#+keyword_style:’ line used to specify some option
• ‘Affilated keyword’: A ‘#+attr_keyword_style:’ line that directly precedes an element and is used to add metadata to arbitrary org elements. It must begin with the ‘attr’ prefix! ⚠️
• ‘Parameter’: Babel blocks have parameters. Whenever an action works mainly on blocks, it can use parameters rather than affiliated keywords.
• ‘Property drawer’: Used especially to configure a heading’s slide action or how an action affects a heading element (affiliated keywords cannot apply to headings). Can be used to configure section actions.
• ‘Property’: Values in the property drawer. Meta data attached to headings. See (org)Property Syntax (org)

4.1 Actions

By default, you just get one slide per heading, a header, and some animation. This is not very exciting. You need to add actions to slides to consume their section content in a more engaging way.

There are two kinds of actions:

• ‘Slide actions’: mostly responsible for narrowing to a slide and then handling the child headings, either inline or as separate slides
• ‘Section actions’: work on the content in the heading’s section.

To browse all actions, because they are all EIEIO classes, you can use eieio-browse and see the actions descend from dslide-action.

+--dslide-stateful-sequence
     +--dslide-action
          +--dslide-action-propertize
          +--dslide-action-image
          +--dslide-action-babel
          +--dslide-action-item-reveal
          +--dslide-action-hide-markup
          +--dslide-slide-action
               +--dslide-slide-action-every-child
               +--dslide-slide-action-inline
               +--dslide-slide-action-child
               +--dslide-slide-action-flat

4.2 Adding Actions

By default, every slide has two actions, configurable in dslide-default-actions:

• dslide-action-propertize for adding text properties to arbitrary elements
• dslide-action-hide-markup to hide keywords, todo states, and tags, allowing you to have these things in your source without them cluttering the presentation

Non-default actions must be added to a slide using the slide’s property drawer. Actions that work by recognizing org elements by type are perhaps a bit dangerous to leave on all the time.

• ‘DSLIDE_SLIDE_ACTION’: Usually narrows to the slide and creates children from child headings. Lifecycle encloses the section actions.
• ‘DSLIDE_ACTIONS:’ Most commonly used. You can list multiple actions. Each one will step through its forward and backward steps.

* Full Screen Images
:PROPERTIES:
:DSLIDE_ACTIONS: dslide-action-images
:END:
#+attr_html: :width 50%
[[./images/emacsen4.jpeg]] [[./images/before-google3.jpeg]]

4.3 Action Arguments

Many actions understand arguments, allowing tuning of similar behaviors from the same class.

To view an action’s arguments, call describe-symbol on it. Any slot definition usually has the same ‘:initarg’ and will be understood when added as a plist-style argument.

Configuring the slot is done by adding plist-style properties after the class name:

:PROPERTIES:
:DSLIDE_ACTIONS: dslide-action-item-reveal :inline t
:END:

You can also use “property+” syntax to add to a property, and these accept plist arguments too:

:PROPERTIES:
:DSLIDE_ACTIONS: dslide-action-babel
:DSLIDE_ACTIONS+: dslide-action-images :full-frame t
:END:

🚧 The current plist read implementation splits the string rather than using read-string and is therefore not smart enough to parse lists as arguments. However dslide-action-propertize demonstrates doing this correctly and shows that it will be possible if needed.

4.4 Annotating Elements

Some actions, such as dslide-action-propertize, can’t decide which elements to operate on or what to do with those elements. You can add some meta data to an element using an affiliated keyword.

⚠️ If you are extending an action and want to create your own affiliated keyword, they must start with ‘attr’ or else the org element parser will not consider them affiliated and that property will not be set on the element!

* Fancy Text
:PROPERTIES:
:DSLIDE_ACTIONS: dslide-action-propertize
:END:
Add text properties to an element using the =attr_dslide_propertize= affiliated keyword.  No quoting is required.  Lists will be interpreted as such.

#+attr_dslide_propertize: face (:background "#ddddff" :foreground "#000000" :weight bold :height 2.0)
This is some fancy text

4.5 Babel Scripting

You can write custom scripts into your presentation as Org Babel blocks. These can be executed with the dslide-action-babel action.

In the future the babel action may become a default, using the ‘#+attr_dslide_babel’ affiliated keyword or ‘:noeval’ to decide a block should not be executed. As of this version of dslide, either add dslide-action-babel to your dslide-default-actions or add it to the actions list via the property drawer.

* My Heading With Babel Blocks
:PROPERTIES:
:DSLIDE_ACTIONS: dslide-action-babel
:END:
#+begin_src elisp
  (message "Good job!")
#+end_src

By default blocks only execute going forward, one block per step. You need to label your blocks with lifecycle methods if you want to perform setup (forward and backward) and teardown. See the dslide-action-babel class and examples in ./test/demo.org.

The ‘#+attr_dslide:’ affiliated keyword is used to configure which methods will run the block. Block labels that are understood:

• ‘begin’ and ‘end’ are run when the slide is instantiated, going forward and backward respectively. You can have several blocks with these methods, and they will be run from top-to-bottom always, making it easier to re-use code usually.
• ‘final’ is called to clean up when no progress can be made or if the presentation is stopped.
• ‘forward’ and ‘backward’ are self-explanatory. Position your ‘backward’ blocks above any block that they undo
• ‘both’ runs either direction. It will not repeat in place when reversing. Use separate ‘forward’ and ‘backward’ blocks for that 💡

These methods follow the naming and behavior of dslide’s stateful sequence interface. The babel action is basically delegating stateful sequence calls into the blocks of your org document.

The babel action also understands regular babel options such as ‘:exports’ and ‘:results’. Exports none will make the block invisible. Results controls whether results will be printed into the buffer or not.

• Step Callbacks

4.6 Hiding Markup

Dslide uses a lot of markup that would not look good in a presentation. It also filters it by default using dslide-action-hide-markup. You can adjust the types using dslide-hide-markup-types

• Hiding Todos and Tags

4.7 Filtering Headings

• Any heading with ‘COMMENT’ directly after the stars will be skipped
• Any heading with the ‘:noslide:’ or ‘:noexport:’ tags will be skipped

Use this when your headings are work-in-progress and you run out of time on Friday before the feature demo meeting. Have some content that is only not used in presentations? Use ‘:noslide:’.

To change the filtering from what is done by dslide-built-in-filter, customize dslide-default-filter or set ‘DSLIDE_FILTER’ (possibly implemented 🤡, file an issue!).

4.8 Header Keywords

If dslide-header is configured, the keywords for the document title, email, and author etc will be used to generate an okay header.

#+,#+title:        Domain Specific sLIDEs
#+author:        Positron
#+email:        contact@positron.solutions

You can try customizing with dslide-header-email and similar variables or just set dslide-header-fun to complete replace the header with your own device.

• Breadcrumbs

4.9 File Local Variables

Don’t forget that if you need a customize variable only set in a particular presentation, you can use file local variables. Not every setting needs a keyword or babel block integration.

# Local Variables:
# dslide-header: nil
# End:

5.1 Two Button Interface

Presentations tend to be organized into a scripted linear sequence. We want to control the entire presentation sequence mostly with two buttons, forwards and backwards.

The controllers for presenting usually have very few buttons. Dslide was designed with this usage pattern in mind and can mostly be controlled by two commands.

• dslide-deck-forward

• dslide-deck-backward

Many controllers also have a “play” button or similar. It’s recommended to map this to dslide-deck-start.

🚧 It is intended to overload dslide-deck-start further to implement “secondary” actions that can be triggered non-linearly.

There is likely no good place to bind dslide-deck-stop, but it’s not critical. You can do everything with just three buttons.

5.2 Contents Interface

Navigate your presentation faster when answering questions. The contents interface is a view of top-level headings. It overloads the presentation controls to navigate.

To enter the contents, call dslide-deck-start when a presentation is already active.

• dslide-deck-start will resume the presentation at that heading
• dslide-deck-stop will similarly exit the contents view
• dslide-deck-forward and dslide-deck-backward move between top level headings.

5.3 Narrating

The presentation you see is a cloned (elisp)indirect buffer of your org mode buffer. The Elisp state and overlays are independent. There are two key advantages:

• Any state you create in the presentation (besides buffer text and text properties!) will not pollute the org mode buffer you are editing
• We can display the source for the presentation simultaneously, making one pretty while leaving the other to show us what is hidden

dslide-deck-develop will attempt to display both the presentation and source simultaneously. Whenever the source is visible, highlights will be applied to indicate where the presentation is at. This is especially helpful for including presentation notes in comments, which are hidden by default.

To leave a comment for yourself in the presentation source, just add a comment block or comment line:

# This is also a comment

#+begin_comment
This is a comment that only I can see while presenting, only when I look at my base buffer while sharing another frame.
#+end_comment

You can also switch a window to the base buffer manually. That’s almost all dslide-deck-develop does.

5.4 Cursor Visibility

By default, the cursor is hidden in the presentation buffer using dslide-cursor-hide. You can call dslide-cursor-restore if you need it.

Another good choice for interactive presentations is to use moc-subtle-cursor-mode from the Master of Ceremonies package. It is more like having a laser pointer that hides itself automatically.

6.1 Binding

You likely want to start the mode via dslide-deck-start. Once the mode starts, it creates an indirect buffer to display the slides and then calls dslide-deck-start-function once the mode is active and everything is initialized, so you can customize startup behavior.

All commands begin with dslide-deck 💡

(keymap-set org-mode-map "<f5>" #'dslide-deck-start)

Once the global minor mode, dslide-mode is active, additional bindings in dslide-mode-map are active in every buffer so that you can integrate other buffers into your presentation. (Tracking which buffers are part of a presentation is still a topic under consideration 🚧)

• Secondary Commands 🚧

6.2 Hooks

Beware of using the normal dslide-mode-hook 😱 because it runs in the base buffer ⚠️. If you use that hook to remap faces or add a bunch of styling, state will be copied to the indirect buffer but then linger in your base buffer. Instead, use dslide-start-hook. 💡

• dslide-start-hook is run in the indirect buffer after it is set it. This is what you want.
• dslide-stop-hook is run in the base buffer because the indirect buffer is already dead.
• dslide-contents-hook is run after switching to contents. It runs in the slide buffer.
• dslide-narrow-hook is run after narrowing, usually after a slide is started
• dslide-after-last-slide-hook is run when the user tries to go forward but there are no more slides. You can use this to implement a final feedback before quitting or add dslide-deck-stop to exit without feedback.

  Another option is to use dslide-push-step to push a callback that will only run when called going forward.

(defun my-stop-if-forward ()
  (dslide-push-step (lambda (direction)
                  (when (eq direction 'forward)
                    ;; Be sure to return t or the callback won't count as a
                    ;; step and the hook will run again.
                    (prog1 t (dslide-deck-stop))))))

(setq dslide-after-last-slide-hook #'my-stop-if-forward)

• Per-Slide Actions

6.3 Steezing Org

This is not unique to dslide, but if you want more professional looking results, you will likely need to make your org a bit prettier.

The setup used for the Positron’s YouTube demos is not much more complex than this well-documented setup by System Crafters. Also see Prot’s further documentation on customizing org mode faces and fonts.

In short, use:

• org-modern
• org-appear
• nerd-icons for more cheesy (Emacs logo)
• And set the faces for org headings and document title.

Don’t forget built-in emoji-search and searching insert-char.

Positron is cheating and also apply custom line-spacing and line-height. While Psionic maintains a custom org-modern, using custom spacing everywhere fights with visual-line-mode currently.

7.1 Creating Actions

Actions are the right choice when you need custom behavior that you want to re-use. Actions can be configured with arguments. They implement the stateful sequence lifecycle. For one-off solutions, you probably just want a babel block.

First choose your action type:

• Override dslide-action to create an action that works mainly on a heading’s section content.

• Override dslide-slide-action to create a slide action. Your action will control the display of the slide and its children, usually controlling the narrow state and adding or removing overlays from children.

Override methods as appropriate, configure a heading to use your action, and you’re done. Some actions, such as dslide-action-propertize only work when some of the section data is annotated.

7.2 A Custom Action

The dslide-section-next and dslide-section-previous method documentation are very helpful behavior for quickly writing custom actions. They advance the action’s ‘:marker’ forwards and backwards to the next matching element and return that element so we can do something with it.

• declare a class
• override a few methods
• now you too can paint the paragraphs red

Example code:

(defclass dslide-action-red-paragraphs (dslide-action)
  ((overlays :initform nil))
  "Paint the paragraphs red, one by one.")

;; Default no-op `dslide-begin' is sufficient

;; Default implementation of `dslide-end', which just plays forward to the end,
;; is well-behaved with this class.

;; Remove any remaining overlays when calling final.
(cl-defmethod dslide-final :after ((obj dslide-action-red-paragraphs))
  (mapc #'delete-overlay (oref obj overlays)))

;; Find the next paragraph and add an overlay if it exists
(cl-defmethod dslide-forward ((obj dslide-action-red-paragraphs))
  (when-let ((paragraph (dslide-section-next obj 'paragraph)))
    (let* ((beg (org-element-property :begin paragraph))
           (end (org-element-property :end paragraph))
           (new-overlay (make-overlay beg end)))
      (overlay-put new-overlay 'face 'error)
      (push new-overlay (oref obj overlays))
      ;; Return non-nil to indicate progress was made.  This also informs the
      ;; highlight when following the slides in the base buffer.
      beg)))

(cl-defmethod dslide-backward ((obj dslide-action-red-paragraphs))
  (when-let* ((overlay (pop (oref obj overlays))))
    (delete-overlay overlay)
    ;; If there is a preceding overlay, move to its beginning else move to the
    ;; beginning of the heading.
    (if-let ((overlay (car (oref obj overlays))))
        (dslide-marker obj (overlay-start overlay))
      (dslide-marker obj (org-element-property :begin (dslide-heading obj))))))

7.3 Default Classes

The deck and slide class as well as actions can be sub-classed. Use the existing sub-classes of actions as example code for writing other classes. See the (eieio)eieio#Top manual for explanation of OOP in Elisp.

• ‘Action’: Creating new action subclasses are an efficient way to perform similar operations on typical kinds of org data.
• ‘Slide:’ Slides can be configured extensively by changing their actions. However, for more vertical cooperation between slides or cooperation among actions, extended slides could be useful.
• ‘Deck’: If the core methods of the deck are insufficient, extension is another option besides advice, hooks, and modifying the source.

  If you suspect you might need to sub-class the dslide-slide or dslide-deck, please file an issue because your use case is probably interesting.

8.1 Objects & Ownership

Org mode uses trees. Presentations are linear sequences. We can either traverse the tree or flatten it. Dslide chose to traverse. This design allowed implementing features such as dslide-slide-action-each-child. The children of such a parent slide exist simultaneously. A consequence of the choice not to flatten is that parents own their children. The lifecycle of a parent always encompasses its child.

• The deck object is the root of all functionality and many commands delegate through it
• The deck owns slides, which own actions
• Slide actions may further own child slides

• Life Cycles

8.2 Stateful Sequence

Presentations are supposed to be linear sequences. We want to traverse the sequence, performing the steps, entirely by calling dslide-forward and dslide-backward.

If all sequences were idempotent, we would only implement dslide-forward and dslide-backward. However, sequences often require setup and teardown before carrying out a single step. This is the “stateful” part.

Implementing this without explicit setup methods crammed too much behavior into dslide-forward and dslide-backward while also requiring them to decide if they were attempting to make progress or just performing setup. It was annoying when building actions.

Setup and teardown can happen in both directions, so there is dslide-begin and dslide-end. The latter commonly calls the former and then advances the state to the end, but some more optimal setups are possible and already in use.

Slides may be disposed of after they no longer make progress. To allow intended cleanup to happen at the right moment, the parent calls dslide-final. This can be called at any time after dslide-end or dslide-begin.

The return values for these methods matter! See flow control.

• Flow Control

8.3 Instantiating Slides

Slides are created by calling dslide--make-slide with an org element for a heading. This function interprets the class name and arguments for the new slide and instantiates the object.

The default classes and actions can be configured at the document or customize level. Set the ‘DSLIDE_DECK_CLASS’ and ‘DSLIDE_SLIDE_CLASS’ as well as other properties that work at the heading level. The order of precedence (Not fully implemented 🚧):

• Property definition of the current heading
• Property definition in the document
• Customize variable

dslide--make-slide will look in order for the highest precedence setting and then instantiate the class with that value in the slot.

8.4 Display

How various visual effects are achieved.

• Hiding
• Animation
• Full Screen Images

8.5 Element Mapping

Org’s Element API is the foundation on top of which dslide is built. It’s documentation is not currently in a manual. Here’s the web link: Org Element API docs. By using the element parser, we can avoid the issues that plague regex based implementations. (The trade-off is more garbage generation.)

Very frequently, we parse a section of the document and map over elements or headings within. This allows us to treat the document or a part of it as a list. The mapping functions all eventually delegate to dslide--map which itself uses org-element-map, narrowed to the targeted region.

It is very common when writing actions to work on only the section or only the children. For this reason, some shortcuts to map the section or children exist. Some section actions such as dslide-action-hide-markup are almost entirely built on dslide-section-map.

Frequently we are looking for an element before or after a marker, so shortcuts exist for finding the next or previous element. Section actions typically use dslide-section-next and dslide-section-previous. Slide actions typically use dslide-child-next and dslide-child-previous to traverse the child headings.

Mapping and progress tracking are intimately related. Finding the previous or next element is implemented by mapping to find the element beginning before or after a certain point. Careful handling of markers and a consistent scheme for sensing progress enable markers in the buffer to act as progress cursors for a variety of actions.

8.6 Progress Tracking

Dslide’s predecessor, org-tree-slide, frequently used the point to track state. This can be fragile and there is also only one point. To be more robust when the document is changing out from under us, dslide uses markers.

Slides keep a reference to the heading in their ‘:begin’ slot and then retrieve it using org-element-at-point. Actions similarly use a marker in order to keep track of how much of the current heading they have already used. For convenience, dslide-section-next and dslide-section-previous are used to simultaneously find the next element and update the marker, eliminating silly mistakes like forgetting to update the marker.

There are two schemes in place for tracking progress:

• When viewing a sequence of images, we reverse by going back to the previous image rather than re-showing the current image. This is the default progress scheme.
• When showing and hiding elements, we reverse undoing the most recent work. This means hiding the most recently shown or showing the most recently hidden element. This is the scheme used when REVERSE-IN-PLACE is non-nil.

⚠️ This section is fiddly and tricky. Put on your smarty hat. 👷

Normal Progress

In short, find the element beginning after (before in reverse) the marker, move the marker to its beginning, and work on that element. If there is no next element, move as far as you can.

• The heading always begins before the first element. We can reliably position before all elements by putting the marker at the beginning of the heading.
• To go forward, we find the first element beginning after the marker and move the marker to its beginning. We work on that element. It will be skipped if we immediately go backward again.
• If there is no next element, we move the marker to the end of the heading, which is after the beginning of the last element.
• To go backward, we find the first element beginning before the marker and move the marker to its beginning. We work on that element. It will be skipped if we immediately go forward again.

Reverse In Place Progress

If doing work means the next reverse step should undo that work, you need reversing in place. We need to slightly tweak our rules to allow two states on each element. Since every element ends after it begins, we can reliably use the end and beginning positions to differentiate if we already used an element when going forwards or backwards.

A very deliberate design choice was to avoid needing to return more than one element from a mapping call. This means we always want to find the element we intend to work on e.g. we do not want to find the element to work on and then have to find the next element to update the marker.

• To go forward, we find the first element beginning at or after the marker. We move the marker to the end of this element and work on this element.
• To go backward, we find the first element ending at or before the marker. We move the marker to the beginning of this element and work on this element.
• Going forward, begin at the beginning of the heading just like normal progress. The first element will not be skipped.
• Going backward, begin at the end of the heading. This is at most the end of the last element, so it won’t be skipped.

☢️ Before these two schemes were developed, some actions were easier to implement one way while others were easier the other way. There was much flip-flopping and radiation sickness from broken actions. Eventually it was realized that both schemes make perfect sense for the right problems.

⚠️ Org elements can and do overlap. Lists are one such challenge. List elements can all end at the same location. Naively calling org-element-at-point is a bad idea. See dslide-action-item-reveal for higher level interfaces.

If you need more states per element, this kind of implicit state tracking is insufficient and you will have to implement state-tracking. ⚠️ Don’t use text properties to store state in buffer text since they will persist in the base buffer between presentation starts if not cleaned up.

9.1 Work In Progress 🚧

Open issues and give feedback on feature requests. Contributions welcome. See the 1.0 feature roadmap.

• Affiliated Keyword
• Layout
• Slide Action Precedence
• Secondary Commands
• Starting From Point
• Affiliated Buffers
• Non-Graphic Display
• Improper Levels
• Counting Slides
• Non-Org Sequences

12.1 Command and Function index

12.2 Concept index

12.3 Variable index