Skip to content

Latest commit

 

History

History
733 lines (580 loc) · 21.1 KB

emacs-conf-2020.org

File metadata and controls

733 lines (580 loc) · 21.1 KB

#

#

#

css

#

#

Overview

With a bit of Lisp —and a lot of time— we obtain

  1. a uniform, and practical, syntax for both special blocks and link types
  2. reusing the Org src interface —including arguments for blocks and global header arguments for links
  3. “write once, generate many”: Write markup in Org and have it exported to other backends!

Motivation

See an aesthetically pleasing style online and seek to reproduce it …


Once upon a time

Three friends —green:Amin, red:Sacha, and blue:Corwin— were organising a conference

… orange:EmacsConf2020!


Sacha wrote an Org file and wanted some feedback


What kind of feedback?

  • top-level remarks visible in the export

    … suggest red:replacement text

    … this is not possible, green: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!

Example 💓 Text and Feedback

Sacha …

She gets feedback …

Amin ❤️ LaTeX

#+latex: {\color{green} \fbox{[Amin:}}
  Please change …
#+latex:  \fbox{]}

Sacha 💔 PDF

Amin 💢 HTML

Sacha may write top-level feedback …

💥 😧 💭 📖

Corwin cyan: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”!

How to set up special blocks?

They agree to figure out the necessary magenta:Lisp,

cyan:hooks, blue:advice, and violet:macros needed to form a

special custom block that outputs both HTML and PDF,
green:but uses Org as interface.

So much work, but it’s worth it!

…!?

Corwin 🥶 🤔 🥊 Terse!

Corwin likes to provide blue:terse, right to the point, feedback and thinks blocks are overkill.

The team decides to incorporate an red:Org-link red:type

and —to avoid duplication of code!— they have the link type reuse the core code of the block type.

How to setup Org links?

They have their own interface…!

gray:Need violet:to magenta:learn a red:little blue:about

teal:font, orange:follow cyan:links, purple:export pink:handles.

Eek …!

The friends learn a lot!

  • doc:defun, for making red:functions to format their blocks!
  • doc:advice-add, for advising Emacs utilities to blue:handle their new special blocks
  • doc:-let, pattern matching / “destructuring lets”
  • extract-arguments, an red:ad-hoc mechanism to cyan:simulate arguments with special blocks
  • doc:org-link-set-parameters, to make new link types

green:Of green:course to actually write the formatting function they need doc:loop, doc:s-replace, doc:mapcar, doc:or, doc: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!”

Goals

Solving the friend’s trilemma

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

Line 1: Declare a block

(defblock feedback (who) (color "red")    (ref:here1)
  "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))

Line 2: Document the block

(defblock feedback (who) (color "red")
  "Top level (HTML & LaTeX) constructive feedback." (ref:here2)
  (format (if (equal backend 'html)
            "<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
            "{\\color{%s}\\bfseries %s: %s}")
          color who contents))

Lines 3-6: Do the thing!

(defblock feedback (who) (color "red")
  "Top level (HTML & LaTeX) constructive feedback."
  (format (if (equal backend 'html)  (ref:here3)
            "<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
            "{\\color{%s}\\bfseries %s: %s}")
          color who contents))

Anaphoric?

(defblock feedback (who) (color "red")
  "Top level (HTML & LaTeX) constructive feedback."
  (format (if (equal backend 'html)  (ref:anaB)
            "<strong style=\"color: %s;\">⟦%s: %s⟧</strong>"
            "{\\color{%s}\\bfseries %s: %s}")
          color who contents))  (ref:anaC)

How do the feedback?

More Blocks!

Using a few lines of Lisp …

  • write text in parallel columns

    … to save on vertical whitespace

  • hide away technical details for the interested reader only
  • enclose text in a pretty box
  • Educational material blocks: spolier, solution, and org-demo

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

Bye!

Thanks for listening in!