Re: Images in the official documentation

> On Feb 25, 2018, at 6:45 PM, Craig Ringer <craig@2ndquadrant.com> wrote:
>
> On 26 February 2018 at 04:12, Steve Atkins <steve@blighty.com> wrote:
>
> Writing SVG by hand maybe doesn't seem the best idea.
>
> I understand the attraction to people who want to store everything as diffable text, but images of this sort are
unlikelyto get updated by others, which means they're unlikely to be maintained as the things they're intended to
documentchange. It also means that the people best suited to generating diagrams are the least likely to do so, and
vice-versa.
>
>
>
> Yeah, I think it'd just effectively preserve the status quo by rendering anyone who's willing to add images and
designsto the docs unable - or unlikely to be willing - to do so.  

Yup. I do think that graphics would be nice in a few places, and that SVG is likely the best format for them.

There are quite a few tools that could be integrated with varying amounts of effort into the documentation generation
workflow.


# ASCII language or ascii art to SVG

# asciitosvg

https://github.com/dhobsd/asciitosvg

Inspired by ditaa, similar in functionality

## blockdiag, seqdiag, actdiag, nwdiag

http://blockdiag.com

Generates various box and arrow diagrams from a DOT-ish input language.

## ditaa

It takes ascii art of box and arrow diagrams and turns them into nice svg. Also supports boxes that look like "storage"
cylinders,documents, clouds and computers. 

## erd

https://github.com/BurntSushi/erd

Entity relationship diagrams, from a plain text input. Uses DOT and graphviz under the covers.

## Markdeep

http://casual-effects.com/markdeep/

In-browser javascript rendering of ascii art, particularly boxes and arrows.

Alternate implementation, https://github.com/blampe/goat, converts to SVG via CLI.

## Mermaid

Flowcharts and sequence diagrams from a markdown-esque input.

## mscgen

Message sequence chart inputs in a DOT-ish language to SVG

## plantuml

http://plantuml.com

It supports a human-editable descriptive text input language and generates from it:

  sequence diagrams
  various box + arrow style diagrams
  flowcharts
  state diagrams
  etc.


## shaape

https://github.com/christiangoltz/shaape

Converts ascii art to SVG. Rather nice.

## svgbob

https://github.com/ivanceras/svgbobrus

Ascii art to SVG. Likely good for boxes and arrows.

## syntrax

https://kevinpt.github.io/syntrax/

Railroad diagrams (like the ones SQLite docs are known for).

## umlet

http://www.umlet.com

Pointy-clicky editor, but also converts plain text to uml, sequence, activity diagrams

# Interactive editor

## SVG-Edit

https://github.com/SVG-Edit/svgedit

Open source, browser based interactive SVG editor. Seems to generate fairly clean SVG.

Cheers,
  Steve