Re: Documentation and explanatory diagrams

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Peter Eisentraut wrote:
> On mån, 2010-04-05 at 16:52 +0200, Rafael Martinez wrote:

>> 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.)
>

Hello

I mentioned Dia because is the one I have experience with and I know it
works with different operative systems. It is not perfect but in my
opinion it is good enough and it does a decent job.

With Dia:

* We have a program that works on Unix, Windows and Mac.
* We can create/update a diagram in an easy way without having to learn
a new complex/powerful system.
* We can save the diagrams in a plain text format that can be check into
CVS.
* We can convert to a variety of target formats with commandline tools.
I have had good experience converting to png and eps.

I have made a quick check of some of your concerns:

* Changing one bit a diagram and saving it, does not produce a
completely different machine-readable-only XML mush. It changes only
the portion of the code affected by your changes. A diff will show
only the lines affected by your changes.

* It looks like the objects in a diagram are saved in the same order
they were created.

* Modified objects keep their position in the saved file.

* The XML format used is human-readable and not so difficult to
understand but it has so much information that it would not be a good
idea to edit it manually. Straightforward changes will not be
difficult to do manually, complex changes have to be done via the
program.

regards,
- --
Rafael Martinez, <r(dot)m(dot)guerrero(at)usit(dot)uio(dot)no>
Center for Information Technology Services
University of Oslo, Norway

PGP Public Key: http://folk.uio.no/rafael/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAku6axAACgkQBhuKQurGihR2YQCeJCE8ZNR3TgP5rkcBYyeZ/9nl
ZfEAn1/HQlw/1IrhY1mGNLRGD9bHzdns
=fXkD
-----END PGP SIGNATURE-----