SVG in Documentation

From PostgreSQL wiki

Jump to: navigation, search

This document has a preliminary status because the described proceeding is only a plan. During the realization phase we expect to see some modifications and supplements. If you have comments concerning the concept, send it to: pgsql-docs@lists.postgresql.org, minor issues are discussed - as usual - at the discussion page.

Contents

Situation up to 2018

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 this process evolves.
  • 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 may cases to different results for elaborated features.
  • There are many tools which generate SVG in a comfortable way - within a WYSIWYG editor (Inkscape, svgedit, LibreOffice Draw, Google Docs Drawing, ...) or out of another language (Markdeep, DOT + Grafviz, 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 tool chain which generates the PG documentation.

Despite the fact that we focus ourselves on a single language, 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 honouring a style guide (fonts, colors, sizes, ...)

Planned Proceeding: Two Files per Graphic

The actual SVG tool zoo consists of a huge bunch of products without a clear favourite 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 favour of a certain product. Everybody shall use the tool of his choice – but has to deliver a clean SVG file which meets the above mentioned requirements. It’s our responsibility to describe and install methods which guarantees that all those requirements are meet. The tools theirselves as well as their proprietary representation of the graphical objects are out of the scope of our community. We focus ourselves to the pure SVG.

Fortunately, some of the tools are able to generate simple SVG without loosing their powerful ad­ditional features.

An example: Inkscape generates by default SVG files in the format Inkscape SVG. In this format all listed disadvantages occurs. But it’s possible to serialize the graphic into a Optimized SVG format. If one parametrises Inkscape in a certain way (see below), Optimized SVG meets most of our requirements. In this case elaborated concepts like connectors or groups get lost. But the author has the chance to store two files, a big one in Inkscape SVG for his further work and a small one in Optimized SVG format for the community. The author doesn’t loose any information or feature and the community gets a working SVG file which renders in the same way as the big one.

This small SVG file becomes part of our documentation’s source, optionally the big one is also stored somewhere in our repository. The small one is authoritative for all further actions like generating documentation, git, diff, further editing with any other tool. If - at a later stage - someone uses the same tool as the original author for a modi­fication of the graphic, he may start with the big file. But only the then generated new small one is used within our system.

General Hints for SVG Creation

  • 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 px. Solely use numbers without fraction (integers). If you use a mixture of px 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 graphic. 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 will become part of the PG documentation. Control this file with an XML- or text-editor. Maybe, you want to do some corrections:

  • It is good practise to rearrange the SVG elements in accordance to 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:1px strings. They have no effect because 1px 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.

Special Hints

Build SVG Graphics using Inkscape

Build SVG Graphics using svgedit (ToDo)

Build SVG Graphics using LibreOffice Draw (ToDo)

Build SVG Graphics using Xfig (ToDo)

How to Integrate SVG Files into the Documentation

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

 <para>
  <figure id="page-layout-figure">
   <title>Overall Page Layout</title>
   <indexterm><primary>Page Layout (Figure)</primary></indexterm>
   <mediaobject id="PageLayoutSVG">
    <imageobject role="html">
     <imagedata fileref="svg/pagelayout.svg" format="SVG" align="center" />
    </imageobject>
    <imageobject role="fo">
     <imagedata fileref="svg/pagelayout.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/ subdirectory. If such a file contains a SVG graphic, the generated man page looks a little ugly. Please avoid this situation and include SVGs only into files of the sgml/ directory.
Personal tools