Re: Documentation and explanatory diagrams - Mailing list pgsql-docs

From Steve Atkins
Subject Re: Documentation and explanatory diagrams
Date
Msg-id 33D0C13B-2F3E-457B-9876-E6A085D9FF77@blighty.com
Whole thread Raw
In response to Re: Documentation and explanatory diagrams  (Tom Lane <tgl@sss.pgh.pa.us>)
List pgsql-docs
On Jul 11, 2010, at 9:26 AM, Tom Lane wrote:

> Steve Atkins <steve@blighty.com> writes:
>> On Jul 11, 2010, at 12:33 AM, Rafael Martinez wrote:
>> [ assorted arguments for and against DIA ]
>
>>> 2) dia-format is too verbose and it uses too much space when it is not
>>> compressed. [vs]
>>> 2) When compressed with gzip, we can get over 90% reduction in size.
>
>>> 3) You can't edit the dia-files in any other way than using DIA [vs]
>>> 3) I cannot see the problem with this. This will be the same with any
>>> other format. Editing a xfig or svg file manually via a text editor is
>>> as tiresome and counterproductive as doing it with a dia file.
>
>> You wouldn't edit any three of those file types in a text editor any more than
>> you'd edit a PNG with a hex editor (i.e. it's possible, and sometimes
>> useful, but not part of your workflow).
>
> More to the point here is that we want to be able to store the diagram
> source files in an SCM (CVS, soon to be git), and one of the main
> reasons for wanting to do that is so that people can see exactly what
> was changed between revision A and revision B.  If the data format isn't
> amenable to diff'ing then that is a big strike against it.  For this
> reason, the proposal to gzip the files is Absolutely Right Out; and even
> for text-based formats the readability of the files *is* a concern,
> whether or not you'd be likely to try to edit them without a diagram
> editor.

I suspect that any format that's intended to be edited in a GUI editor
is not likely to diff well. Some formats will be better than others, and
some GUI editors will be better than others, but we're never going
to be able to diff -c an image that has been edited as an image in
the same way we can a text file.

A clean, text or xml based format is likely to be the most diffable,
but it's all a bit speculative without trying it and seeing.

Maybe I'll grab a copy of dia and see how things compare this
afternoon.

Cheers,
  Steve


pgsql-docs by date:

Previous
From: Tom Lane
Date:
Subject: Re: Documentation and explanatory diagrams
Next
From: Bruce Momjian
Date:
Subject: Re: release-9.0.sgml changes