> On Feb 25, 2018, at 6:45 PM, Craig Ringer <cr...@2ndquadrant.com> wrote: > > On 26 February 2018 at 04:12, Steve Atkins <st...@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 unlikely to get updated by others, > which means they're unlikely to be maintained as the things they're intended > to document change. 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 designs to 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
