SVG in Documentation

Situation before Version 12

Since around 2010 we have seen efforts to enrich the PostgreSQL documentation with graphical elements. Most of the contributors propose to use SVG as the source language for such graphics because it offers many advantages.

• It is standardized (actual 1.1; 2.0 under development) and widely used.
• It is supported by most browsers and many other viewers.
• It renders to devices of different physical sizes - as its name suggests.
• It is available on a wide range of operating systems. But despite of the stand­ardisation the implementations render in many cases to different results for the elaborated features.
• There are many tools that generate SVG in a comfortable way. Those tools implement two different strategies:

• Edit SVG in a WYSIWYG editor (Inkscape, svgedit, LibreOffice Draw, Google Docs Drawing, ...)
• Generate SVG out of another language (Markdeep, Graphviz, ditaa, XFig, AsciiToSvg, blockdiag, ... )

• SVG is integrated into DocBook.

Tests have shown that - after the change from SGML to XML format in version 11 - it is easy to integrate SVG files into the toolchain which generates the PG documentation.

Despite the fact that we focus ourselves on a single language - namely SVG -, we have not come to a consensus about tools to generate it and how to handle it in the long-term. The problems with WYSIWYG editors are:

• The generated SVG is extremely verbose, unreadable, and tool-specific.
• They tend to integrate ‘high level’ SVG features with the result that port­ability suffers.

The generation of SVG out of another language suffers from the fact that those languages are by far not so powerful as SVG. In some cases, they even support only one special use case.

Our requirements in respect to the resulting SVG are:

• short, compact, easy to read
• diff-able
• conforming to SVG 1.1
• restriction to such features, which are portable across most viewers and plat­forms
• homogeneity across all graphics by honoring a style guide (fonts, colors, sizes, ...)

Two Files per Graphic

The current SVG tool zoo consists of a huge bunch of products without a clear favorite in our community. And it’s possible that within the next years new products will overrun the old ones. Our lengthy discussion has shown that it’s likely that we will reach no agreement in a manageable future about one single tool for all our authors. Therefore we avoid a recommendation in favor of one single product. Everybody shall use the tool of his choice – but has to deliver a clean SVG file that meets the above-mentioned requirements, plus the original tool-specific file. The SVG file acts as the source during the generation of our documentation, the tool-specific one as the basis for future modifications of the graphic. Both files reside in the repository under doc/src/sgml/images.

Obviously, such tools, which generate SVG out of another language, have the mentioned two files. Starting with version 12 beta 1 there are two examples in the documentation, one generated with ditaa (https://github.com/stathissideris/ditaa) and the other with Graphvis (https://graphviz.org/).

But also some of the WYSIWYG-editors are able to generate simple SVG out of a 'high level / tool specific' SVG file without losing their powerful ad­ditional features. An example: Inkscape generates by default SVG files in the format Inkscape SVG. In this format, all listed disadvantages occur. But it’s possible to serialize the graphic into a Optimized SVG format (don't confuse it with Inkscape's Plain SVG format). If one parametrizes Inkscape in a certain way, Optimized SVG meets most of our requirements. In this case, elaborated concepts like connectors or groups get lost. But - as previously described - the author has the chance to store both files, the big one in Inkscape SVG format for future work and the small one in Optimized SVG format for the generation of the documentation. The author doesn’t lose any information or feature and the documentation can be generated out of a simple and readable file, which renders in the same way as the big one.

General Hints for SVG Creation in a WYSYWIG editor

• Use grid. This leads to simple integer values for positions.
• Use the same values for viewbox and viewport (=width/height). This helps to understand the plain SVG File. The viewbox may be scaled easily by sub­sequent processes like fop to adopt all sizes in a consistent way.
• The preferred dimensions for measurements are pt. Solely use numbers without fraction (integers). If you use a mixture of pt and em, the size of characters are rendered differently in HTML and PDF.
• All documents shall contain a border (rectangle with rounded corners and a grey background) as a clear separator between the documentation's pure text, its tables, and graphics. Don’t use position 0/0 or a size of 100% for this rectangle because it will lead to invisibility of the right/left and/or top/bottom lines in some rendering systems.

After your work is finished generate the small SVG file which is the source of the PG documentation. Control this file with an XML- or text-editor. It is possible - but not recommended - to do some manual corrections:

• It is good practice to rearrange the SVG elements in accordance with a logical sequence. The sequence created by WYSIWYG tools follows the order in which you had inserted the elements during your interactive work. But be careful: The order determines the z-direction (later elements hide previous elements if they render to the same x/y position).
• Within rect there are sometimes rx="0" or ry="0" attributes to define the radius of a rounded corner. 0 is the default, you can safely remove these attributes.
• Within the style attribute there are sometimes stroke-width:1pt strings. They have no effect because 1pt is the default, you can safely remove them.

Last but not least, verify SVG compatibility, e.g.: validator.w3.org

We have some hints for the use of colors within SVG.

How to Integrate SVG Files into the Documentation

1. Store SVG files within the repository in the directory doc/src/sgml/images.
2. Refer to SVG files from the traditional SGML (xml) files:

 <para>
  <figure id="gin-internals-figure">
   <title>GIN Internals</title>
   <indexterm><primary>... some text ...</primary></indexterm>
   <mediaobject>
    <imageobject>
     <imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
    </imageobject>
    <!--  or:
    <imageobject role="html">
     <imagedata fileref="images/gin.svg" format="SVG" align="center"/>
    </imageobject>
    <imageobject role="fo">
     <imagedata fileref="images/gin.svg" format="SVG"  scale="70"/>
    </imageobject>
    -->
   </mediaobject>
  </figure>
 </para>

In role="html" mode Docbook renders the graphic as a block (newline before and after) or inline (the following text surrounds the graphic at the 'free' side) depending on the attribute align of element imagedata. If you use no alignment (which leads to left-alignment) or align="center" the graphic is shown as a block, other values lead to inline rendering.

Huge graphics shall be centered if there is text in front of and behind it. If a table precedes or follows, the graphic shall be left centered in the same way as the table.

Known problems

• Man pages are created out of the files in the sgml/ref/ directory. If such a file contains an SVG graphic, the generated man page looks a little ugly. Please avoid this situation and include SVGs only into files of the sgml/ directory.