Hintergrundbild
Navigation

Blockdiag filter for pandoc

Version: 0.1.0
Article in PDF format

Table of Contents


ASCII Art with blockdiag and pandoc

The blockdiag tool converts ASCII art images to formats suitable for HTML, LaTeX and other formats. It is implemented as a pandoc filter using the Python pandocfilters module.

Installation

blockdiag needs a Python interpreter v3.x and ReportLab for PDF and Pillow for PNG and JPEG images.

Usage

The filter works on fenced code blocks that have the class .blockdiag. A given identifier will be used as the image filename, otherwise a SHA-1 checksum will be generated.

This example code shows how to draw boxes connected by arrows:

  ~~~ {#box_and_fills .blockdiag}

  diagram admin {
    top_page -> config -> config_edit -> config_confirm -> top_page;
  }
  ~~~

The resulting image:

The Filter Code

<blockdiag-filter.py>=

  #!/usr/bin/env python3
  
  """
  Pandoc filter to process code blocks with class "blockdiag" containing
  blockdiag_ ASCII art into images.  Assumes that blockdiag, funcparserlib and
  Pillow modules a installed:
  
      pip install blockdiag
  
  Tested with pandocfilters-1.3.0 and pandoc 1.16.0.2.
  
  _blockdiag: http://blockdiag.com/en/blockdiag/index.html
  
  """
  __author__ = "Meik Teßmer"
  __email__ = "mtessmer@wiwi.uni-bielefeld.de"
  __version__ = "0.1.0"
  
  
  import hashlib
  import subprocess
  import sys
  
  from pandocfilters import toJSONFilter, Para, Image
  
  
  def sha1(x):
      return hashlib.sha1(x.encode()).hexdigest()
  
  
  def blockdiag2img(key, value, format, meta):
      if key=='CodeBlock':
          [[ident, classes, keyvals], code] = value
  
          if "blockdiag" in classes:
              caption = ""
              typef = ""
              keyvals = {}
  
              if ident:
                  outfile = ident
              else:
                  outfile = sha1(code)
  
              if format=='html':
                  filetype = 'png'
              elif format=='latex':
                  filetype = 'pdf'
              else:
                  filetype = 'png'
  
              dest = outfile + '.' + filetype
  
              alt = 'caption'
              tit = alt
  
              build_image(code, filetype, dest)
              print('written blockdiag', dest, file=sys.stderr)
  
              return Para([Image(['', [], []], [], [dest, tit])])
  
  
  def build_image(code, filetype, outfile):
      args = ['blockdiag3', '-T' + filetype, '-o' + outfile, '-']
      p = subprocess.Popen(args, stdin=subprocess.PIPE, universal_newlines=True)
      out, err = p.communicate(input=code)
      if err:
          print('error while generating', outfile, file=sys.stderr)
  
  
  if __name__ == "__main__":
      toJSONFilter(blockdiag2img)
  

Todo

  • enhance filter for seqdiag (simple sequence-diagram image generator), actdiag (simple activity-diagram image generator) and nwdiag (simple network-diagram image generators).

<build-script>=

  #!/bin/sh
  if [ -z "${NOWEB_SOURCE}" ]; then
          NOWEB_SOURCE=pandoc_blockdiag_filter.nw
  fi
  if [ -z "${NOWEB_CODE}" ]; then
          NOWEB_CODE=`pwd`/code
  fi
  
  # check if we need to create target dirs
  [ -d ${NOWEB_CODE} ] || mkdir -p ${NOWEB_CODE}
  
  FILES="blockdiag-filter.py"
  
  for f in ${FILES}; do
          tangle -R"$f" "${NOWEB_SOURCE}" > "${NOWEB_CODE}/$f"
          chmod u+x "${NOWEB_CODE}/$f"
  done
  

Code Chunks

Aktuelles

ipmi-telegraf

2017-02-09

ipmi-telegraf: IPMI-Skript für Telegraf-exec-Plugin veröffentlicht.

blockdiag-Filter für pandoc

2016-10-28

Die Version 0.1.0 des pandoc-Filters für blockdiag-ASCII-Bilder wurde veröffentlicht.

Update nw2md2ctags auf v0.1.3

2015-04-21

Das Werkzeug nw2md2ctags wurde auf die Version 0.1.3 aktualisiert.

Filter für die Verwendung von ASCII-Art mit pandoc

2015-04-08

Der pandoc_aafigure_filter ermöglicht die Verwendung von ASCII-Art-Bildern in pandoc-Dokumenten und generiert automatisch die entsprechenden Bilder.