Adding support for aasvg graphics. (#216)

* Adding support for aasvg graphics.

Adding support for aasvg graphics/diagrams.

Example:

```aasvg
+--------+    .-------.     +--------+
| Server +-->+ Message +--->+ Client |
+--------+    '-------'     +--------+
```

Further: some minor syntax and grammar/text fixes.

Signed-off-by: Michael Eckel <[email protected]>

* Adding example for aasvg diagrams in guide.tcg.

Signed-off-by: Michael Eckel <[email protected]>

---------

Signed-off-by: Michael Eckel <[email protected]>

Author: eckelmeckel

.github/workflows/render.yml

@@ -73,6 +73,7 @@ jobs:
             *.upb
             *.convert.pdf
             *.mermaid.pdf
+            *.aasvg.pdf
           key: latex-${{ inputs.input }}-${{ inputs.container-version }}-${{ github.run_id }}
           restore-keys: latex-${{ inputs.input }}-${{ inputs.container-version }}
 

Dockerfile

@@ -238,15 +238,17 @@ RUN tlmgr update --self && tlmgr install \
     zref
 
 RUN apt install -y \
+    aasvg \
     dbus \
     imagemagick \
+    librsvg2-bin \
     libxss1 \
     openbox \
     wget \
     xorg \
     xvfb
 
-ENV DRAWIO_RELEASE=24.7.8
+ENV DRAWIO_RELEASE=26.0.16
 
 # TARGETPLATFORM is linux/arm64 or linux/amd64. The release for amd64 is called drawio-amd64-23.1.5.deb.
 RUN export DRAWIO_DEB=drawio-${TARGETPLATFORM#linux/}-${DRAWIO_RELEASE}.deb && \

README.md

@@ -16,6 +16,7 @@ The interesting dependencies are:
   (Pandoc/LaTeX template, with some TCG-specific modifications)
 * [Mermaid](https://mermaid-js.github.io/mermaid/#/) /
   [mermaid-filter](https://github.com/raghur/mermaid-filter) (for rendering diagrams)
+* [aasvg](https://github.com/martinthomson/aasvg) (for rendering ASCII art diagrams)
 
 # How to Use
 

build.sh

@@ -670,6 +670,7 @@ do_latex() {
 		--no-highlight
 		--template=tcg.tex
 		--lua-filter=mermaid-filter.lua
+		--lua-filter=aasvg-filter.lua
 		--lua-filter=informative-sections.lua
 		--lua-filter=convert-images.lua
 		--lua-filter=center-images.lua
@@ -745,6 +746,7 @@ do_pdf() {
 	# Copy converted images so they can be cached as well.
 	cp *.convert.pdf "${SOURCE_DIR}" 2>/dev/null
 	cp *.mermaid.pdf "${SOURCE_DIR}" 2>/dev/null
+	cp *.aasvg.pdf "${SOURCE_DIR}" 2>/dev/null
 	echo "Elapsed time: $(($end-$start)) seconds"
 	# Write any LaTeX errors to stderr.
 	>&2 grep -A 5 "! " "${logfile}"
@@ -779,6 +781,7 @@ do_docx() {
 		--embed-resources
 		--standalone
 		--lua-filter=mermaid-filter.lua
+		--lua-filter=aasvg-filter.lua
 		--lua-filter=convert-images.lua
 		--lua-filter=parse-html.lua
 		--lua-filter=apply-classes-to-tables.lua
@@ -819,6 +822,7 @@ do_html() {
 		--embed-resources
 		--standalone
 		--lua-filter=mermaid-filter.lua
+		--lua-filter=aasvg-filter.lua
 		--lua-filter=parse-html.lua
 		--lua-filter=apply-classes-to-tables.lua
 		--lua-filter=landscape-pages.lua

filter/aasvg-filter.lua

@@ -0,0 +1,84 @@
+-- Turn aasvg-classed code blocks into figures, retaining other classes on the
+-- code block as classes on the figure.
+
+function runCommandWithInput(command, input)
+    local pipe = io.popen(command, "w")
+    if not pipe then
+        return false
+    end
+    pipe:write(input)
+    pipe:flush()
+    pipe:close()
+    return true
+end
+
+function runCommandSuppressOutput(command)
+    -- N.B.: we are using io.popen so we can suppress the output of the command.
+    local pipe = io.popen(command)
+    if not pipe then
+        return false
+    end
+    pipe:flush()
+    local output = pipe:read("*all")
+    pipe:close()
+    return true
+end
+
+function getContentsHash(contents)
+    return pandoc.sha1(contents):sub(1,10)
+end
+
+function fileExists(file)
+    local f = io.open(file)
+    if f then
+        f:close()
+        return true
+    end
+    return false
+end
+
+function aasvgFigure(code, caption, attrs)
+    local filename_base = getContentsHash('code=' .. code .. 'caption=' .. pandoc.utils.stringify(caption) .. 'attrs=' .. pandoc.utils.stringify(attrs)) .. '.aasvg'
+    local filename_svg = filename_base .. '.svg'
+    local filename_pdf = filename_base .. '.pdf'
+
+    if fileExists(filename_pdf) then
+        print(string.format('%s already exists; not re-rendering it', filename_pdf))
+    else
+        print(string.format('rendering %s using aasvg ...', filename_svg))
+        if not runCommandWithInput(string.format(
+            "aasvg --fill > %s 2>&1", filename_svg), code) then
+            print(string.format('failed to convert ASCII art SVG (aasvg) diagram to %s using aasvg, falling back to letting LaTeX try to pick it up', filename_svg))
+            return false
+        end
+
+        print(string.format('converting %s to %s using rsvg-convert ...', filename_svg, filename_pdf))
+        if not runCommandSuppressOutput(string.format("rsvg-convert --format=pdf --keep-aspect-ratio --output %s %s 2>&1", filename_pdf, filename_svg)) then
+            print(string.format('failed to convert %s to %s using rsvg-convert, falling back to letting LaTeX try to pick it up', filename_svg, filename_pdf))
+            return false
+        end
+    end
+
+    local img = pandoc.Image(caption, filename_pdf)
+    return pandoc.Figure(img, caption, attrs)
+end
+
+function CodeBlock(el)
+    local isAasvg = false
+    local figure_classes = pandoc.List({})
+    for i, class in ipairs(el.classes) do
+        if class == 'aasvg' then
+            isAasvg = true
+        else
+            figure_classes:insert(class)
+        end
+    end
+    if isAasvg then
+        local caption = {long = pandoc.Plain(pandoc.Str(el.attributes.caption))}
+        local attrs = pandoc.Attr(el.identifier, figure_classes)
+        el.identifier = nil
+        el.classes = {'aasvg'}
+        return aasvgFigure(el.text, caption, attrs)
+    end
+    return el
+end

filter/convert-images.lua

@@ -42,41 +42,51 @@ end
 -- Wrap calls to drawio in xvfb-run. Note that --no-sandbox has to be the last argument.
 -- https://github.com/jgraph/drawio-desktop/issues/249
 function drawio(source, dest)
-    print(string.format('converting %s using drawio...', source))
+    print(string.format('converting %s using drawio ...', source))
     if not runCommandSuppressOutput(string.format("xvfb-run -a drawio -x -f pdf --crop -o %s %s --no-sandbox 2>&1", dest, source)) then
-        print(string.format('failed to convert %s to %s using drawio, falling back to letting latex try to pick it up', source, dest))
+        print(string.format('failed to convert %s to %s using drawio, falling back to letting LaTeX try to pick it up', source, dest))
         return false
     end
     return true
 end
 
 function imagemagick(source, dest)
-    print(string.format('converting %s using imagemagick...', source))
+    print(string.format('converting %s using ImageMagick ...', source))
     if not runCommandSuppressOutput(string.format("convert -density 300 %s %s 2>&1", source, dest)) then
-        print(string.format('failed to convert %s to %s using imagemagick, falling back to letting latex try to pick it up', source, dest))
+        print(string.format('failed to convert %s to %s using ImageMagick, falling back to letting LaTeX try to pick it up', source, dest))
+        return false
+    end
+    return true
+end
+
+function svg(source, dest)
+    print(string.format('converting %s using rsvg-convert...', source))
+    if not runCommandSuppressOutput(string.format("rsvg-convert --format=pdf --keep-aspect-ratio --output %s %s 2>&1", dest, source)) then
+        print(string.format('failed to convert %s to %s using rsvg-convert, falling back to letting LaTeX try to pick it up', source, dest))
         return false
     end
     return true
 end
 
 function string:hassuffix(suffix)
-    return self:sub(-#suffix) == suffix
+    return self:sub(-#suffix):lower() == suffix:lower()
 end
 
 function converterFor(filename)
     if filename:hassuffix('.drawio') or filename:hassuffix('.drawio.svg') then
         return drawio
-    end
-    if filename:hassuffix('.jpg') or filename:hassuffix('.png') or filename:hassuffix('.svg') then
+    elseif filename:hassuffix('.jpg') or filename:hassuffix('.png') or filename:hassuffix('.webp') then
         return imagemagick
+    elseif filename:hassuffix('.svg') then
+        return svg
     end
     return nil
 end
 
 function Image (img)
     -- Try to convert anything that is not a pdf, jpg, or png.
-    -- This allows us to support file types that latex doesn't (e.g., SVG),
-    -- as well as speed up the latex render iterations.
+    -- This allows us to support file types that LaTeX doesn't (e.g., SVG),
+    -- as well as speed up the LaTeX render iterations.
     local converter = converterFor(img.src)
     if converter then
         local new_filename = img.src .. '.' .. getFileHash(img.src) .. '.convert.pdf'
@@ -96,4 +106,4 @@ function Image (img)
         print(string.format("    not converting %s", img.src))
     end
     return img
-end
+end

filter/informative-quote-blocks.lua

@@ -13,4 +13,4 @@ function BlockQuote(el)
         pandoc.RawBlock('latex', '\\end{mdframed}')
     }))
     return result
-  end
+end

filter/mermaid-filter.lua

@@ -30,10 +30,10 @@ function mermaidFigure(code, caption, attrs)
     if fileExists(filename) then
         print(string.format('%s already exists; not re-rendering it', filename))
     else
-        print(string.format('rendering %s using Mermaid...', filename))
+        print(string.format('rendering %s using Mermaid ...', filename))
         if not runCommandWithInput(string.format(
             "mmdc --configFile /resources/filters/mermaid-config.json --puppeteerConfigFile ./.puppeteer.json --width 2000 --height 2000 --backgroundColor transparent --pdfFit --input - --output %s 2>&1", filename), code) then
-            print(string.format('failed to convert %s to %s using drawio, falling back to letting latex try to pick it up', source, dest))
+            print(string.format('failed to convert Mermaid diagram to %s using mmdc, falling back to letting LaTeX try to pick it up', filename))
             return false
         end
     end

guide.tcg

@@ -562,7 +562,7 @@ Users are encouraged to use AES instead.
 
 # Figures {#sec:figures}
 
-There are two ways to include a figure in a document: as an image file checked into the repository, and as a [Mermaid](http://mermaid.js.org) diagram.
+There are various ways to include a figure in a document: as an image file checked into the repository, as a [Mermaid](http://mermaid.js.org) diagram, and as an [aasvg](https://github.com/martinthomson/aasvg) diagram.
 
 ## Images
 
@@ -670,6 +670,59 @@ graph TD;
 Crossreferences to Mermaid diagrams are supported by providing both `caption`
 and `#fig:xxxxx` classes in curly braces.
 
+
+## aasvg diagrams
+
+[aasvg](https://github.com/martinthomson/aasvg) converts ASCII art diagrams into SVG.
+It is inspired by [goat](https://github.com/blampe/goat) but rather than a
+reimplementation, the code uses the original
+[markdeep](https://casual-effects.com/markdeep/) code.
+
+Here is an example aasvg diagram:
+
+````md
+```aasvg {caption="(v)TPM Key Management" #fig:tpm-key-management}
+ .---------------------.    .----.
+|  Virtual Environment  |  | vTPM +--------------.-----------------.----------------.
+ '---------------------'    '----'                |                 |                |
+                                       +----------)-----------------)----------------)--------+
+ .-------------------------------.    /|          |                 |                |        |
+|        Virtual Platform         |  / |          |handle           |handle          |handle  |
+ '-------------------------------'  /  |          v                 v                v        |
+                                   /   | +--------+--------+ +------+-------+ +------+------+ |
+ .---------------------.   +------+    | |      vTPM       | |    vTPM      | |    vTPM     | |
+| Virtualization System |  | pTPM |    | | Endorsement Key | | Platform Key | | Storage Key | |
+ '---------------------'   +------+    | +--------+--------+ +------+-------+ +------+------+ |
+                                   \   |           '-----------------'---------. .--'         |
++---------------------------------+ \  | +-----------------+ +--------------+ +-+-----------+ |
+|        Physical Machine         |  \ | |   Endorsement   | |   Platform   | | ◌ Storage   | |
++---------------------------------+   \| +-----------------+ +--------------+ +-------------+ |
+                                       +------------------------------------------------------+
+```
+````
+
+```aasvg {caption="(v)TPM Key Management" #fig:tpm-key-management}
+ .---------------------.    .----.
+|  Virtual Environment  |  | vTPM +--------------.-----------------.----------------.
+ '---------------------'    '----'                |                 |                |
+                                       +----------)-----------------)----------------)--------+
+ .-------------------------------.    /|          |                 |                |        |
+|        Virtual Platform         |  / |          |handle           |handle          |handle  |
+ '-------------------------------'  /  |          v                 v                v        |
+                                   /   | +--------+--------+ +------+-------+ +------+------+ |
+ .---------------------.   +------+    | |      vTPM       | |    vTPM      | |    vTPM     | |
+| Virtualization System |  | pTPM |    | | Endorsement Key | | Platform Key | | Storage Key | |
+ '---------------------'   +------+    | +--------+--------+ +------+-------+ +------+------+ |
+                                   \   |           '-----------------'---------. .--'         |
++---------------------------------+ \  | +-----------------+ +--------------+ +-+-----------+ |
+|        Physical Machine         |  \ | |   Endorsement   | |   Platform   | | ◌ Storage   | |
++---------------------------------+   \| +-----------------+ +--------------+ +-------------+ |
+                                       +------------------------------------------------------+
+```
+
+See the [aasvg website](https://github.com/martinthomson/aasvg) for more examples.
+
+
 ## DrawIO Diagrams
 
 Some diagrams can't easily be represented in (human-maintained) code.