Re: Documentation and explanatory diagrams

On Sun, 2011-06-12 at 17:44 -0400, Bruce Momjian wrote:
> Thom Brown wrote:
> >
> > Obviously nothing for this happened in time to make it for 9.1. So
> > are diagrams still something we plan to have?
>
> Agreed, we need to move forward with something, and I am afraid we got
> into bike-sheeting on this. Would someone please summarize the previous
> discussion so we can make some decisions and move forward?
>

Hei Bruce

I will try to summarize the previous discusion.

This discusion was about creating explanatory diagrams that could be
used to improve the PostgreSQL documentation.

These are some of the things we would like when creating diagrams:
------------------------------------------------------------------

* A program to create and manipulate diagrams that is easy to use and
can be used on Unix, Windows, or Mac.

* We need a format that is easy to maintain, that can check into VCS
and that will provide tools for automatically converting to a variety of
target formats.

* The requirements to create/convert to a format that can be used in the
documentation must be kept to a minimum.

* We do not want these diagrams to use to much disk space. Compression
is not an alternative.

The discusion started suggesting DIA [1]. This program uses its own XML
representation to define a diagram. More information about what was said
in the begynning about this:
http://archives.postgresql.org/pgsql-docs/2010-04/msg00038.php

The main objections and feedback about using DIA were:
------------------------------------------------------

1) DIA has a terrible UI.

2) dia-format is too verbose and it uses too much space when it is not
compressed.

3) You can't edit the dia-files in any other way than using DIA

4) PNG files generated by DIA are too large.

5) Not sure 100% that a change in a diagram will not affect code
everywhere in the XML representation of the diagram. This will make
difficult to diff between version in a VCS system.

I think the main problems in general were 3) and 5), specially 5)

XFIG and SVG were proposed as an alternative to DIA files. But no
further job was done to properly check these formats.

Good feedback about SVG was done here:
http://archives.postgresql.org/pgsql-docs/2010-07/msg00097.php

It refers among other things to Inkscape [2]. This program generates SVG
diagrams and is not so difficult to use. One of the good things with
Inkscape is that it works with a standard format so we are not bound to
a specific program or non standard format.

And the discussion stopped here.

The main problem I see is that all these formats that can be used to
generate quality diagrams are difficult, if not impossible, to
manipulate outside a WYSWYG program. So probably it will be difficult to
get good diffs between versions of a diagram.

[1] http://live.gnome.org/Dia/
[2] http://inkscape.org/

--
Rafael Martinez Guerrero
Center for Information Technology
University of Oslo, Norway

PGP Public Key: http://folk.uio.no/rafael/