pandoc-imagine 0.1.7

A filter to process codeblocks into images or ascii art

                                          \\\///
                                         / _  _ \
                                       (| (.)(.) |)
                .--------------------.OOOo--()--oOOO.-------------------.
                |                                                       |
                |        ____                          _                |
                |       /  _/____ ___   ____ _ ____ _ (_)____   ___     |
                |       / / / __ `__ \ / __ `// __ `// // __ \ / _ \    |
                |     _/ / / / / / / // /_/ // /_/ // // / / //  __/    |
                |    /___//_/ /_/ /_/ \__,_/ \__, //_//_/ /_/ \___/     |
                |                           /____/                      |
                |                                                       |
                '-------------------.oooO-------------------------------'
                                     (   )   Oooo.
                                      \ (    (   )
                                       \_)    ) /
                                             (_/

A pandoc filter to process codeblocks into images and/or ascii art

Imagine is a pandoc filter that will turn codeblocks tagged with certain classes into images or ascii art. The following are currently supported:

actdiag, asy, asymptote, blockdiag, boxes, circo, ctioga2, ditaa, dot, fdp,
figlet, flydraw, gle, gnuplot, graph, graphviz, gri, imagine, mermaid, mscgen,
neato, nwdiag, octave, packetdiag, pic, pic2plot, plantuml, plot, ploticus,
protocol, pyxplot, rackdiag, seqdiag, sfdp, shebang, twopi

Examples

Mscgen

```{.mscgen im_out="img,fcb" im_fmt="png"}
msc {
 hscale="1.3", arcgradient = "8";

 a [label="Client"],b [label="Server"];

 a=>b [label="data1"];
 a-xb [label="data2"];
 a=>b [label="data3"];
 a<=b [label="ack1, nack2"];
 a=>b [label="data2", arcskip="1"];
 |||;
 a<=b [label="ack3"];
 |||;
}
```

Mermaid

```{.mermaid im_opt="-H 300" im_fmt="png" im_out="img,fcb"}
sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?
```

Gnuplot

```{.gnuplot im_fmt="png" im_out="img,fcb"}
set terminal png
set dummy u,v
set key bmargin center horizontal Right noreverse enhanced autotitles nobox
set parametric
set view 50, 30, 1, 1
set isosamples 50, 20
set hidden3d back offset 1 trianglepattern 3 undefined 1 altdiagonal bentover
set ticslevel 0
set title "Interlocking Tori"
set urange [ -3.14159 : 3.14159 ] noreverse nowriteback
set vrange [ -3.14159 : 3.14159 ] noreverse nowriteback
splot cos(u)+.5*cos(u)*cos(v),sin(u)+.5*sin(u)*cos(v),.5*sin(v) with lines,\
1+cos(u)+.5*cos(u)*cos(v),.5*sin(v),sin(u)+.5*sin(u)*cos(v) with lines
```

Shebang using Python & Pygal

```{.shebang im_fmt="png" im_out="img,fcb"}
#!/usr/bin/env python3
import sys
import pygal
from math import cos
xy_chart = pygal.XY()
xy_chart.title = 'XY Cosinus'
xy_chart.add('x = cos(y)', [(cos(x / 10.), x / 10.) for x in range(-50, 50, 5)])
xy_chart.add('y = cos(x)', [(x / 10., cos(x / 10.)) for x in range(-50, 50, 5)])
xy_chart.render_to_png(sys.argv[-1])
```

boxes

/*       _\|/_
         (o o)
 +----oOO-{_}-OOo------------------------------+
 |    #!/bin/bash                              |
 |    # I seem to have got myself boxed in!    |
 |    cat $0 | boxes -d peek -p h4             |
 +--------------------------------------------*/

```{.shebang im_out="stdout,fcb"}
#!/bin/bash
# I seem to have got myself boxed in!
cat $0 | boxes -d peek -p h4
```

More examples on github, which also includes formats other than png.

Documentation

Imagine
  A pandoc filter to turn fenced codeblocks into graphics or ascii art by
  wrapping some external command line utilities, such as:

    actdiag, asy, asymptote, blockdiag, boxes, circo, ctioga2, ditaa, dot,
    fdp, figlet, flydraw, gle, gnuplot, graph, graphviz, gri, imagine,
    mermaid, mscgen, neato, nwdiag, octave, packetdiag, pic, pic2plot,
    plantuml, plot, ploticus, protocol, pyxplot, rackdiag, seqdiag, sfdp,
    shebang, twopi


Installation

    % sudo -H pip install pandoc-imagine

    or simply save `pandoc_imagine.py` anywhere along python's sys.path


Dependencies

    % sudo -H pip install pandocfilters six

    and one (or more) of the packages that provide above utilities.


Pandoc usage

    % pandoc --filter pandoc-imagine document.md -o document.pdf


Markdown usage

    ```cmd
    code
    ```

  Alternate, longer form:

    ```{.cmd im_opt=".." ...}
    code
    ```

  which will run `cmd` (if known) to proces the `code` into an image and
  replaces the fenced code block with an Image in a paragraph of its own or any
  ascii art in its own CodeBlock.

  If the command fails, the original fenced code block is retained unchanged.
  Usually, only errors are printed to stderr but you can get more info by
  setting the `im_log` option (see below).

  If the command succeeds but produces no image, a line reporting the missing
  image is included in the output document.


Imagine options

  Imagine's behaviour can be influenced by setting these options:

  - im_opt="" or any cli-options to pass in on the command line.
    Some classes already provide some defaults (as required by the command).

  - im_out="img", or ordered csv-list of keywords indicating what to produce:
    - img     an image-link in a paragraph
    - ocb     the original codeblock but without imagine's class or options
    - fcb     an anonymous codeblock containing the original codeblock
    - stdout  an anonymous codeblock containing captured stdout (if any)
    - stderr  an anonymous codeblock containing captured stderr (if any)

    Some workers ignore 'img' by necessity since they donot produce graphical
    data that can be linked to, e.g. `figlet` or `protocol`, while others the
    'stdout' will ignored because that's where they produce their graphical
    data.

  - im_prg=None, or a cli-cmd name to override class-to-command map.
    Normally, the class on the code block maps directly to a command line
    tool to use. For example,
    ```gri
    ..
    ```
    maps gri to `gri`, but that can be changed by `{.gri im_prg="gri2"} to use
    `gri2` instead of `gri`.

  - im_fmt="png", or another output format of your choosing depending on the
    command line tool used.  Some tools donot derive their output image format
    from an intended output file name extension, but instead require it to be
    set in the tool's codeblock containing its instructions.  Be sure the code
    in the codeblock matches `im_fmt` or pandoc may have trouble assembling the
    final document.

  - im_dir="pd", or antoher absolute or relative (to the working directory)
    path in which input/output files are to be stored during processing.
    Note that an "-images" is still tacked onto the end of the path though.

  - im_log=0, which defaults to printing only errors caught during processing.
    Set it to -1 to completely silence Imagine, or as high as 4 for debug level
    output if somethings goes wrong and you need more information on what is
    going on.

  Option values are resolved in order of most to least specific:

  1. {.klass im_xyz=".."}       codeblock specific
  2. imagine.klass.im_xyz: ..   metadata, klass specific
  3. imagine.im_xyz: ..         metadata, imagine specific
  4. class variable             hardcoded default

  Notes:
  - filenames are based on a hash of the codeblock + its attributes
  - uses subdir `{im_dir}-images` to store any input/output files
  - there's no clean up of files stored there
  - if an output filename exists, it is not regenerated but simply linked to.
  - `packetdiag`'s underlying library seems to have some problems.

  Some commands follow a slightly different pattern:
  - 'img' directive is ignored by commands that only produce ascii
  - ctioga2 defaults to pdf instead of png
  - flydraw produces a gif, not png
  - gle also creates a .gle subdir inside the images-dir
  - gri produces a ps, which is `convert`ed to png
  - imagine reads its code as help-topics, returns codeblocks with help-info
  - plot reads its codeblock as the relative path to the file to process
  - pyxplot will have `set terminal` & `set output` prepended to its `code`
  - shebang runs its codeblock as a script with <fname>.{im_fmt} as its argument.
    - use {.shebang im_out="stdout"} for text instead of an png


Merge `Image`'s into a single `Para`.

  Based on a [*feature request*](https://github.com/hertogp/imagine/issues/16)
  by [*pbsds*](,https://github.com/pbsds) `pandoc-imagine` has been extended to
  better cooperate with
  [*pandoc-crossref*](https://github.com/lierdakil/pandoc-crossref#pandoc-crossref-filter-),
  whose [*subfigure
  grids*](https://lierdakil.github.io/pandoc-crossref/#subfigure-grid) facility
  requires that consecutive image links be located inside a single paragraph.

  This means that `Div`'s, when assigned the `pandoc-imagine` specific class
  `im_merge`, will have their block-level elements processed individually.  Any
  consecutive `Image`-links are collected into a single `Para`, other elements
  are included in the `Div` contents as-is.

  See Examples/inline.md and Examples/inline.pdf.


Security

  Imagine just hands the fenced codeblocks to plotting tools to process or
  simply runs them as system scripts, as-is.

  Shebang's are inherently unsafe and most of the plotting tools implement
  their own 'little' languages, which can create beautiful images, but can also
  cause harm.

  There is no way to check for 'side effects' in advance, so make sure to check
  the fenced codeblocks before running them through the filter.


Imagine class

The imagine class puts documentation of topics at your fingertips, like so:

    ```imagine
    klass
    ```

  Use `imagine` as klass to get the module's docstring (ie this text) and/or
  one or more of the commands you're interested in, each on a separate line.


Thanks for feedback:

  amietn, chdemko, heyrict, priiduonu, K4zuki, pbsds

Individual Classes

Asy

    sudo-apt-get install asymptote

    See http://asymptote.sourceforge.net/
    
    Runs asy -o <fname>.{im_fmt} {im_opt} <fname>.asy
    Wraps:
    -  'asy' -> asy
    -  'asymptote' -> asy

BlockDiag

    sudo pip install blockdiag nwdiag actdiag seqdiag
    http://blockdiag.com/
    
    Runs {im_prg} {im_opt} -T {im_fmt} <fname>.{im_fmt} -o <fname>.{im_prg}
    Wraps:
    -  'blockdiag' -> blockdiag
    -  'seqdiag' -> seqdiag
    -  'rackdiag' -> rackdiag
    -  'nwdiag' -> nwdiag
    -  'packetdiag' -> packetdiag
    -  'actdiag' -> actdiag

Boxes

    sudo apt-get install boxes
    http://boxes.thomasjensen.com
    
    Runs boxes {im_opt} <fname>.boxes
    Wraps:
    -  'boxes' -> boxes

Ctioga2

    sudo apt-get install ctioga2
    http://ctioga2.sourceforge.net
    
    Runs ctioga2 {im_opt} -f <fname>.ctioga2
    Wraps:
    -  'ctioga2' -> ctioga2

Ditaa

    sudo apt-get install ditaa
    http://ditaa.sourceforge.net
    
    Runs ditaa <fname>.ditaa <fname>.{im_fmt} {im_opt}
    Wraps:
    -  'ditaa' -> ditaa

Figlet

    sudo apt-get install figlet
    http://www.figlet.org
    
    Runs figlet {im_opt} < code-text
    Wraps:
    -  'figlet' -> figlet

Flydraw

    sudo apt-get install flydraw
    http://manpages.ubuntu.com/manpages/precise/man1/flydraw.1.html
    notes:
    - graphic data is printed to stdout
    - so 'stdout' in im_out option is silently ignored
    
    Runs flydraw {im_opt} < code-text
    Wraps:
    -  'flydraw' -> flydraw

Gle

    sudo apt-get install gle-graphics
    http://glx.sourceforge.net
    
    Runs gle {im_opt} -verbosity 0 -output <fname>.{im_fmt} <fname>.gle
    Wraps:
    -  'gle' -> gle

GnuPlot

    sudo apt-get install gnuplot
    http://www.gnuplot.info
    notes:
    - graphic data is printed to stdout
    - so 'stdout' in im_out option is silently ignored
    
    Runs gnuplot {im_opt} <fname>.gnuplot > <fname>.{im_fmt}
    Wraps:
    -  'gnuplot' -> gnuplot

Graph

    sudo apt-get install plotutils
    https://www.gnu.org/software/plotutils
    notes:
    - graphic data is printed to stdout
    - so 'stdout' in im_out option is silently ignored
    
    Runs graph -T png {im_opt} <fname>.graph
    Wraps:
    -  'graph' -> graph

Graphviz

    sudo apt-get install graphviz
    http://graphviz.org
    
    Runs {im_prg} {im_opt} -T{im_fmt} <fname>.{im_prg} <fname>.{im_fmt}
    Wraps:
    -  'dot' -> dot
    -  'neato' -> neato
    -  'twopi' -> twopi
    -  'circo' -> circo
    -  'fdp' -> fdp
    -  'sfdp' -> sfdp
    -  'graphviz' -> dot

Gri

    sudo apt-get install gri imagemagick
    http://gri.sourceforge.net
    Notes
    - insists on creating a <fname>.ps in current working directory
    - requires `convert` from imagemagick
    - ImageMagick's security policy might need massaging
    
    Runs gri {im_opt} -c 0 -b <fname>.gri
    Wraps:
    -  'gri' -> gri

Imagine

    pip install pandoc-imagine
    https://github.com/hertogp/imagine
    
    Runs returns documentation in a CodeBlock
    Wraps:
    -  'imagine' -> imagine

Mermaid

    sudo npm install mermaid.cli
    https://github.com/mermaidjs/mermaid.cli
    
    Runs mmdc -i <fname>.mermaid -o <fname>.<fmt> {im_opt}
    Wraps:
    -  'mermaid' -> mmdc

MscGen

    sudo apt-get install mscgen
    http://www.mcternan.me.uk/mscgen
    
    Runs mscgen -T {im_fmt} -o <fname>.{im_fmt} <fname>.mscgen
    Wraps:
    -  'mscgen' -> mscgen

Octave

    sudo apt-get install octave
    https://www.gnu.org/software/octave
    
    Runs octage --no-gui -q {im_opt} <fname>.octave <fname>.{im_fmt}
    Wraps:
    -  'octave' -> octave

Pic2Plot

    sudo apt-get install plotutils
    https://www.gnu.org/software/plotutils
    notes:
    - graphic data is printed to stdout
    - so 'stdout' in im_out option is silently ignored
    
    Runs pic2plot -T png {im_opt} <fname>.pic2plot
    Wraps:
    -  'pic2plot' -> pic2plot
    -  'pic' -> pic2plot

PlantUml

    sudo apt-get install plantuml
    http://plantuml.com
    
    Runs plantuml -t{im_fmt} <fname>.plantuml {im_opt}
    Wraps:
    -  'plantuml' -> plantuml

Plot

    sudo apt-get install plotutils
    https://www.gnu.org/software/plotutils
    notes:
    - graphic data is printed to stdout
    - so 'stdout' in im_out option is silently ignored
    
    Runs plot -T {im_fmt} {im_opt} <code-text-as-filename>
    Wraps:
    -  'plot' -> plot

Ploticus

    sudo apt-get install ploticus
    http://ploticus.sourceforge.net/doc/welcome.html
    
    Runs ploticus -{im_fmt} -o <fname>.{im_fmt} {im_opt} <fname>.ploticus
    Wraps:
    -  'ploticus' -> ploticus

Protocol

    cd ~/installs/git-repos
    git clone https://github.com/luismartingarcia/protocol.git
    python setup install
    https://github.com/luismartingarcia/protocol.git
    
    Runs protocol {im_opt} code-text
    Wraps:
    -  'protocol' -> protocol

PyxPlot

    sudo apt-get install pyxplot
    http://pyxplot.org.uk
    Note:
     - Imagine adds the following lines to the top of the script
        set terminal {im_fmt}
        set output {outfile}
     - that means you cannot use set output in the pyxplot itself.
       There seems no way to convince `set output` to take a variable to
       indicate an output filename.  It'll take anything quite literally..
    
    Runs pyxplot {im_opt} <fname>.pyxplot
    Wraps:
    -  'pyxplot' -> pyxplot

SheBang

    http://www.google.com/search?q=shebang+line
    
    Runs <fname>.shebang {im_opt} <fname>.{im_fmt}
    Wraps:
    -  'shebang' -> shebang