Re: Graphic to visualize data flow between processes, buffers and files

There have been discussions about how to incorporate graphics, which
have failed to come to any consensus.  Nobody is particularly willing
to put a badly-formatted batch of raw numbers into git though, because
it'd be impossible to do any incremental updates on it and still have
useful git history.  There are also a bunch of questions about whether
the graphics would work in all the output formats we try to support.

This particular example doesn't really seem compelling enough to
justify finding a way over those hurdles ...

In 2010/11 we had a discussion about SVG editors and SVG cleaner tools: http://www.postgresql.org/message-id/flat/201006302218.o5UMI7Y20379@momjian.us#201006302218.o5UMI7Y20379@momjian.us. 5 years later we should take a second chance to bring graphics to the documentation.

After some research I propose a collection of rules and hope that they will fulfill our needs. Please proof and extend the below-mentioned steps to a useful cookbook.


Principles:

• Use the tool (text editor, xml-editor, svg-editor) and SVG-cleaner of your choice.
• Produce pure standard compliant (xmlns:svg="http://www.w3.org/2000/svg") SVG text files without any additional XML-namespace.

Recommendations:

• We suggest the use of Inkscape. It creates the above mentioned format by performing the following steps
  • File | Clean up document
  • File | Save as | Plain SVG
    
• If you insist to use complex objects like connectors we suggest the use of Inkscape's SVG format for your working file and the two steps mentioned above to create the destination file. In the destination file complex objects are fragmented into simple objects but they are rendered in the same way as before.
  
• You can copy complex objects like UML shapes from any SVG tool to Inkscape by performing the following steps
  
  • Create the object with the tool of your choice in an temporary file
    
  • Export the graphic to SVG or Plain SVG format
    
  • Open this SVG file in Inkscape
  • Copy / Past the object to your working file
  • If necessary group the fragments of the new object to one object
• Although other SVG editors support 'Plain SVG' format via their export-command as well as Inkscape, the results of Inkscape's approach seams to be nearly optimal.
• Nevertheless Inkscape's output in 'Plain SVG' format is not optimal. There are some superfluous objects which can be ignored or removed with a text editor:
  • Within <metadata> the descriptions use the namespaces rdf, cc and dc instead of svg's elements.
    
  • Within the style attribute sometimes there are '-inkscape-font-specification' instructions. They are redundant as they have the same contents as the also present and standard conform font-style instructions (Inkscape bug?).
  • Some objects imported from other SVN tools fills the attribute 'class' with values like "com.sun.star.drawing.xxx". Test such objects and/or remove the values.
• Don't use "Objects | Symbols" as it creates an additional namespace 'xlink'.
  
• If you create a PNG file (File | Export PNG Image), you should previously set the background color of the image (File | Document Properties) to RGB ffffffff or any color of your choice. Otherwise some PNG viewer shows an odd background.

Advantages:

• Files in plain SVG format are text files and therefore diff-able. As they are also XML-files, it is a good idea to use an xml-diff tool (better granularity, ignoring of newlines and other white spaces, ignoring the different syntax for empty tags, ignoring xml-attribute sequence, ...).
• As fare as I have seen the plain SVG as well as the PNG leads to identical rendering in different viewers.
• Inkscape is able to produce PDF files out of its plain SVG files - as well as a lot of other tools.
  
• Inkscape offers a window where you can control (and partly modify) the xml representation of an object.
  

Disadvantages:

• There is no guaranty that the resulting plain SVG file will be rendered by every other SVG tool in the same way as it is done in Inkscape. In my opinion this is a failure of SVG tools - they have a different understanding of some SVG elements. Hopefully SVG 2 will bring some progress (in the far future).
  
• The proceeding is very time consumptive in comparison to the use of the sophisticated features of a single product.

Regards, Jürgen Purtz