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 configurable 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. The action system is a framework for attaching reusable, configurable programmed behavior to multiple org elements.

If Emacs does it, dslide can present it. As Emacs can use all of your programs and programming tools, so can dslide. This includes both scripting through Elisp and command-based keyboard macros. Dslide aims to integrate with other buffers and Emacs automation seemlessly.

High productivity was another goal. By respecting export settings and cleaning up markup, dslide aims to re-use the same documents you already use for storing, organizing, and publishing information. Dslide adds a bit of flair so that, with a decent org configuration, you get a decent result with little extra effort.

1.2 Strengths 🦾

Because dslide has access to all of your programming tools via Emacs, it is unmatchable by other software at presenting programming tools themselves. No tool can sell or demonstrate programming or use of raw software tools more effectively than Dslide.

Dslide is also 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:

• Friday feature demos
• Stand-ups, retros, and other rituals
• Early stage startup pitches

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. Dslide uses them to encode some action steps directly.
• ‘Affilated keyword’: A ‘#+attr_keyword_style:’ line that directly precedes an element and is used to add metadata to most org elements, except headings. 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 🪄

Actions add behavior to your content. They can be configured per-slide and in some cases per-element.

There are two kinds of actions:

• ‘Section actions’: work on the content in the heading’s section. They use the dslide-action base class and prefix.
• ‘Slide actions’: display the slide, usually by narrowing, and then handle the child headings, either inline or as independent slides. They use the dslide-slide-action base class and prefix.

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-kmacro
          +--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 Enabling Actions 🚦

Most actions are enabled by scanning for the right content. The babel action is used on babel blocks. The image action is used on image links. Some actions, especially slide actions, must be explicitly enabled. The markup used to enable actions can also be where they are configured.

• Per-Element
• Keyword
• Property Drawer
• Default Actions ⛔

#+attr_dslide_propertize: face '(:foreground "#ff0000")
This text will be red

#+dslide_kmacro: :keys [134217848 97 110]

* Inline Children
:PROPERTIES:
:DSLIDE_SLIDE_ACTION: dslide-slide-action-child :header nil
:DSLIDE_ACTIONS: dslide-action-item-reveal :inline t
:END:
- You won't believe these animations
- This is the world's greatest presentation software
  + But mainly because it integrates with all you programming tools

4.3 Configuring Actions 🎛️

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

💡 To view an action’s default values, call describe-symbol on it. Any slot definition usually has the same ‘:initarg’ and will be understood when used in the configuration.

Configuring is usually done by adding plist-style ‘:key value’ arguments after the class name, keyword, or affiliated keyword:

* A Headline For a Heading
:PROPERTIES:
# configuration after a class name
:DSLIDE_ACTIONS: dslide-action-item-reveal :inline t
:END:

# A keyword configuration
#+dslide_kmacro: :frequency 0.08 :jitter 0.5 :keys [134217848 97 110 ]

# An affiliated keyword configuration
#+attr_dslide_propertize: face '(:background "#ddddff")
This text will be propertized

🚧 After class names, 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 Babel Scripting 🧑‍💻

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

* My Heading With Babel Blocks
#+begin_src elisp
  (message "Good job!")
#+end_src

• Controlling Direction ♻️
• Ignoring Blocks 🙅
• Visibility 👻
• Confirming Evaluation 🔏
• Step Callbacks 👟

#+begin_src elisp :direction backward
  (message "I run going backwards, on `dslide-deck-backward'")
#+end_src

#+begin_src elisp :direction [end forward]
  (message "My configuration is a vector with multiple directions")
#+end_src

#+begin_src elisp :eval never
  (message "Who cares?  I am never evaluated")
#+end_src

# Only the results of this block are visible
#+begin_src elisp :exports results
  '(a b c)
#+end_src

#+begin_src elisp
  (message "Just doing block things")

  ;; Let's also push a step!
  (dslide-push-step
   (lambda (direction)
     ;; Decide what to do
     (pcase direction
       ;; `message' returns non-nil and will function as a padding step
       (forward (message "Injecting an extra step"))
       ;; `prog1' nil returns the nil, so this will not add a step
       (backward (prog1 nil (message "No step for you!")))
       ;; The _ catch-all will handle non-directional calls, such as quitting
       (_ (prog1 nil (message "Cleaning 💩 up!"))))))
#+end_src

4.5 Keyboard Macros 🤖

🧪 Experimental new feature. Hopefully the configuration argument names are good. Hopefully.

The dslide-action-kmacro will run pre-recorded sequences of keystrokes as if you are controlling the computer. Through ‘:frequency’ and ‘:jitter’, it plays back strokes at a human-feeling pace.

By playing back keyboard macros, you can encode real Emacs workflows as steps in a presentation. Don’t just talk about how your software works. Use the software with fully reproducible steps that users can understand in a tactile, human way.

To record kmacros as presentation steps, use the dslide-kmacro-transcribe-set-mark command. It will save a marker and every time you call kmacro-end-macro, it will transcribe that macro as an expression that dslide-action-kmacro knows how to play back.

🆒 The jitter uses a Laplace distribution to sample a perturbation power. This power is mapped onto the zero-to-infinity factor range by raising e to the power of jitter. This is multiplied by ‘:frequency’, which is a duration. As a result, while the jitter is usually pretty small, it does have some wild variation, which does look a bit more human.

4.6 Hiding Markup 🥷🏿

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

dslide-action-hide-markup will also hide todos and tags. You can modify this with dslide-hide-todo and dslide-hide-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 Configuration 🎩

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 completely replace the header with your own device. Check its signature!

• 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.

#+cindex confirming evaluation This is also one good way to set org-confirm-babel-evaluate and other settings that are somewhat risky to leave on generally.

# Local Variables:
# dslide-header: nil
# org-confirm-babel-evaluate: 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 Source Following

🚧 The start functions were recently overhauled. They need user feedback, both to identify bugs and focus on real uses cases. dslide-deck-start should be the most reliable way to start presentations.

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

Using comments and comment blocks, you can write down prompts or scripts to help you maintain your flow. Dslide highlights the current progress state, providing both debugging and narration feedback.

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

• Present
• Develop
• Start Functions

5.4 Cursor Visibility 🥷

By default, the cursor is hidden in the presentation buffer using dslide-cursor-hide. Remove it from the dslide-start-hook to disable this. You can call dslide-cursor-restore if you just temporarily need a cursor.

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 Key Bindings

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 top-level presentation commands begin with the dslide-deck prefix

(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 Behavior

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 methods 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
• Action Configuration 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