Re: Documentation and explanatory diagrams

On Jul 11, 2010, at 12:33 AM, Rafael Martinez wrote:

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

Inkscape will run on all three platforms. It has an OS X .dmg, windows
installer (and is in the Ubuntu standard repositories, at least).

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

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 importantly, perhaps, if you use a standard file format, rather than
something proprietary, you can edit it with whatever vector editor you like -
import SVG, edit, export SVG.

Choice of fonts to use, such that they'll be available on all the machines
that are used is probably important too. The fonts are not usually
packaged up with the vector format, rather relying on the fonts on the
machine rendering the image. SVG allows use of css-style descriptions
to choose the local font to use.

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

What is the purpose of the PNG files? For things like PDF, vector would
be the better source format.

For html, vector would be a better format to use than PNG (file
size, quality of image, ability to scale) where possible. My understanding
is that it's possible to render basic SVG in the browser natively on
everything but IE and with some javascript or flash assistance on IE.
I'm not sure that is the right way to go today (though it's likely to become
more so as future browser releases, including IE9, clean up their SVG
support).

> 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?

xfig, inkscape and dia are all available on all three platforms (if you count
the cygwin port of xfig, anyway), as are "Draw" from OpenOffice.org, glips
graffiti and probably others.

There are many more apps that are not available on all three platforms,
or aren't freely available, that can edit the same format. We don't require
that everyone use vi to edit text files, just anything that'll edit them in a
way that doesn't break their format for everyone else.

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

I have no dog in this fight, and I'd be overjoyed to see diagrams of
any sort. I do think that requiring use of a single, fairly clunky, graphics
package rather than allowing people who get the urge to create a
diagram to use whichever graphics program they're familiar with is
likely to lead to more, and better, documentation.

Cheers,
Steve