Re: Images in the official documentation

[Craig Ringer]

On 26 February 2018 at 12:16, Tom Lane  wrote:

> Craig Ringer  writes:
> > 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.
>
> This is an entirely reasonable complaint.  But I don't see how we'd cope
> with patches that rewrite an entire SVG file because the patch author's
> WYSIWG editor emits its output in a style randomly different from the tool
> the previous patch author used.  It seems like such patches would be
> effectively unreviewable, and certainly incapable of being merged.
>

Well, they definitely couldn't be merged in any situation entailing
conflicts, no.

Patch review would entail displaying the new and (if present) old SVGs,
possibly in the context of a build of the docs, or possibly standalone.

This is always going to be the case for anything but the most trivial SVG
changes anyway. After all, even small textual changes can cause elements to
overlap, break out of their expected bounaries, or otherwise look wrong.

So IMO whether it's SVG or a raster image format, the net effect isn't that
different: you have to review the rendered result not the source.
Personally I'd just mark svg as binary in .gitattributes to stop it from
spamming noise in diffs.

Github offers a cool tool for side-by-side compares of svg diffs (
https://github.com/blog/1902-svg-viewing-diffing) but that likely won't
help us much.

There's diffsvg (https://github.com/jrsmith3/diffsvg), which I haven't
tried but looks interesting. Combined with filters in .gitattributes this
might offer improved visibility into change history if we really need it.

Personally, I don't think images will be changing that often and they
should just be tracked as blobs.



> Maybe we could improve matters a bit by insisting that everyone use the
> same version of the same SVG-editing tool.  But that's not too practical.
> Worse, from what I've seen, even that would not really fix the problem.
> The tools simply don't give a damn about comparability of their dump
> files.  I don't blame their authors exactly (try diffing Postgres data
> file changes :-() but that doesn't mean it isn't a problem for us.
>
> How can we resolve these issues?
>

Question the assumptions and requirements. Why do we actually _need_
diffable, mergeable images? Sure, it'd be *nice*, but what's the real world
impact if we don't have it?

-- 
 Craig Ringer   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services

Re: Images in the official documentation

[Tom Lane]

Craig Ringer  writes:
> On 26 February 2018 at 04:12, Steve Atkins  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.

This is an entirely reasonable complaint.  But I don't see how we'd cope
with patches that rewrite an entire SVG file because the patch author's
WYSIWG editor emits its output in a style randomly different from the tool
the previous patch author used.  It seems like such patches would be
effectively unreviewable, and certainly incapable of being merged.

Maybe we could improve matters a bit by insisting that everyone use the
same version of the same SVG-editing tool.  But that's not too practical.
Worse, from what I've seen, even that would not really fix the problem.
The tools simply don't give a damn about comparability of their dump
files.  I don't blame their authors exactly (try diffing Postgres data
file changes :-() but that doesn't mean it isn't a problem for us.

How can we resolve these issues?

regards, tom lane

Re: Images in the official documentation

[Steve Atkins]

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

Re: Images in the official documentation

[Craig Ringer]

On 26 February 2018 at 04:12, Steve Atkins  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.



-- 
 Craig Ringer   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services

Re: Images in the official documentation

[Steve Atkins]

> On Feb 25, 2018, at 4:00 AM, Jürgen Purtz  wrote:
> 
> As an addition to my mail from January 2016 concerning graphics 
> (https://www.postgresql.org/message-id/568A9148.30303%40purtz.de) I propose 
> to use SVG (after switching to XML) - but not an SVG which is generated by 
> Inkscape or similar tools. Those editors generate very ugly and chatty 
> commands. This form is not easy to read or understand. Therefore we shall use 
> nothing but a simple text editor and write every line by our self. The 
> process is divided into two parts:
> As a basis we shall develop an SVG library containing a bunch of "atomic" 
> symbols of simple graphical elements (rectangle, arrow, ...) up to complex 
> elements (magnetic disc, laptop, cloud, UML-elements, ...). The SVG routines 
> creating those symbols shall accept parameters for position, size, rotation, 
> colour, ... . This library shortens the individual SVG files, it ensures a 
> consistent rendering of common graphical elements, it is diff-able, and it 
> will reach a stable state - some day.
> 
> The real graphics shall use the elements of the library and add individual 
> SVG elements. The rules for this part are the same as above: create SVG 
> commands with vi (or similar), store it in git.
> If such an approach works (we must distribute the docs across a wide range of 
> different systems, a proof-of-system is necessary) and the community accepts 
> my proposal, I would like to work on the library-part - starting after 
> finishing my actual project in about 6 weeks from now. The attached file 
> contains a very first draft as of Jan. 2016.

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.

Cheers,
  Steve

Re: Images in the official documentation

[Jürgen Purtz]

As an addition to my mail from January 2016 concerning graphics 
(https://www.postgresql.org/message-id/568A9148.30303%40purtz.de) I 
propose to use SVG (after switching to XML) - but not an SVG which is 
generated by Inkscape or similar tools. Those editors generate very ugly 
and chatty commands. This form is not easy to read or understand. 
Therefore we shall use nothing but a simple text editor and write every 
line by our self. The process is divided into two parts:


As a basis we shall develop an SVG library containing a bunch of 
"atomic" symbols of simple graphical elements (rectangle, arrow, ...) up 
to complex elements (magnetic disc, laptop, cloud, UML-elements, ...). 
The SVG routines creating those symbols shall accept parameters for 
position, size, rotation, colour, ... . This library shortens the 
individual SVG files, it ensures a consistent rendering of common 
graphical elements, it is diff-able, and it will reach a stable state - 
some day.


The real graphics shall use the elements of the library and add 
individual SVG elements. The rules for this part are the same as above: 
create SVG commands with vi (or similar), store it in git.


If such an approach works (we must distribute the docs across a wide 
range of different systems, a proof-of-system is necessary) and the 
community accepts my proposal, I would like to work on the library-part 
- starting after finishing my actual project in about 6 weeks from now. 
The attached file contains a very first draft as of Jan. 2016.


Kind regards
Jürgen Purtz



On 23.02.2018 22:14, Daniel Westermann wrote:

Hi %,

I am working with PostgreSQL documentation quite a few years now and I 
am almost happy. What I think is completely missing (especially if you 
compare to commercial product documentation) are pictures that 
illustrate a topic, e.g. the relation of 
instance->database->user/role->schema->objects.


Is there an agreement not to include that pictures for any reason? I 
can not promise that I find time for that in the near future but if 
that will be appreciated I am willing to spend time on that to make 
the documentation even better.


Regards
Daniel