Hi! My name is Eduardo Ochs, and I just
gave a talk at the EmacsConf 2021
about a new feature of eev called
"test blocks"...
my talk was just five minutes long so I
couldn't give examples of how I use
test blocks in real life...
so I decided to make this video to
complement my talk on the conference,
and to show how I'm using test blocks
to document some of my programs.
What I'm going to show is how I'm
using test blocks to document a package
for LaTeX that I have that is called
Dednat6. Dednat6 is... let me go to the
first page here...
Dednat6 is an extensible
(semi-)preprocessor for LaTeX that
understands diagrams in ascii art.
Let's see what that means.
Sometimes we want to to draw diagrams
like this, and it's very boring to
generate LaTeX code like this by hand...
so I developed a program that would
understand some specifications of
diagrams in comments, for example
this one... and it would generate
the LaTeX code corresponding to these
things... so this is a representation
in ascii art of this tree here...
and my program generates the...
it does the boring part: it generates the
LaTeX code corresponding to this. And it
also supports diagrams for
Category Theory, for example this one...
that would be a nightmare to typeset by
hand... and this one, that is not so
horrible, but we can see that the source
code is quite manageable, here...
So: LaTeX interprets these things as
comments, and my program, Dednat6,
understands these things...
this block here as a specification of
a diagram, and generate the LaTeX
code for it.
And LaTeX code is very extensible, so
from time to time I create more
extensions to it...
and sometimes I have to draw new
kinds of diagrams, they're very boring
to draw by hand, so I create new
extensions to draw them...
and i'm going to show how i use eev
to document these extensions.
Just let me explain something first,
which is that... in the beginning,
when I was starting to put test blocks
in the source code of Dednat6, I was
very shy about it... I thought that
that by using test blocks in the
documentation people would be
scared, they would feel that that was
super weird... but then
I reminded myself that very few
people use Dednat6, and that now
we have packages like this one,
Quiver...
let me show it here in a new window...
and everybody is using this instead of
text-based tools...
so most people prefer to edit diagrams
in this way...
here we have an animation of how people
can edit diagrams interactively,
"in the modern way", let's say...
so this gives me much more freedom
with Dednat6. I could make a
a big mess with it, especially in the
parts of it that nobody else is using
as far as i know...
And then at some point I showed that to
some friends, and they were able to
understand the test blocks immediately...
and they could run the test blocks
without any hesitation, and they
liked them very much.
So, well... let me let me show how these
test blocks work, and how you can test
these test blocks... how you can run
them yourself.
Let me take this block here, and copy it
to an Emacs that has eev loaded...
note that these things are not red stars,
they are not even red...
but this first expression here will make
them behave as red stars.
I'm going to use a smaller font here...
I'm going to type f8 four times. The first
one will make them behave as red stars...
and the other three ones will create a
target buffer here
running a shell (bash)... and now I'm
going to send these commands.
The first one will make sure that
lua5.1 is installed...
this block of four lines here
download a copy of Dednat6
to a subdirectory of /tmp/...
these lines here are comments that are
ignored by the shell...
these two lines here are things that I
do not want to explain now.
So i'm not going to explain them, I'm
going to just execute them... and skip
to this one. This one is easy to
understand because it's a hyperlink -
an elisp hyperlink that opens this file
and searches for this anchor in this
file... and this anchor is in the middle
of a very big test block.
So if we execute it with f8
we go to this position here...
we can see that this test block starts
here... but the part that I want to show
is here.
Ok, so let me execute these tests.
If I type f8 three times here they
set up a target buffer running Lua...
if I type f8 here this Lua REPL
loads this file...
and if i type f8 in these lines they
create a certain object and display it
in ascii art.
Same thing here,
same thing here,
and same thing here,
and same thing here...
note that I can also change these
tests... for example, I can do this,
and then instead of
showing the representation in ascii art
of these objects my program shows
the LaTeX code that it will generate...
let me run some undos here...
these objects here correspond to these
diagrams here, that I had to use in a
paper...
especially this one that is a bit
harder to draw...
and I'm also going to show another test
block: this one here...
it's the same thing, it shows some
objects using ascii art but I could
also show the LaTeX code
corresponding to them...
they correspond to these diagrams here
that I had to use in another part
of the same paper.
And that's it.
This demo here can be executed by just
typing f8s in the right places - if
you understand what you are doing...
and that's it. So I just showed
two test blocks, and the source code of
Dednat6, and that's what I wanted to
show. That's it! =)