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.m.guerrero@usit.uio.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-----