[nongnu] elpa/dslide 7ae80ecdca 194/230: cleaning up light misinformation

[ELPA Syncer]

branch: elpa/dslide
commit 7ae80ecdca53ba56efeb0978bd6b64fd68105793
Author: Psionik K <73710933+psionic-k@users.noreply.github.com>
Commit: Psionik K <73710933+psionic-k@users.noreply.github.com>

    cleaning up light misinformation
    
    MC is too raw to recommend right now.  Well, dslide got relatively more 
mature.
    
    Cleaned up some comments that are aimed at prospective package hackers.
    
    Some whitespace changes.
    
    Signed-off-by: Psionik K <73710933+psionic-k@users.noreply.github.com>
---
 README.md      | 17 ++++++-----------
 doc/README.org | 17 +++++++----------
 dslide.el      | 45 +++++++++++++++++++++++++--------------------
 3 files changed, 38 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index 6f37751372..362d7cd959 100644
--- a/README.md
+++ b/README.md
@@ -162,14 +162,6 @@ Beware of using the normal `dslide-mode-hook` 😱 because it 
runs **in the base
     (setq dslide-after-last-slide-hook #'my-stop-if-forward)
 
 
-## Recommended MC Settings
-
-The out-of-the-box experience can be a bit messy due to property drawers, 
keywords, and babel blocks that you might include.  You probably want to hide 
these elements.  [Master of 
Ceremonies](https://github.com/positron-solutions/master-of-ceremonies) 
contains some flexible hiding that can be updated with each slide and turned on 
and off only when the slideshow is active.
-
-    ;; Something like this should work
-    (add-hook 'dslide-start-hook mc-hide-cursor-mode)
-
-
 ## Heading Properties
 
 Headings are treated as slides.  Slides have actions.  Actions are configured 
in the property drawer.
@@ -234,6 +226,8 @@ The `dslide-section-next`  and `dslide-section-previous` 
method documentation ar
 -   override a few methods
 -   now you too can paint the paragraphs red
 
+You can view the effect of this example in the demo.
+
     (defclass dslide-action-red-paragraphs (dslide-action)
       ((overlays :initform nil))
       "Paint the paragraphs red, one by one.")
@@ -309,11 +303,12 @@ This package is focused on creating a linear presentation 
sequence. For function
 
 The 
[master-of-ceremonies](https://github.com/positron-solutions/master-of-ceremonies)
 package contains utilities for display & presentation frame setup that are not 
specific to using DSL IDE.
 
--   **hide markup**
--   display a region full-screen
+-   display a region full-screen using `mc-focus`.  Check the full commands by 
pressing `h` during focus.  You can highlight a region, save an expression to 
playback a code snippet without the buffer open etc.
 -   silence messages during presentation
 -   hide the cursor or make it very subtle
--   extract notes and display them in a separate frame
+
+    ;; Also check `mc-subtle-cursor-mode'
+    (add-hook 'dslide-start-hook mc-hide-cursor-mode)
 
 
 ## Open Broadcaster Software
diff --git a/doc/README.org b/doc/README.org
index 06b2a9fdfd..9e98b9774b 100644
--- a/doc/README.org
+++ b/doc/README.org
@@ -117,13 +117,6 @@ Beware of using the normal ~dslide-mode-hook~ 😱 because it 
runs *in the base
 
   (setq dslide-after-last-slide-hook #'my-stop-if-forward)
 #+end_src
-** Recommended MC Settings
-The out-of-the-box experience can be a bit messy due to property drawers, 
keywords, and babel blocks that you might include.  You probably want to hide 
these elements.  
[[https://github.com/positron-solutions/master-of-ceremonies][Master of 
Ceremonies]] contains some flexible hiding that can be updated with each slide 
and turned on and off only when the slideshow is active.
-#+begin_src elisp
-  ;; Something like this should work
-  (add-hook 'dslide-start-hook mc-hide-cursor-mode)
-#+end_src
-
 ** Heading Properties
 Headings are treated as slides.  Slides have actions.  Actions are configured 
in the property drawer.
 
@@ -174,6 +167,8 @@ The ~dslide-section-next~  and ~dslide-section-previous~ 
method documentation ar
 - declare a class
 - override a few methods
 - now you too can paint the paragraphs red
+
+You can view the effect of this example in the demo.
 #+begin_src elisp
   (defclass dslide-action-red-paragraphs (dslide-action)
     ((overlays :initform nil))
@@ -235,11 +230,13 @@ Because babel blocks are not actions, using 
~dslide-push-step~ may be the only w
 This package is focused on creating a linear presentation sequence. For 
functionality not related to integrations into the ~dslide-deck-forward~ 
~dslide-deck-backward~ interface, it is better to maintain separate packages 
and use hooks and babel scripting.
 ** Master of Ceremonies
 The 
[[https://github.com/positron-solutions/master-of-ceremonies][master-of-ceremonies]]
 package contains utilities for display & presentation frame setup that are not 
specific to using DSL IDE.
-- *hide markup*
-- display a region full-screen
+- display a region full-screen using ~mc-focus~.  Check the full commands by 
pressing =h= during focus.  You can highlight a region, save an expression to 
playback a code snippet without the buffer open etc.
 - silence messages during presentation
 - hide the cursor or make it very subtle
-- extract notes and display them in a separate frame
+#+begin_src elisp
+  ;; Also check `mc-subtle-cursor-mode'
+  (add-hook 'dslide-start-hook mc-hide-cursor-mode)
+#+end_src
 ** Open Broadcaster Software
 Sacha Chua has written an OBS plugin integration helpful for video integration 
[[https://github.com/sachac/obs-websocket-el][obs-websocket-el]].
 ** Orgit
diff --git a/dslide.el b/dslide.el
index 44ebe7874c..bce92252b2 100644
--- a/dslide.el
+++ b/dslide.el
@@ -63,8 +63,8 @@
 ;; 1. Class interface definitions for stateful sequence, deck (root sequence),
 ;; slide, and actions (sequences that run within slides).
 ;;
-;; 2. Element mapping implementations that are private but exposed publicly on
-;; slide actions and elsewhere because they are super useful.
+;; 2. Org element mapping implementations that are private but exposed publicly
+;; on slide actions and elsewhere because they are super useful.
 ;;
 ;; 3. Miscellaneous implementation details of parsing arguments, debug 
printing,
 ;; header, animation etc.
@@ -80,8 +80,8 @@
 ;;
 ;; For hackers wishing to extend the code, in addition, you will want to check
 ;; `dslide--make-slide' if you want your slides to hydrate actions differently.
-;; Also pay very close attention to `dslide-stateful-sequence' and how 
sequences and
-;; steps can be pushed.
+;; Also pay very close attention to `dslide-stateful-sequence' and how 
sequences
+;; and steps can be pushed.
 ;;
 ;; This package is a fork and mostly complete re-write of org-tree-slide by
 ;; Takaaki ISHIKAWA.  Thanks to everyone who worked on org-tree-slide over the
@@ -417,13 +417,17 @@ coordinate with it.")
   "Configure `display-buffer-alist' to override.")
 
 ;; * Classes
-;; - `dslide-deck': is the first thing called into by
-;;   `dslide-deck-forward' and `dslide-deck-backward'.
+;; - `dslide-deck': is the first thing called into by `dslide-deck-forward' and
+;;   `dslide-deck-backward'.  It chooses root headings to hydrate as slides 
and forwards
+;;   these commands into the slides.
 ;;
-;; - `dslide-slide': interprets an org heading into some actions, which
+;; - `dslide-slide': interprets an org heading into some actions and 
coordinates
+;;   forwarding calls into actions in the correct order.  Through their 
actions,
+;;   slides may forward calls into other slides.
 ;;
 ;; - `dslide-action': does most of the actual work of narrowing, hiding,
-;;   animating, executing babel etc.
+;;   animating, executing babel etc.  Actions with `slide-action' in their name
+;;   likely hydrate child slides and forward calls into them.
 
 ;; The generic functions below are the most important interfaces for all 
hacking
 ;; of this package.
@@ -500,10 +504,10 @@ inappropriate, it should be overridden.
 In cases where you don't need a real backward implementation or
 progressing backwards would have no sensible behavior, you can
 delegate this to `dslide-begin' and possibly delegate
-`dslide-deck-backward' to `dslide-deck-forward',
-resulting in a sequence that always starts at the beginning and
-always proceeds to the end.  For a single step sequence that has
-identical effect in both directions, this is appropriate.
+`dslide-deck-backward' to `dslide-deck-forward', resulting in a
+sequence that always starts at the beginning and always proceeds
+to the end.  For a single step sequence that has identical effect
+in both directions, this is appropriate.
 
 This method should work together with `dslide-end' and
 `dslide-final' to ensure consistently valid state for
@@ -578,9 +582,10 @@ perform necessary teardown, the stateful sequence provides 
`begin'
 `end' and `final' methods.
 
 It can also be indexed by high-level navigation commands.  The
-implementation of `dslide-goto' Sequences can run as sub-sequences,
-where one sequence calls into another.  🚧 This capability is largely
-unimplemented, but compatible with existing work.
+implementation of `dslide-goto' Sequences can run as
+sub-sequences, where one sequence calls into another.  🚧 This
+capability is largely unimplemented, but compatible with existing
+work.
 
 Classes that wish to implement the stateful sequence interface
 just need to support a few methods and then rely on the generic
@@ -932,8 +937,8 @@ order.")
 ;; headings.  We can pretty much divide the likely user needs into either what
 ;; to do with the section and what to do with the child headings.
 ;;
-;; The section needs to be narrowed to, and this narrowing must be performed
-;; both forwards and backwards.  Narrowing and the display of children are
+;; The contents needs to be narrowed to, and this narrowing must be performed
+;; both forwards and backwards.  Narrowing and the handling of children are
 ;; usually coupled, so control over the restriction and the child headings is
 ;; combined into one slide action.  This action is run outside of section
 ;; actions, enabling
@@ -1261,10 +1266,10 @@ for `dslide-contents-map'."
 
 ;; ** Babel Action
 
-;; TODO automatically map the blocks during begin and remove results... this is
-;; kind of implemented but seems to inconsistently work.
+;; TODO automatically map the blocks during begin and remove results
 ;; TODO configure results removal behavior with an argument
-;; TODO integrate with skipping with begin and end.
+;; TODO enable aborting after a failure.  Right now there is a behavior to ask
+;; to visit a block
 (defclass dslide-action-babel (dslide-action)
   () "Execute source blocks as steps.
 By default blocks execute one by one with forward.  You can mark a block to