Re: Documentation and explanatory diagrams

On mån, 2010-04-05 at 16:52 +0200, Rafael Martinez wrote:
> Tom Lane wrote:
> > Rafael Martinez <r.m.guerrero@usit.uio.no> writes:
> >> I am wondering if we have ever evaluated the use of explanatory diagrams
> >> in the PostgreSQL documentation.
> >
> > There actually used to be some.  We've moved away from them, I believe,
> > because of the difficulty of maintenance; which stems mainly from the
> > lack of any universally-available tools.  Unless you can tell me what
> > you're going to draw the diagram with and how people on Unix, Windows,
> > or Mac could modify it later, I'm going to not be very interested ...

> Well, I was thinking about DIA [1]. It runs on Unix, Windows and Mac.
> It loads and saves diagrams to a custom XML format and it can export
> diagrams to a number of formats, including EPS, SVG, XFIG, WMF and PNG.

Preferably, any tool that we would use would save a reasonably plain
text source file that we could check into VCS and would provide a tool
for automatically converting to a variety of target formats.  For
example, graphviz could work well.  (Not saying that graphviz is the
right tool for producing the kinds of diagrams that you want, but it
provides the right toolchain interfaces.)  Dia might, but it would be
interesting to see how human-readable that XML format really is.  (This
is necessary for change tracking.  I would like to use a diff tool to
see what happened to a diagram over various revisions.  If opening the
file in the editing tool, changing one bit, and saving it produces a
completely different machine-readable-only XML mush, then it's no good.)