Sender: Pavel Golub <pavel.golub@gf.microolap.com>
From: Pavel Golub <pavel@microolap.com>
Date: Thu, 19 Jul 2018 15:06:08 +0300
Reply-To: Pavel Golub <pavel@gf.microolap.com>
Organization: Microolap
Message-ID: <1554502154.20180719150608@gf.microolap.com>
To: =?utf-8?Q?J=C3=BCrgen_Purtz?= <juergen@purtz.de>,
 pgsql-docs@lists.postgresql.org
Subject: Re: Images in the official documentation
In-Reply-To: <4ea1bacb-02ca-e967-31d7-d2a6db30abff@purtz.de>
References: <20180227151914.2xtoygrwlm357fqo@alvherre.pgsql>
 <4ea1bacb-02ca-e967-31d7-d2a6db30abff@purtz.de>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Precedence: bulk

Hello, Jürgen.

You wrote:

JP> Our discussion about grafics in the documentation reached to the 
JP> conclusion that we shall use SVG, the importance to 'diff-ability'
JP> is rated differently, and there is no consensus about tools.

I disagree. From what I heard, GraphViz is the winner for now. I can
give you my two cents: plantuml is another good choice

JP> To push the issue forward I modify my original proposal to use   
JP> plain svg files in a standard editor as follows:


JP>   We define a 'Simplified SVG format' (SSVG)  We create libraries
JP> where complex elements are predefined and         can be
JP> referenced  We write the source in ssvg-format  A compiler
JP> (written in bison or xslt) converts ssvg-files to        
JP> svg-files  We extend the sgml-files to include the svg-files  The
JP> ssvg and svg-files are located in a new svg directory,        
JP> Makefile copies them to sgml and html directory  A
JP> proof-of-concept is performed in 11beta2 for HTML and PDF        
JP> generation.  The ssvg-format may be XML (as used in the examples),
JP> JSON,         C-style function calls   
JP>   

JP>        PRO:
JP>   
JP>   
JP>   SVG 1.x has many restrictions and SVG 2.x does not make        
JP> progress in the last years. Tools and Browsers support different  
JP> ranges of the specification. The planned compiler cuts        
JP> everything down to the basic language level, where a broad        
JP> support is possible.  Predefinded elements and default values
JP> reduce the ssvg file         to a small and clear source file. 
JP> You can embed original svg commands into ssvg files.  When you use
JP> an editor and a browser in parallel, you get the         visual
JP> result with few clicks.  Everything is diff-able.  The Makefile
JP> needs only slightly amendments: additional cp         commands and
JP> some target-dependencies. We need no new tool.  
JP>   
JP> CON:
JP>   
JP>   
JP>   The development is done in a non-wysiwyg editor and without    
JP> mouse.  You have to count pixel.  
JP>   

JP>        Example:
JP>        PageLayout.ssvg: written in the new language
JP>        PageLayout.svg: the generated svg file (actually by hand,
JP> the       compiler is not yet implemented)
JP>        storage.sgml: an additional paragraph to refer to the svg-file
JP>   
JP>        <para>
JP>          <mediaobject id="PageLayoutSVG">
JP>            <imageobject role="html">
JP>              <imagedata fileref="PageLayout.svg" format="SVG"/>
JP>            </imageobject>
JP>            <imageobject role="fo">
JP>              <imagedata fileref="PageLayout.svg" format="SVG"    
JP> scalefit="1" width="100%" contentdepth="100%"/>
JP>            </imageobject>
JP>          </mediaobject>
JP>        </para>
JP>   
JP>        PageLayoutHtml.png: the HTML result
JP>        PageLayoutPdf.png: the PDF result
JP>   
JP>        A second example: pgDump.svg within backup.sgml
JP>   
JP>   
JP>        Kind regards, Jürgen Purtz
JP>   
JP>   

JP>   
JP>   


-- 
With best wishes,
 Pavel                          mailto:pavel@gf.microolap.com