https://github.com/hertogp/imagine

A pandoc-filter for images
https://github.com/hertogp/imagine

Last synced: 15 days ago
JSON representation

A pandoc-filter for images

• Host: GitHub
• URL: https://github.com/hertogp/imagine
• Owner: hertogp
• License: mit
• Created: 2017-04-17T10:59:05.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2021-05-03T14:55:49.000Z (over 3 years ago)
• Last Synced: 2024-08-31T04:56:09.907Z (2 months ago)
• Language: Python
• Size: 17.4 MB
• Stars: 81
• Watchers: 6
• Forks: 11
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGES
  • License: LICENSE

Awesome Lists containing this project

• stars - hertogp/imagine - filter for images (HarmonyOS / Windows Manager)

README

        
``` 

                                          \\\///

                                         / _  _ \

                                       (| (.)(.) |)

                .--------------------.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](http://www.mcternan.me.uk/mscgen/)

![](https://raw.githubusercontent.com/hertogp/imagine/master/pd-images/3472ea8b47f0b7d2d2f30565851e320f39b5e3a9.png)

    ```{.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](https://github.com/mermaidjs/mermaid.cli)

![](https://raw.githubusercontent.com/hertogp/imagine/master/pd-images/cc321a3330d39327fcaffac5dc39397e6166edc7.png)

    ```{.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
long time, so long
that the text does
not fit on a row.

    

        Bob-->Alice: Checking with John...

        Alice->John: Yes... John, how are you?

    ```

### [Gnuplot](http://www.gnuplot.info)

![](https://raw.githubusercontent.com/hertogp/imagine/master/pd-images/5f64cf6a4cf0b4b737fd2d07f0e3cc035475aca6.png)

    ```{.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](http://www.google.com/search?q=linux+shebang) using Python & Pygal

![](https://raw.githubusercontent.com/hertogp/imagine/master/pd-images/4d647b61c07fe8c3935def2b57796c0780ff38bd.png)

    ```{.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](http://boxes.thomasjensen.com)

    /*       _\|/_

             (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](https://github.com/hertogp/imagine/tree/master/examples), 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 .{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 .{im_fmt} {im_opt} .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} .{im_fmt} -o .{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} .boxes

    Wraps:

    -  'boxes' -> boxes

Ctioga2

    sudo apt-get install ctioga2

    http://ctioga2.sourceforge.net

    

    Runs ctioga2 {im_opt} -f .ctioga2

    Wraps:

    -  'ctioga2' -> ctioga2

Ditaa

    sudo apt-get install ditaa

    http://ditaa.sourceforge.net

    

    Runs ditaa .ditaa .{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 .{im_fmt} .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} .gnuplot > .{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} .graph

    Wraps:

    -  'graph' -> graph

Graphviz

    sudo apt-get install graphviz

    http://graphviz.org

    

    Runs {im_prg} {im_opt} -T{im_fmt} .{im_prg} .{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 .ps in current working directory

    - requires `convert` from imagemagick

    - ImageMagick's security policy might need massaging

    

    Runs gri {im_opt} -c 0 -b .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 .mermaid -o . {im_opt}

    Wraps:

    -  'mermaid' -> mmdc

MscGen

    sudo apt-get install mscgen

    http://www.mcternan.me.uk/mscgen

    

    Runs mscgen -T {im_fmt} -o .{im_fmt} .mscgen

    Wraps:

    -  'mscgen' -> mscgen

Octave

    sudo apt-get install octave

    https://www.gnu.org/software/octave

    

    Runs octage --no-gui -q {im_opt} .octave .{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} .pic2plot

    Wraps:

    -  'pic2plot' -> pic2plot

    -  'pic' -> pic2plot

PlantUml

    sudo apt-get install plantuml

    http://plantuml.com

    

    Runs plantuml -t{im_fmt} .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} 

    Wraps:

    -  'plot' -> plot

Ploticus

    sudo apt-get install ploticus

    http://ploticus.sourceforge.net/doc/welcome.html

    

    Runs ploticus -{im_fmt} -o .{im_fmt} {im_opt} .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

    

    Runs pyxplot {im_opt} .pyxplot

    Wraps:

    -  'pyxplot' -> pyxplot

SheBang

    http://www.google.com/search?q=shebang+line

    

    Runs .shebang {im_opt} .{im_fmt}

    Wraps:

    -  'shebang' -> shebang

```