branch: elpa/dslide commit f2ef90a2bd8f389b224b44be512ae9726e110384 Author: Psionik K <73710933+psioni...@users.noreply.github.com> Commit: Psionik K <73710933+psioni...@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+psioni...@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: