Pict2e-lua: a library for diagrams that is being developed with eev and test blocks

For info on what this library is, see its github page:
https://github.com/edrx/pict2e-lua/
https://github.com/edrx/pict2e-lua/#introduction

Here is a screenshot (of this test; click the image to enlarge it):

Pict2e-lua is a uninteresting library that is being developed in an interesting way - with test blocks.

1. Try it!

If you want to see in practice how "development with test blocks" works, you can download and test Pict2e-lua by just running the two eepitch blocks below,

• (eepitch-shell)
• (eepitch-kill)
• (eepitch-shell)
sudo apt-get install texlive-base lua5.1
sudo apt-get install texlive-latex-extra texlive-latex-recommended

• (setenv "LUA_INIT" "@/tmp/pict2e-lua/edrxlib.lua")
• (eepitch-shell)
• (eepitch-kill)
• (eepitch-shell)

rm -Rfv /tmp/pict2e-lua/
mkdir   /tmp/pict2e-lua/
cd      /tmp/pict2e-lua/
git clone https://github.com/edrx/pict2e-lua .

# (find-fline "/tmp/pict2e-lua/")
# (code-c-d "pict2elua" "/tmp/pict2e-lua/" :anchor)
# (find-pict2elua "Pict2e1.lua")
# (find-pict2elua "Pict2e1-1.lua")

...and then running a few other, aham, "obvious", steps. I will explain these steps in three ways. If you are very familiar with eev then the (first) explanation is just this:

• Make sure that eev, lua-mode, and pdf-tools are installed,
• make sure that Lua5.1 and LaTeX are installed,
• clone the pict2e-lua repo with the second eepitch block above,
• run the `code-c-d' to define `find-pict2elua',
• open either Pict2e.lua or Pict2e-1.lua,
• run the one-liners in its header,
• run the test blocks.

If you are not very familiar with eev, then you will prefer the (second) explanation, that is this video:

Click here to watch it on Youtube, or click on the image above to watch it in MP4. The quality of the MP4 is better, but on Youtube it has subtitles.

The other (third) explanation is below - it's a textual version, with lots of links, of the explanations above.

2. The textual explanation

You will need these Emacs packages: eev, from ELPA, and lua-mode and pdf-tools, from NonGNU ELPA.

The first eepitch block above installs Lua5.1 and LaTeX; it supposes that you are in Debian. The packages texlive-latex-extra and texlive-latex-recommended are needed because this .tex file uses xcolor and colorweb, and I was too lazy to remove these dependencies.

After running the second eepitch block you will need to run this sexp in it with `M-e',

# (code-c-d "pict2elua" "/tmp/pict2e-lua/" :anchor)

to define the function `find-pict2elua'; note that the extra argument ":anchor" to code-c-d defines the function `find-pict2elua' as a "short hyperlink to an anchor". There is a good explanation of "short hyperlinks to anchors" here:

(find-1stclassvideo-links "eevfherel")
(find-eevfherelvideo "17:02" "4.2. The option :anchor for `code-c-d'")

After running the `code-c-d' you can run the sexps that visit the files Pict2e1.lua and Pict2e1-1.lua.

Now comes a step that needs a bit of hindsight. Both Pict2e1.lua and Pict2e1-1.lua start with headers that contain these one-liners in comments:

-- (defun a  () (interactive) (find-angg "LUA/Pict2e1.lua"))
-- (defun b  () (interactive) (find-angg "LUA/Pict2e1-1.lua"))
-- (defun ab () (interactive) (find-2b '(a) '(b)))
-- (defun et () (interactive) (find-angg "LATEX/2022pict2e.tex"))
-- (defun eb () (interactive) (find-angg "LATEX/2022pict2e-body.tex"))
-- (defun ao () (interactive) (find-angg "LATEX/2022pict2e.lua"))
-- (defun v  () (interactive) (find-pdftools-page "~/LATEX/2022pict2e.pdf"))
-- (defun tb () (interactive) (find-ebuffer (eepitch-target-buffer)))
-- (defun etv () (interactive) (find-wset "13o2_o_o" '(tb) '(v)))
-- (setenv "PICT2ELUADIR" "~/LATEX/")
--
-- (code-c-d "pict2elua" "/tmp/pict2e-lua/" :anchor)
-- (defun a  () (interactive) (find-pict2elua "Pict2e1.lua"))
-- (defun b  () (interactive) (find-pict2elua "Pict2e1-1.lua"))
-- (defun ab () (interactive) (find-2b '(a) '(b)))
-- (defun et () (interactive) (find-pict2elua "2022pict2e.tex"))
-- (defun eb () (interactive) (find-pict2elua "2022pict2e-body.tex"))
-- (defun v  () (interactive) (find-pdftools-page "/tmp/pict2e-lua/2022pict2e.pdf"))
-- (defun tb () (interactive) (find-ebuffer (eepitch-target-buffer)))
-- (defun etv () (interactive) (find-wset "13o2_o_o" '(tb) '(v)))
-- (setenv "PICT2ELUADIR" "/tmp/pict2e-lua/")

These are two separate blocks of sexps. The first block, that ends with (setenv "PICT2ELUADIR" "~/LATEX/"), corresponds to the setup in my machine, and the second block, that ends with (setenv "PICT2ELUADIR" "/tmp/pict2e-lua/"), is the setup for people who downloaded Pict2e-lua in /tmp/pict2e-lua/, and are testing it there. You need to execute all the sexps in the second block. The obvious way to execute them is to type `M-e <down>' many times, but it is more practical to type `M-7 M-e' many times - i.e., `M-7e7e7e7e7e7e7e7e7e7e'. The prefix `M-7' for `M-e' is explained here.

After executing the second block of sexps the function `etv' will be defined in the right way. It will be used in some test blocks to create a multiwindow setup like this one,

.__________________
|         |        |
|         |  Lua   |
|         |  REPL  |
|   Lua   |________|
|  file   |        |
|         |  PDF   |
|         |  file  |
|_________|________|

and to make sure that the .pdf being displayed is synced with the one on disk.

The occurrences of `(etv)' in test blocks are always like this:

= p:bshow()
• (etv)

They have a non-red-star line that run a method like :show() or :bshow() immediately followed by a red star line that runs `(etv)'. The methods :show() and :bshow() call methods from the class Show; its comments describe it as:

-- Show a chunk of tex code by saving it to 2022pict2e-body.tex,
-- latexing 2022pict2e.tex, and displaying the resulting PDF.

The lines with :show() and :bshow() take several seconds to execute, because they create a .tex file and run pdflatex to generate a .pdf from it, and this is slow - 6 seconds on my machine. You will have to wait until the :show() or :bshow() answers something like this,

Show: /tmp/pict2e-lua/2022pict2e-body.tex => Success!!!

and then you can execute the

• (etv)

with <f8> to display the .pdf.

The "orbit" figure from the screenshot was generated by this test block:

(find-angg "LUA/Pict2e1-1.lua" "Plot2D-test2")

3. Download the video

You can watch the video on Youtube here, and you can download it with the two wgets below:

# See:  http://anggtwu.net/eev-videos.html
#       http://anggtwu.net/eev-videos.html#mpv-keys
# Play: (find-2022pict2eluavideo "0:00")
# Info: (find-1stclassvideo-links "2022pict2elua")
# Subs: (find-1stclassvideolsubs  "2022pict2elua")

wget -nc http://anggtwu.net/eev-videos/2022-pict2e-lua.mp4
wget -N  http://anggtwu.net/eev-videos/2022-pict2e-lua.vtt
mpv --fs --osd-level=2 2022-pict2e-lua.mp4