public inbox for [email protected]  

help / color / mirror / Atom feed

From: Steve Atkins <[email protected]>
To: [email protected]
Subject: Re: Images in the official documentation
Date: Sun, 25 Feb 2018 19:18:50 -0800
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAMsr+YEfh3qgxDeyAThi-nv0k3ptxhOZKW44kKzcaspGnWzC2A@mail.gmail.com>
References: <[email protected]>
	<[email protected]>
	<[email protected]>
	<CAMsr+YEfh3qgxDeyAThi-nv0k3ptxhOZKW44kKzcaspGnWzC2A@mail.gmail.com>


> On Feb 25, 2018, at 6:45 PM, Craig Ringer <[email protected]> wrote:
> 
> On 26 February 2018 at 04:12, Steve Atkins <[email protected]> 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

view thread (23+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: Images in the official documentation
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox