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

From Tom Lane
Subject Re: Documentation and explanatory diagrams
Date
Msg-id 20026.1278865567@sss.pgh.pa.us
Whole thread Raw
In response to Re: Documentation and explanatory diagrams  (Steve Atkins <steve@blighty.com>)
Responses Re: Documentation and explanatory diagrams  (Steve Atkins <steve@blighty.com>)
List pgsql-docs
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 have no dog in this fight, and I'd be overjoyed to see diagrams of
> any sort.

I'm not backing any specific solution either.  But Rafael's summary
ignores some requirements that I believe are significant.

            regards, tom lane

pgsql-docs by date:

Previous
From: Steve Atkins
Date:
Subject: Re: Documentation and explanatory diagrams
Next
From: Steve Atkins
Date:
Subject: Re: Documentation and explanatory diagrams