?
for Help ⟫
With a bit of Lisp —and a lot of time— we obtain
a uniform, and practical, syntax for both special blocks and link types
reusing the Org src
interface —including arguments for blocks
and global header arguments for links
“write once, generate many”: Write markup in Org and have it exported to other backends!
Other fun stuff: solution, org-demo, stutter, rename, spoiler (─‿‿─)
😂 The setup joyously works for org-reveal 😹
🥰 🍭 🦄 😆
See an aesthetically pleasing style online and seek to reproduce it …
⇄ The author wrote raw HTML
Obscures my source with styling information!
⇄ The author wraps the HTML in an {{{Org-macro}}}
Not useful if I want to export to PDF!
⇄ The author doesn't even provide the source!
Time to ‘View Page Source’ and do a lot of reading!
⇉ We want Org users to have numerous styles available and an extensible mechanism to add more! ⇇
Three friends --- Amin , Sacha , and Corwin — were organising a conference
… EmacsConf2020 !
Sacha wrote an Org file and wanted some feedback
#+ATTR_REVEAL: :frag (appear)
Three friends ---green:Amin, red:Sacha,
and blue:Corwin--- were organising a conference
#+ATTR_REVEAL: :frag (appear)
... orange:EmacsConf2020!
#+html: <br>
#+ATTR_REVEAL: :frag (appear)
Sacha wrote an Org file and wanted some feedback
top-level remarks visible in the export
… suggest replacement text
… this is not possible, elegantly , with raw HTML!
translate in the export
… everyone speaks different languages!
… or suggest a rewrite, without altering the other person's text
… this is not possible with raw HTML at all !
Sacha …
Let's begin at \(\sqrt{3 + \sum_{i = 0}^{12} i}\) in the morning.
She gets feedback …
[Amin:
How about
(sqrt (apply '+ 3 (number-sequence 0 12)))
;-)
[Corwin:
C'mon guys, let's just say 9 am!
]Amin likes to export to PDF, so he wrote top-level remarks using LaTeX
#+latex: {\color{green} \fbox{[Amin:}}
Please change …
#+latex: \fbox{]}
[Amin:
Please change …
]But Sacha likes to look at the resulting HTML ! … not PDFs!
So, she may not see his top-level feedback and she may forgot to look at the Org source
Happily, she thinks things are all good …!
Sacha may write top-level feedback …
#+html: <strong> [Sacha Speculates: </strong>
I think that maybe we could try …
#+html: <strong> End of speculations] </strong>
[Sacha Speculates:
I think that maybe we could try …
End of speculations ]Now Amin exports to PDF; take a quick glance and not notice anything standing out; thinks it's all OK
Corwin actually reads an exported result, and is worried at what he sees.
Amin & Sacha agree to read up and make a uniform Org interface that exports to both HTML & PDF
They use Org “special blocks”!
They agree to figure out the necessary Lisp ,
hooks , advice , and macros needed to form a
special custom block that outputs both HTML and PDF,
but
uses Org as interface.
So much work, but it's worth it!
…!?
Corwin likes to provide terse , right to the point, feedback and thinks blocks are overkill.
The team decides to incorporate an Org-link type
and —to avoid duplication of code!--- they have the link type reuse the core code of the block type.
They have their own interface …!
Need to learn a little about
font , follow links , export handles .
Eek …!
Of course to actually write the formatting function they need loop, s-replace, mapcar, or, s-match, and much more!
Such a pain!
⇒ It's probably not worth it! |
“Just do enough to make it work!” |
“We're in a rush!” |
A modular and unified interface for producing new special blocks and link types, simultaneously , with roughly the same interface as a defun!
⇒ defblock ⇐ |
(defblock feedback (who) (color "red")
"Top level (HTML & LaTeX) constructive feedback."
(format (if (equal backend 'html)
"<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
"{\\color{%s}\\bfseries %s: %s}")
color who contents))
Huh?
There are 3 main parts …
1: (defblock feedback (who) (color "red")
2: "Top level (HTML & LaTeX) constructive feedback."
3: (format (if (equal backend 'html)
4: "<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
5: "{\\color{%s}\\bfseries %s: %s}")
6: color who contents))
Line 1: def -ine a new block named feedback whose main argument is who wrote the feedback, and optionally a color —which is red by default.
1: (defblock feedback (who) (color "red")
2: "Top level (HTML & LaTeX) constructive feedback."
3: (format (if (equal backend 'html)
4: "<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
5: "{\\color{%s}\\bfseries %s: %s}")
6: color who contents))
Line 2: Just as when you write a function, you write what it does.
Moreover, this documentation is used as a tooltip for the Org link form of feedback —for Corwin — within Emacs!
1: (defblock feedback (who) (color "red")
2: "Top level (HTML & LaTeX) constructive feedback."
3: (format (if (equal backend 'html)
4: "<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
5: "{\\color{%s}\\bfseries %s: %s}")
6: color who contents))
Line 3: Depending on whether we're exporting to HTML —for Sacha — or to PDF —for Amin — we use HTML divs or LaTeX macros.
1: (defblock feedback (who) (color "red")
2: "Top level (HTML & LaTeX) constructive feedback."
3: (format (if (equal backend 'html)
4: "<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
5: "{\\color{%s}\\bfseries %s: %s}")
6: color who contents))
Sacha 😍 Org/HTML
#+begin_feedback Sacha Speculates
I think we should do …
#+end_feedback
[Sacha Speculates:
I think we should do …
]Amin 😻 Org/PDF
#+begin_feedback Amin :color green
I think we should do …
#+end_feedback
[Amin:
I think we should do …
]Corwin 💌 Org/Terse
[[feedback:Corwin][Guys, let's wrap up already!]]
[Corwin: Guys, let's wrap up already! ]
Using a few lines of Lisp …
write text in parallel columns
… to save on vertical whitespace
Finally, blocks compose: They're building blocks for new and better ideas!
More details and examples at
https://alhassy.github.io/org-special-block-extras |
Thanks for listening in!
The org-special-block-extras Library:
https://alhassy.github.io/org-special-block-extras
… has examples, tutorial, and is a literate program! (•̀ᴗ•́)و
A 5-page PDF covering ELisp fundamentals :
These slides :
https://alhassy.github.io/org-special-block-extras/emacs-conf-2020