[nongnu] elpa/dslide f2ef90a2bd 209/230: document various results / exports behaviors in babel demos

[ELPA Syncer]

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

    document various results / exports behaviors in babel demos
    
    also restructured to introduce a bit at a time
    
    Signed-off-by: Psionik K <73710933+psionic-k@users.noreply.github.com>
---
 test/demo.org | 179 +++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 121 insertions(+), 58 deletions(-)

diff --git a/test/demo.org b/test/demo.org
index 6814fa2ef7..82de56b29c 100644
--- a/test/demo.org
+++ b/test/demo.org
@@ -133,10 +133,83 @@ You can't see this during the presentation.  Convenient 
for reminding yourself t
 #+end_comment
 There is a comment block above this paragraph.  There is a comment below this 
paragraph.  Neither are visible when using the defaults.
 # There is a comment after this paragraph too.
-* Babel Slide Integration
+
+This is another case where you can use ~dslide-deck-develop~ to see the 
comments while showing just presentation content in another window.  (use 
~make-frame~ 💡)
+* Babel Integration
+:PROPERTIES:
+:DSLIDE_ACTIONS: dslide-action-babel
+:END:
+To make your blocks interactive, set the =:DSLIDE_ACTIONS:= property to 
=dslide-action-babel= in the property drawer.
+#+begin_src elisp
+  (message "By default, a block is just a forward step.")
+#+end_src
+
+** Forwards & Backwards
+:PROPERTIES:
+:DSLIDE_ACTIONS: dslide-action-babel
+:END:
+- Blocks can be marked with the =#+attr_dslide:= affiliated keyword to execute 
in a certain order.  (unmarked default is forward)
+- Blocks can be marked =forward=, =backward=, or =both= to run via 
~dslide-deck-forward~ or ~dslide-deck-backward~.
+- The markup keywords are hidden during presentation by default.  Use 
~dslide-deck-develop~ to see both markup and presentation simultaneously. 
(Executed blocks are highlighted! 💡)
+- Note, if there is no =backward= block, when entering the slide going 
backward, the slide will begin as if going forward because there is no backward 
step.
+#+attr_dslide: backward
+#+begin_src elisp
+  ;; Called when going backward
+  (random 100)
+#+end_src
+
+# using the default behavior, going forward
+#+begin_src elisp
+  ;; Unmarked blocks will run going foward
+  (random 100)
+#+end_src
+
+#+attr_dslide: both
+#+begin_src elisp
+  ;; Called when going either way
+  (random 100)
+#+end_src
+
+#+attr_dslide: forward
+#+begin_src elisp
+  ;; An explicitly forward marked block
+  (random 100)
+#+end_src
+
+** Begin, End, and Final
 :PROPERTIES:
 :DSLIDE_ACTIONS: dslide-action-babel
 :END:
+If you need to initialize some code, the =begin= and =end= methods can be 
used.  To clean up, use a =final= block.
+
+Enter this slide going backwards to observe the "end" behavior.
+
+#+attr_dslide: begin
+#+begin_src elisp
+  (setq-local my-dslide-var 'beginning)
+#+end_src
+
+#+attr_dslide: both
+#+begin_src elisp
+  (message "Entered slide at: %s" my-dslide-var)
+#+end_src
+
+#+attr_dslide: end
+#+begin_src elisp
+  (setq-local my-dslide-var 'end)
+#+end_src
+
+#+attr_dslide: final
+#+begin_src elisp
+  (kill-local-variable 'my-dslide-var)
+#+end_src
+
+** Reusing Blocks
+:PROPERTIES:
+:DSLIDE_ACTIONS: dslide-action-babel
+:END:
+Multiple blocks can have the =begin=, =end=, and =final= method.  They are 
always executed top to bottom.  These blocks can be shared among blocks marked 
=forward=, =backward=, and =both=.  This allows better code re-use.
+
 Go 2-3 steps forwards and then backwards.  This slide also supports starting 
at the end.  Just go to the next slide and back up.
 #+attr_dslide: begin end
 #+begin_src elisp :results none
@@ -173,93 +246,83 @@ Go 2-3 steps forwards and then backwards.  This slide 
also supports starting at
   (mapc #'delete-overlay overlays)
   (makunbound 'overlays)
 #+end_src
-* Babel Exports & Results Clearing
+** Hiding Blocks
 :PROPERTIES:
 :DSLIDE_ACTIONS: dslide-action-babel
 :END:
-#+attr_dslide: begin
-#+begin_src elisp :results replace
-  (message "off to a good start")
-#+end_src
-
-#+attr_dslide: backward
-#+begin_src elisp :results replace
-  (message "I am ignored when going forward: %s" (random 100))
-#+end_src
-
-#+attr_dslide: forward
-#+begin_src elisp :results replace
-  (message "I am ignored when going backwards: %s" (random 100))
-#+end_src
-
-#+attr_dslide: both
-#+begin_src elisp :results replace
-  (message "replace my results: %s" (random 100))
-#+end_src
-
-#+attr_dslide: both
-#+begin_src elisp :exports none
-  (message "exports set to none.  should be invisible")
-#+end_src
-
-#+attr_dslide: both
-#+begin_src elisp
-  (message "No options set.  Nothing cared about.")
-#+end_src
-
-#+attr_dslide: both
-#+begin_src elisp :exports results
-  (message "I am exporting my results")
-#+end_src
-
-* Hidden Babel Slide
-This slide has a child, but it will not be displayed.  It will only run the 
babel block within, which finds and updates the text below:
+The babel block header argument =exports= is recognized and controls 
visibility of the block and its results.  The babel blocks in this slide are 
not visible at all.  The blocks find and updates the text below:
 
 Can has display?
-** No Display!  Only Execute!
-:PROPERTIES:
-:DSLIDE_SLIDE_ACTION: nil
-:DSLIDE_ACTIONS: dslide-action-babel
-:END:
-These four org blocks will not be displayed since this slide has no slide 
action.  They will however execute when navigating forward and backward.  Note 
these features:
 
-- Blocks can have methods
-- Multiple blocks can have the begin, end, and final method.  They are always 
executed top to bottom.  This allows better code re-use.
+Try forwards and backwards.  There are several hidden steps.
 
+⚠️ This example also uses =:results none=, not because they would be visible, 
but because the return type is an overlay that babel can't serialize as output.
 #+attr_dslide: end begin
-#+begin_src elisp :results none
+#+begin_src elisp :exports none :results none
   ;; No need to deal with restriction or restore point.
-  (org-up-heading-safe)
+  (org-back-to-heading t)
   (if (re-search-forward "\?" nil t)
       (setq-local dslide-can-has-overlay
                   (make-overlay (match-end 0) (match-end 0)))
-    (message "Ouchie, the document changed!"))
+    (error "Ouchie, the document changed!"))
 #+end_src
 
-Some extra setup that can also be returned to with step backwards
 #+attr_dslide: begin backward
-#+begin_src elisp :results none
+#+begin_src elisp :exports none :results none
   (overlay-put dslide-can-has-overlay 'after-string
                (propertize "  No display!  Only execute!"
                            'face 'error))
 #+end_src
 
-When going backwards, we begin at the end, which can also be stepped forwards 
to
 #+attr_dslide: forward end
-#+begin_src elisp :results none
+#+begin_src elisp :exports none :results none
   (overlay-put dslide-can-has-overlay 'after-string
                (propertize "  No display!  Only execute!"
                            'face 'success))
 #+end_src
 
-Our cleanup is always run, after everything
 #+attr_dslide: final
-#+begin_src elisp :results none
+#+begin_src elisp :exports none :results none
   (when (bound-and-true-p dslide-can-has-overlay)
     (delete-overlay dslide-can-has-overlay)
     (makunbound 'dslide-can-has-overlay))
 #+end_src
-* Package Integration
+** Results Only
+:PROPERTIES:
+:DSLIDE_ACTIONS: dslide-action-babel
+:END:
+The babel in this block will show results after being called but the block 
itself is never visible.
+#+begin_src elisp :exports results
+  '(a b c)
+#+end_src
+
+** Silent Results
+:PROPERTIES:
+:DSLIDE_ACTIONS: dslide-action-babel
+:END:
+For blocks you want to be visible but are only running for effects, you can 
use the built-in babel block header argument =results= and set it to =none=
+#+attr_dslide: both
+#+begin_src elisp :results none
+  (let* ((block (org-element-at-point))
+         (overlay (make-overlay (org-element-property :begin block)
+                                (org-element-property :end block))))
+    (overlay-put overlay 'face '(:inverse-video t))
+    (setq-local dslide--example-overlay overlay))
+#+end_src
+#+attr_dslide: final
+#+begin_src elisp :results none :exports none
+  (when (bound-and-true-p dslide--example-overlay)
+    (delete-overlay dslide--example-overlay)
+    (makunbound 'dslide--example-overlay))
+#+end_src
+** Retaining Results
+:PROPERTIES:
+:DSLIDE_ACTIONS: dslide-action-babel :remove-results nil
+:END:
+By default, blocks will clear results on entry, either forward or backward.  
To retain them, set the action argument =:retain-results t=.  This might be 
useful if you have a figure that is not dynamic.
+#+begin_src elisp
+  `(this result will not be removed when entering the slide ,(random 100))
+#+end_src
 :PROPERTIES:
 :DSLIDE_ACTIONS: dslide-action-babel
 :END:
@@ -293,7 +356,7 @@ Our cleanup is always run, after everything
 #+begin_src elisp :results none
   (mc-focus "🖊️🍍🍎🖊️")
   #+end_src
-* Babel is every Feature
+** Babel is every Feature
 :PROPERTIES:
 :DSLIDE_ACTIONS: dslide-action-babel
 :END: