Test blocks in Dednat6 (subtitles)

The main page about this video is here.
Its index is here.
Its subtitles in Lua are here.
The rest of this page contains a conversion of the subtitles in Lua
to a slightly more readable format.

00:00 Hi! My name is Eduardo Ochs, and I just
00:02 gave a talk at the EmacsConf 2021
00:06 about a new feature of eev called
00:10 "test blocks"...
00:14 my talk was just five minutes long so I
00:17 couldn't give examples of how I use
00:19 test blocks in real life...

00:21 so I decided to make this video to
00:24 complement my talk on the conference,
00:26 and to show how I'm using test blocks
00:29 to document some of my programs.

00:33 What I'm going to show is how I'm
00:35 using test blocks to document a package
00:38 for LaTeX that I have that is called
00:40 Dednat6. Dednat6 is...
00:44 let me go to the first page here...

00:46 Dednat6 is an extensible
00:49 (semi-)preprocessor for LaTeX that
00:52 understands diagrams in ascii art.
00:55 Let's see what that means.

00:58 Sometimes we want to to draw diagrams
01:01 like this, and it's very boring to
01:05 generate LaTeX code like this by hand...
01:08 so I developed a program that would
01:14 understand some specifications of
01:16 diagrams in comments, for example
01:19 this one... and it would generate
01:21 the LaTeX code corresponding to these
01:23 things... so this is a representation
01:26 in ascii art of this tree here...

01:30 and my program generates the...
01:34 it does the boring part: it generates the
01:36 LaTeX code corresponding to this. And it
01:38 also supports diagrams for
01:40 Category Theory, for example this one...
01:44 that would be a nightmare to typeset by
01:46 hand... and this one, that is not so
01:49 horrible, but we can see that the source
01:52 code is quite manageable, here...

01:57 So: LaTeX interprets these things as
02:00 comments, and my program, Dednat6,
02:03 understands these things...
02:06 this block here as a specification of
02:08 a diagram, and generate the LaTeX
02:10 code for it.

02:12 And LaTeX code is very extensible, so
02:15 from time to time I create more
02:17 extensions to it...
02:19 and sometimes I have to draw new
02:24 kinds of diagrams, they're very boring
02:28 to draw by hand, so I create new
02:30 extensions to draw them...

02:33 And i'm going to show how i use eev
02:35 to document these extensions.

02:40 Just let me explain something first,
02:42 which is that... in the beginning,
02:44 when I was starting to put test blocks
02:47 in the source code of Dednat6, I was
02:50 very shy about it... I thought that
02:53 that by using test blocks in the
02:55 documentation people would be
02:57 scared, they would feel that that was
02:59 super weird... but then
03:02 I reminded myself that very few people
03:04 use Dednat6, and that now we have
03:07 packages like this one, Quiver...

03:11 Let me show it here in a new window...

03:14 And everybody is using this instead of
03:17 text-based tools...
03:20 so most people prefer to edit diagrams
03:22 in this way...

03:24 here we have an animation of how people
03:26 can edit diagrams interactively,
03:30 "in the modern way", let's say...

03:36 so this gives me much more freedom
03:39 with Dednat6. I could make a
03:41 a big mess with it, especially in the
03:43 parts of it that nobody else is using
03:46 as far as i know...

03:50 And then at some point I showed that to
03:52 some friends, and they were able to
03:54 understand the test blocks immediately...
03:57 and they could run the test blocks
04:00 without any hesitation, and they
04:01 liked them very much.

04:04 So, well... let me show how these
04:07 test blocks work, and how you can test
04:10 these test blocks...
04:13 how you can run them yourself.

04:16 Let me take this block here,
04:19 and copy it to an Emacs
04:21 that has eev loaded...

04:26 note that these things are not red stars,
04:28 they are not even red...
04:30 but this first expression here will make
04:34 them behave as red stars.

04:38 I'm going to use a smaller font here...

04:40 I'm going to type f8 four times. The first
04:42 one will make them behave as red stars...
04:45 and the other three ones will create a
04:48 target buffer here
04:50 running a shell (bash)...and now I'm
04:54 going to send these commands.

04:56 The first one will make sure that
04:59 lua5.1 is installed...
05:01 this block of four lines here
05:03 download a copy of Dednat6
05:05 to a subdirectory of /tmp/...
05:11 these lines here are comments that are
05:13 ignored by the shell...
05:16 these two lines here are things that I
05:18 do not want to explain now.

05:22 So I'm not going to explain them, I'm
05:24 going to just execute them... and skip
05:27 to this one. This one is easy to
05:29 understand because it's a hyperlink -
05:31 an elisp hyperlink that opens this file
05:34 and searches for this anchor in this
05:36 file... and this anchor is in the middle
05:40 of a very big test block.

05:42 So if we execute it with f8
05:45 we go to this position here...
05:48 we can see that this test block starts
05:54 here... but the part that I want to show
06:02 is here.

06:07 Ok, so let me execute these tests.
06:10 If I type f8 three times here they
06:13 set up a target buffer running Lua...

06:17 if I type f8 here this Lua REPL
06:19 loads this file...
06:22 and if i type f8 in these lines they
06:25 create a certain object and display it
06:27 in ascii art.

06:29 Same thing here,
06:31 same thing here,
06:32 and same thing here,
06:34 and same thing here...

06:36 note that I can also change these
06:41 tests... for example, I can do this,
06:48 and then instead of
06:50 showing the representation in ascii art
06:52 of these objects my program shows
06:57 the LaTeX code that it will generate...
07:04 let me run some undos here...
07:09 these objects here correspond to these
07:14 diagrams here, that I had to use in a
07:17 paper...
07:19 especially this one that is a bit
07:22 harder to draw...

07:24 and I'm also going to show another test
07:27 block: this one here...
07:34 it's the same thing, it shows some
07:37 objects using ascii art but I could
07:39 also show the LaTeX code
07:41 corresponding to them...
07:45 they correspond to these diagrams here
07:47 that I had to use in another part
07:49 of the same paper.

07:52 And that's it.

07:54 This demo here can be executed by just
07:57 typing f8s in the right places - if
07:59 you understand what you are doing...
08:01 and that's it. So I just showed
08:05 two test blocks, and the source code of
08:07 Dednat6, and that's what I wanted to
08:09 show. That's it! =)

00:00