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

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

Bruce Momjian wrote:

>
> Where are we on this?  Application?  dia? xfig?  Number of colors?  Once
> we decide these items, we can start adding diagrams.
>

This is an attempt to summarize the current status and what have been
said/done about the subject.

After the first proposal of using DIA to create diagrams, some tests,
several diagrams and a patch of the documentation has been sent to the
list as a proof of concept. DIA was chosen because it initially met the
requirements proposed by list members.


* Requirements
- ---------------

1) We need a program to create and manipulate diagrams that is easy to
use and can be used on Unix, Windows, or Mac.

2) We need a format that is easy to maintain, that can check into VCS
and that will provide tools for automatically converting to a variety of
target formats.


* Main objections and feedback
- -------------------------------

1) DIA has a terrible UI.

2) dia-format is too verbose and it uses too much space when it is not
compressed.

3) You can't edit the dia-files in any other way than using DIA

4) PNG files generated by DIA are too large.

5) Two ways of getting the PNG files in the documentation: shipping them
vs. generating them in the build process.

6) xfig and SVG have been proposed as an alternative to dia files.


This is the status as per today. Below I will argue for and against
these objections and feedback and I hope this will help to take a final
decision:

1) DIA is not perfect and it could be better. That said, it is easy to
install, it does run on Unix, Windows, or Mac, it is easy to learn and
the end results are potentially professional. As far as I know it is the
only program that has all these features.

2) When compressed with gzip, we can get over 90% reduction in size.

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.

4) True. By default PNG files generated with DIA have these attributtes:
Colorspace: RGB / Depth: 8-bit / Type: Truecolor. The 'Truecolor'
attributte is not necessary in explanatory diagrams and it is the reason
of the extra size.

PNG files generated with DIA could be converted with ImageMagick. We can
get between 50% and 75% reduction in size with ImageMagick if we want.
That said, I do not think the documentation will have more than maybe
30-40 diagrams. 40 diagrams using the same amount of space as the
examples sent to the list will use around 1.5MB. I really cannot see how
this can be a problem in 2010 and I would not even bother to reduce the
size if I had to decide this.

5) This is the big question. Personally, I think that generating the PNG
files in the build process is a more elegant solution. The
infrastructure needed for this is easy to install and you have RPM and
DEB packages to do this if you don't want to compile the source. The few
people who build the documentation themself should not have a problem
installing the extra program needed for this.

That said, I do not have a problem neither with shipping the files.

6) Do we have programs to work with these formats on Unix, Windows and
Mac? Are they easy to use and learn? What are the software requirements
needed to generate other formats?

Well, I hope this summary will help us to take the final decision about
 the program/format/infrastructure to use, so we can begin working on
the diagrams we are going to include and the contents of them.

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

iEYEARECAAYFAkw5c8EACgkQBhuKQurGihTjFACeLA77cj51zhoX57mRH6hsJHMP
jH0An2CKPmmqaK0CzdDa5ioGX5YJthTy
=vzmm
-----END PGP SIGNATURE-----