|
|
# Powering-up Special Blocks
Musa Al-hassy
Users will generally only make use of a few predefined \`special
blocks', such as \`example, centre, quote', and will not bother with
the effort required to make new ones. When new encapsulating notions
are required, users will either fallback on HTML or LaTeX specific
solutions, usually littered with \`#+ATTR' clauses to pass around
configurations or parameters.
Efforts have been exerted to mitigate the trouble of producing new
special blocks. However, the issue of passing parameters is still
handled in a clumsy fashion; e.g., by having parameters be expressed
in a special block's content using specific keywords.
We present a novel approach to making special blocks in a familiar
fashion and their use also in a familiar fashion. We achieve the
former by presenting \`\`defblock'', an anaphoric macro exceedingly
similar to \`\`defun'', and for the latter we mimic the usual
\`\`src''-block syntax for argument passing to support special blocks.
For instance, here is a sample declaration.
(defblock stutter () (reps 2)
"Output the CONTENTS of the block REPS many times"
(org-parse (s-repeat reps contents)))
Here is an invocation that passes an *optional* argument; which
defaults to 2 when not given.
<div class="stutter">
<p>
Emacs for the win ⌣̈
</p>
</div>
Upon export, to HTML or LaTeX for instance, the contents of this block
are repeated (\`stuttered') 5 times. The use of \`\`src''-like
invocation may lead to a decrease in \`#+ATTR' clauses.
In the presentation, we aim to show a few \`practical' special blocks
that users may want: A block that …
- translates *some selected* text —useful for multilingual blogs
- hides *some selected* text —useful for learning, quizzes
- folds/boxes text —useful in blogs for folding away details
In particular, all of these examples will be around ~5 lines long!
We also have a larger collection of more useful block types, already
implemented.
The notable features of the system are as follows.
- Familiar \`\`defun'' syntax for making block —\`\`defblock''
- Familiar \`\`src'' syntax for passing arguments —e.g., \`\`:key
value''
- Fine-grained control over export translation phases —c.f.,
\`\`org-parse'' above
- **Modular**: New blocks can be made out of existing blocks really
quickly using \`\`blockcall'' —similar to Lisp's \`\`funcall''. We
will show how to fuse two blocks to make a new one, also within ~5
lines.
It is hoped that the ease of creating custom special blocks will be a
gateway for many Emacs users to start using Lisp.
## Resources
<https://alhassy.github.io/org-special-block-extras/emacs-conf-2020>
<!-- from the pad --->
- Actual start and end time (EST): Start 2020-11-29T09.19.39; Q&A: 2020-11-29T09.36.14; End: 2020-11-29T09.48.34
# Questions
## Should packages implement the interface to one specific format, or attempt to be conclusive to all the potential output targets?
## How to share "recipes"? Will this become a "large" project, or minimal that requires you to write most customizations yourself?
## Could you make slides that show the source form on the left and the output on the right? That would make understanding each capability much simpler.
## Does typing in a block mess up the syntax highlighting? Usually themes use a single color inside an example block, for example.
"You found my crutch!". Colors in source code blocks within blocks are hard. Didn't have time yet to implement it. Any help is appreciated! :)
- That's where you can get help from org-mode core developers ;)
## +++if you export to latex->pdf does that work well with beamer as well? To create slides with columns for example?
You have to format the LaTeX appropriately for the backend "beamer".
## How does this relate to pandoc, which is used for converting between markup formats?
## Side question about org-reveal: How do you get bespoke/multiple-column layouts without using #+HTML (and <div>) everywhere in the org file?
It's a custom #begin\_parallel block! See the main article linked below.
Parallel section: <https://alhassy.github.io/org-special-block-extras/#Parallel>
## What is used to produce colorful boxes around the cursor in your browser?
Commercial software called ScreenBrush
## Why did you put optional arguments in a separate list rather than using cl-style argument lists? e.g. (defblock feedback (who &optional (color "red")) …) +1
The first argument may take some meta-information when you define it, which is easier to handle with two arguments.
## Do you intend to try to upstream this amazing work into Org? :)+1
no prior experience on how to upstream; suggestions and help appreciated
- <https://orgmode.org/contribute.html>
- Yes, I would suggest simply posting a short proposal for an org-defblock macro on the orgmode mailing list, and hopefully Bastien and other maintainers like Nicolas will discuss it with you. I think they would be excited to have this feature standardized in Org. +1+1+1+1 I am excited+1+1
add a little beginner-focused documentation and this becomes another great reason to use org over markdown, I imagine the maintainers would love to have it
# Notes
- Main article: <https://alhassy.github.io/org-special-block-extras/> (HTML or 48 page PDF)
- Slides for this talk: <https://alhassy.github.io/org-special-block-extras/emacs-conf-2020>
- [Reddit discussion](https://www.reddit.com/r/emacs/comments/k2whsy/declaring_new_special_blocks_with_arguments/)
- Elisp Reference Sheet: <https://alhassy.github.io/ElispCheatSheet/CheatSheet.pdf>
- My Emacs init: <https://github.com/alhassy/emacs.d#a-life-configuring-emacs>
|
