From: Steve Atkins <steve@blighty.com>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\))
Subject: Re: Images in the official documentation
Date: Sun, 25 Feb 2018 19:18:50 -0800
References: <1914747379.117313.1519402446241.JavaMail.zimbra@dbi-services.com>
 <ff69cb83-9f90-4967-7de7-629bdfaa0c75@purtz.de>
 <08B83F11-EB17-4436-B73A-1857898B6B9B@blighty.com>
 <CAMsr+YEfh3qgxDeyAThi-nv0k3ptxhOZKW44kKzcaspGnWzC2A@mail.gmail.com>
To: pgsql-docs@lists.postgresql.org
In-Reply-To: 
 <CAMsr+YEfh3qgxDeyAThi-nv0k3ptxhOZKW44kKzcaspGnWzC2A@mail.gmail.com>
Message-Id: <1AF29ABD-1A12-4AB5-956A-4C9AD35F155D@blighty.com>
Precedence: bulk


> On Feb 25, 2018, at 6:45 PM, Craig Ringer <craig@2ndquadrant.com> =
wrote:
>=20
> On 26 February 2018 at 04:12, Steve Atkins <steve@blighty.com> wrote:
>=20
> Writing SVG by hand maybe doesn't seem the best idea.
>=20
> 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.
>=20
>=20
>=20
> 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.=20

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