oh you are now muted
all right then well uh hello everyone
I hope uh you're all enjoying the Emacs
conf
my name is musa alhassi and I hope
you're
excited to learn about uh powering up
special blocks
um so let's let's first off uh find out
what these special blocks are and
and see what we can uh go from so
uh yesterday I saw a lot of cool talks
and uh people were chatting about how do
you
I know how should you present should you
do it this way or that way and
I thought maybe I should try a different
way uh but but I'm talking about special
blocks and if I
show you an emax then I have to export
the html so you can see what it looks
like
or export to a pdf so you can see what
it looks like
uh so I ended up writing an org reveal
and
joyously this this just works you can
you can just see things here
uh I was worried that I'd have to take
pictures and then you know
uh uh you know insert pings so that that
was a delight
okay uh so special blocks are these
things like
a center small quote uh that's what a
special block is
and with a bit of lisp we can we can
make special blocks
and link types right so uh using a
single interface
um and the interface is going to be
similar to one
many people are familiar with in
particular org babel's
source interface as well as using global
header arguments for link types
and the idea is to write it once and
generate many different kinds
right you write uh an org markup and you
can have
uh html you can have pdf and and
joyously
uh org reveal so that was uh that was an
unexpected delight
um so here is a few that you'll you'll
just see as we
uh in this presentation you know some uh
uh I won't show some of these uh link
only ones
but we'll see a few of these other ones
just to make the uh
presentation look nice so the
presentation is really going to
present these blocks and the mechanism
at the same time
so uh so this no no html was written
look ma no html just pure org mode and
and
you get all these beautiful boxes and
things okay
so the motivation for this is you know
what uh
you're you're online you run into a blog
and you see something you like and
you're like man
you know I wish I could uh you know
produce that
um uh but you you check in the author
wrote raw
html you know plus html everywhere
and uh that's that's you know gonna
obscure
your your real content it's going to be
surrounded by all this uh
styling information that's unfortunate
uh the author decides to use an org
macro all right a bit better
but then what if you decide hey I want
to make a
not pdf great and then the worst of all
the author doesn't give you the source
and then you have to view page source
and
learn cascading style sheets and and you
know
sit in a corner and cry decide to do
other things with your life
so uh we want to give you org users
numerous styles
and uh and an extensible mechanism to
add more of these
aesthetically pleasing styles you know
to have really nice things
look one way in the html and look almost
the same way
in the pdf and other uh back ends and
if by having these newer ones you know
people
might be encouraged to try making new
ones
especially when the interface is uh not
so difficult
uh that's the that's the aim okay
uh so let's let's have a a real story to
motivate this even more
um so here's three friends uh I hope I
don't butcher their names but these
friends are called
amin sasha and corwin and then they're
organizing a conference
uh EmacsConf 2020.
so sasha decides to write an org file
and and she would like some feedback
okay and and just uh make it clear
there's no
uh just how easy this looks
let's look at the source for this block
notice it's just the word green then a
colon
than amine uh so no
no div style coloring just just you know
green color
immune a very pleasant uh or markup
so that's that's quite nice put some
bold around it
not not too difficult so hopefully uh
this will be useful to
other people as well so what kind of
feedback
uh would sasha expect to get um so maybe
she would expect top level remarks
visible
in the export you know when she makes an
html she can see right there a big block
right maybe
amin will suggest to sasha please
replace this part
with this other part or replace this
word with this other word
right um this is not really possible
with raw
html or uh yeah or with even latex
you'd have to have multiple arguments
the first argument and then
the replacement argument and it's a bit
clunky
um but with our setup you just write
some text
write hashtag plus replace with and then
write more text and you're good to go
normal uh org markup um
everyone speaks different languages
maybe they want to use a
uh one word or they're arguing about
whether we talk about frames or windows
um so maybe they want to have some
translations
right so there's different kinds of
feedbacks uh let's let's take an example
uh look at what they are okay
uh so for example sasha might write
uh this org mode right here and uh
and then in her html exports you might
see this
and uh her feedback might look really
nicely from anyone who says you know
let's uh
let's do some lisp instead of uh
mathematics let's just do some list
and and corwin says you know let's let's
not be so silly
maybe let's just say 9 a.m and move on
okay
um so amin likes to export to pdf
and so he writes his top-level remarks
using latex that's how
so to get this uh square I mean please
change whatever
he might write like this hashtag you
know plus latex
hashtag plus latex right but then
sasha only exports to p to html uh for
example
um and uh so she doesn't look at the pdf
and she may not see his top-level
feedback you know with those nice
brackets and
and bold right and so she might think
everything's good
right and that can be a bit disastrous
um so maybe sasha will will then uh make
some
of her own feedback all right uh but
and to produce it she might write html
uh
um html commands hashtag plus html to
get that
uh but then amin will make a pdf and
this won't stick out
and then so he might think everything's
okay even even though it's not
um then corwin actually decides hey
uh let me read the exported result and
these
there's all those feedback from two
people who haven't uh
read anything because maybe they were in
a russian and didn't
see the top level feedback and so they
agree hey let's have a uniform org
interface that exports
to both html and pdf make both of us
happy
okay so they decide to use org special
blocks
right um and to set this up they need to
you know maybe read a little bit of lisp
hooks
advice macros to get all of this set up
and then they'll use org as the main
interface okay
it's a lot of work but it's worth it
right maybe
um but then corwin corbin's a bit tears
so
uh corwin maybe doesn't want to write
uh using blocks he thinks they're
overkill and
and sasha wants html and uh and
I mean wants pdf and corwin wants org
reveal
so now they have to reformat all their
code and then they need to use org link
types to
reduce the overkill all right so they
can try to avoid duplication by
factoring things out into self-contained
uh defined functions or defunds
um but now to set up or links
uh we'll have uh to learn a new
interface
org setup link um learn a little bit
about fonts
follow links exports handles
it's so much that's so much but but then
you know the friends they learn a lot
you know they learn about defund all
right so these these words are red
you get a little explanation I think
it's a bit too small for anyone to read
this is lisp documentation right for
defund
advice ad there's some list
documentation right
they learn about destructuring let's so
this is from the dash library
here's all that you know glorious
glorious documentation with examples
sorry
I like that they might make an ad-hoc
mechanism to simulate
arguments for special blocks so
something maybe called
extract arguments and then of course to
make new link types they have to learn
about
org link set parameters and then it's
numerous uh
bits and pieces all right so let's oh
let's uh
close all these ones down and and uh of
course they also need to be uh
comfortable with
uh loops and maps and matching and
string functions
so it's it's a bit of a pain it's a bit
of a pain
um so it's probably not worth it so
maybe I'll just
rush things quickly or do an ad hoc you
know
we have things to do right
so maybe maybe the squad wants to have a
modular
and unified interface so everyone's
comfortable with defunct to define a
function and they say you know what
it would be nice if we could just you
know define simultaneously
both a block and the link type right
and uh that way we have a single
interface
org mode for for these things and it
would be nice was
modular so if I defined a
one kind of block and you defined
another we could compose them
right and then get a you know a nice
bigger block like lego
that would be nice building box okay and
uh this is uh what we
have come up with called death block and
it also has a
long documentation string containing
examples and things
so that way you can try to be useful
okay um so let's let's look at a a
solution to these friends uh trilemma
all right so here's here's a way to
define a block
um it looks it's it doesn't look that
difficult but this is how they can
define a block for um
for uh their top-level feedback right
so let's let's look at the three main
parts together
it's not that uh difficult I hope just
six lines
and that's including a documentation
string and you know
uh new lines and things okay so in line
one we just define the block just like
you define
a function we define a block the flag
the block name is going to be called
feedback it has an author who
right the author has no default
value it has a color and the color has a
default value of red
okay so just just as when you define
functions they
they uh you start by uh define
or def block than the name some
mandatory argument and some optional
arguments okay
then the next stage is well and
definition a documentation you know
uh the people who use this which are
future you or future me you know
uh might want to know what this is all
right so let's get to document this
uh and uh for for corwin who might want
to use uh tooltips
uh when corwin writes feedback whatever
and
Emacs they'll see a nice little tooltip
and the tooltip will have
this uh documentation string right so
that'll be nice
okay and then here's the third part the
last three lines are
not not so difficult if the back end is
in
is html the backend is html
please use this template string
otherwise use the other string
okay and for each of these uh string
markers
please put in the color who wrote it and
then the contents
of the special block or the link type
okay
um so that's pretty neat not not so
difficult
so I thought that was kind of cool and
then notice it's
anaphoric it's it's a this this def
block
gives you two new names it gives you a
name called
uh contents and it gives you a name
called back end
right and so even if you're writing a
def block and you intend it to be used
only for links
uh like the uh these colors for example
uh these colors were defined using dev
block
uh and I used them as links right here
and you don't need to worry
where does the text come from in the
link you know if I say red colon bob uh
is it bob
or if I put a description is it the
description so
it's whatever is available will will
become uh the value of contents
and if you're really you know interested
and you want to do some
intricate stuff uh def block also gives
you something called
raw dash contents if you really want to
touch the raw
uh contents with all of the org markups
still there
okay so let's uh let's see
how uh everyone can uh communicate
amongst themselves
using this new interface okay so
uh uh sasha speculates and she how does
she speculate for her organ html
she might just write hey look at that no
no no html nice and and
amin wants to have some green and so he
just says hey here's some color green
and and uh there you go it looks almost
the same
right uh notice that the main argument
is right here def block took an author
and here's the author again and now the
optional argument
uses the org babel source interface you
just say
colon and then a key and then the
argument
quite quite nice and and corwin doesn't
want to
use blocks it's a bit of an overkill and
can just write a
a little um right
so the main argument is now the uh uh
the label of the link
all right and then the description of
the link is the contents
of uh of the feedback so that was quite
nice
so it looks like uh everyone uses the
same interface on the left
and can have varying uh outputs
and it looks I think it looks quite nice
and I hope you do too
um and there's a few more maybe
as you saw in some previous ones we had
text side beside side
right now um or we folded some regions
away
that was quite nice we put some things
in pretty boxes
um uh we had some spoilers at the very
beginning that we we uh hit some text uh
we demoed uh
some texts right you know here's some
org and here's what it looks like
um and and most importantly uh they they
compose
right there's uh uh there's a
a macro called uh uh thread block
uh thread block a thread block call and
it lets you thread the
the contents through a number of blocks
treating them as if they were functions
and so really you can think of a block
as a as a
as a string valued function so that's
pretty neat
I I think and uh thank you for listening
and uh
I I hope you've uh enjoyed this little
uh
happy fun time with uh with the Emacs
and friends
and uh I'll I'm I'll happy happily
answer questions
uh right now um
[Music]
so uh someone says why did you put
optional arguments in a separate list
rather than using cl style argument
lists
um so that's a very good question
and I will answer that by
showing you a more involved definition
of
feedback so let's look at a
a more involved one
right right here so for example
this one is called rural mark all right
and uh please let me know if my text is
not sufficiently big
so here is here is why uh we have
two arguments that takes two arguments
uh instead of one
for for its argument list right so you
you have def block
then you have the name right then you
have
the first uh argument list and the
second argument list
the first argument list uh takes the
takes the text right after the begin
right the text right after the begin is
the main
argument okay and then the remaining key
value pairs
are in the second argument list okay
now the reason we have two is because uh
in order to
streamline the interface to account for
both uh special blocks
and or link types uh what we do is we
say hey
uh in the first argument list uh you can
give a name to the first argument
give it a default value and anything
else you provide will become uh
uh part of the I'll co link
information so for example this link we
decided to make its face
angry red um you might want to give
other features to
links so we're trying to streamline the
interface for both
special blocks and org link types and we
thought
this way was quite nice um so
that was the main reason uh someone asks
uh so if if you uh if that's uh if you
need if you have follow-up please ask
someone asks do you intend to try to
upstream this amazing work into org
well I'm glad you like it I I don't know
how to upstream
but but I I will look into it and any
advice or guidance would be
much appreciated um you know
lisp is awesome and just as defunded as
a macro deathblock is a macro and then
source blocks are awesome and then now
maybe we can have arguments and special
blocks and motivate and encourage more
people to uh
to uh learn lisp right
so another person asks
um what is used to produce colorful
boxes around the cursor
I I'm not quite sure if you're asking
are you talking about my cursor right
here
or are you talking about in the slide um
so this this this cursor is some
application called
a stream brush that I had to purchase uh
unfortunately I could not find a a
suitable free one
um and the blocks I can demonstrate some
Emacs list but I can open up my Emacs if
people like and we can try some things
out
happy to do that uh
you're welcome uh someone asks
a side question about org reveal how do
you get
bespoke or multiple column layouts
without using html
ah excellent question that's what we do
that's that's what this uh project is
about so it's not
org reveal it's it's our fancy parallel
uh
uh block so we have this thing you say
begin parallel
you say how many columns you would like
uh do you want a bar
or not and then you write some text and
then you uh
you get some text and according with the
bar or not right so that's
that's how we achieve that in our slides
so I'm not uh I'm not quite sure where
this was
somewhere here I think
let me try to find this for you
I can't seem to find where the parallel
blocks were
apologies let's move on to the next
question I suppose
uh I'm pretty sure they're here ah there
they are
yes so these these uh were just
instances of using
uh the parallel block and it makes
things parallel
so that's quite nice um another person
asks uh yes
excellent um how does this relate to
banda pandoc
which is used for converting between
markup formats
so all we're doing is we're we're saying
hey
please write org because org is just
fantastic
and we love it and it's the dream and if
you would like to view things
in html or in org reveal or
in pdf that's up to the user so
here is a um oh
made it too small now so here is a an
example
so here's an uh how here's how parallel
is implemented
uh just as a quick example uh not too
long
uh about half of the implementation is
documentation so
uh hopefully that speaks for for how
useful this feature is
uh so we decide if there's a rule or not
um we look for the column break
and really here we're looking at the
back end if the back end is latex
uh please use this uh incantation with
multi columns mini pages what have you
and if the
back end is something else uh please uh
do this
uh div and style and uh other uh
gibberish that we don't really wanna
look at uh so
uh when you pandoc works from org
so it might not work directly since our
interface the way we set it up is when
you try to export
uh we hook in and we do a bunch of
pre-processing
so this this uh def block is a is a
string valued function
and so whenever we see these uh begin
parallel uh when you do an export
I tell Emacs hold up look for those
begin
parallels please oh you found them grab
that text
you grabbed it great now please apply
this person's uh function
onto that text and splice in the result
okay so so when you export uh we're
performing
arbitrary computations on your uh uh on
your text
so uh um some people might not find that
comforting to have
arbitrary uh computations happening so
in this article there's a few where
uh we change your text upon export we
translate it
we do other things to it um
so someone says uh if you export to
latex to pdf does that work well with
beamer as well
to create slides with columns for
example for uh
um so uh actually uh
so uh I I made a bunch of these changes
earlier this morning
and it just says latex right here um
so if you want to go to beamer I think
the back end for me
beamer is called well beamer so instead
of a
a p case what we would do is we would
say oh
if it's a latex or it's a beamer
then uh use this uh otherwise
it's not a latex it will simply default
to this one which could be
dangerous for your needs um I think it's
a bad practice to put a underscore but I
did it really quickly because I just
wanted to show you that it works fine in
org reveal contributions are more than
welcome
I I uh happily uh would love any
assistance
um and and I have a uh we have a
list a reference cheat sheet here to to
learn a little bit about lisp if you're
not comfortable or to
ask some questions lots of helpful
people
so there's another question that says uh
does typing in a block mess up with a
syntax highlighting
usually you use a single color inside an
example block for example
ah you found my crutch you found
my crutch um so I so there's
emax's is all encompassing and I'm not
quite sure how fonts work or are
you know I I learned enough to get by I
learned enough to get by
so let me um but here's
here's how links work they're they're a
bit complicated
this this is a bit scary I don't
recommend anyone
uh read it um
but uh actually let me open up an email
and you can
you can see what I see uh so here's an
Emacs
all right let's make that a bit bigger
uh let's change this
slightly nope that's worse there you go
so
here's here's some words um so here's
red hello um
but you're worried about uh preserving
uh
uh uh um quantification
so let's make an emax list block all
right
and let's say plus one two ah
where's the fun hello
um bye okay where's the coloring
if we if we zoom in on this on this
begin source block
if we zoom in you can see down here
uh we have our our coloring all right
when we zoom in
if we if we zoom out ah no coloring
zoom in coloring it's about ah no
coloring
let's take off these bad boys and oh
look my coloring's back
so um in a previous
uh iteration of the system I was able to
maintain coloring
uh in this new iteration I am not I
don't know how to do it I haven't uh
had the time to to implement it I spent
a lot of time writing this uh
48 page uh documentation uh with uh
with some fun examples to to to try to
help
people learn so but but I would
appreciate any help or guidance on
how to uh maintain the quantification I
I really would like to keep those colors
in
um musa we have time for maybe one more
question
um one or two more questions and then we
have to move on to the next talk
um but yeah you're more than welcome to
take continue taking the questions via
irc or the pad
okay thank you thank you
let's uh the final question we'll take
is
um should packages implement
interface to one specific format or
attempt to be conclusive to all the
potential output targets
I think you should just make them as you
go and you know add them as you need
them we'll make uh
help requests or things and uh
we can we can share recipes in this uh
document and then
try to add other uh techniques and then
and we can uh use these blocks as a
common uh interface for
for exporting to pdf and other things
and since someone asked here is a um
here is uh what a pdf looks like this is
the same pdf and
uh rendered uh just I made no effort to
make it look good
but it surprisingly does look good so so
uh that was
uh that was nice um that was a
terrible magenta but that is life uh
anyhow
I hope you all enjoyed this talk I hope
you will find um
death block uh useful to you it is
available on melbourne
uh in a rush to make it available for
EmacsConf 2020 some melba
guidelines may not have been in here too
please do not
hit me um and I hope everyone enjoys the
rest of the EmacsConf
2020 thank you