From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Subject: Re: Images in the official documentation
To: pgsql-docs@lists.postgresql.org
References: <1914747379.117313.1519402446241.JavaMail.zimbra@dbi-services.com>
Message-ID: <ff69cb83-9f90-4967-7de7-629bdfaa0c75@purtz.de>
Date: Sun, 25 Feb 2018 18:00:30 +0600
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.6.0
MIME-Version: 1.0
In-Reply-To: 
 <1914747379.117313.1519402446241.JavaMail.zimbra@dbi-services.com>
Content-Type: multipart/mixed;
 boundary="------------114CCCA48262D369C770884E"
Content-Language: en-GB
Precedence: bulk

This is a multi-part message in MIME format.
--------------114CCCA48262D369C770884E
Content-Type: multipart/alternative;
 boundary="------------8F8DF816E96B1CB80B05E37B"


--------------8F8DF816E96B1CB80B05E37B
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit

As an addition to my mail from January 2016 concerning graphics 
(https://www.postgresql.org/message-id/568A9148.30303%40purtz.de) I 
propose to use SVG (after switching to XML) - but not an SVG which is 
generated by Inkscape or similar tools. Those editors generate very ugly 
and chatty commands. This form is not easy to read or understand. 
Therefore we shall use nothing but a simple text editor and write every 
line by our self. The process is divided into two parts:

As a basis we shall develop an SVG library containing a bunch of 
"atomic" symbols of simple graphical elements (rectangle, arrow, ...) up 
to complex elements (magnetic disc, laptop, cloud, UML-elements, ...). 
The SVG routines creating those symbols shall accept parameters for 
position, size, rotation, colour, ... . This library shortens the 
individual SVG files, it ensures a consistent rendering of common 
graphical elements, it is diff-able, and it will reach a stable state - 
some day.

The real graphics shall use the elements of the library and add 
individual SVG elements. The rules for this part are the same as above: 
create SVG commands with vi (or similar), store it in git.

If such an approach works (we must distribute the docs across a wide 
range of different systems, a proof-of-system is necessary) and the 
community accepts my proposal, I would like to work on the library-part 
- starting after finishing my actual project in about 6 weeks from now. 
The attached file contains a very first draft as of Jan. 2016.

Kind regards
Jürgen Purtz


On 23.02.2018 22:14, Daniel Westermann wrote:
> Hi %,
>
> I am working with PostgreSQL documentation quite a few years now and I 
> am almost happy. What I think is completely missing (especially if you 
> compare to commercial product documentation) are pictures that 
> illustrate a topic, e.g. the relation of 
> instance->database->user/role->schema->objects.
>
> Is there an agreement not to include that pictures for any reason? I 
> can not promise that I find time for that in the near future but if 
> that will be appreciated I am willing to spend time on that to make 
> the documentation even better.
>
> Regards
> Daniel


--------------8F8DF816E96B1CB80B05E37B
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <p>As an addition to my mail from January 2016 concerning graphics
      (<a class="moz-txt-link-freetext" href="https://www.postgresql.org/message-id/568A9148.30303%40purtz.de">https://www.postgresql.org/message-id/568A9148.30303%40purtz.de</a>)
      I propose to use SVG (after switching to XML) - but not an SVG
      which is generated by Inkscape or similar tools. Those editors
      generate very ugly and chatty commands. This form is not easy to
      read or understand. Therefore we shall use nothing but a simple
      text editor and write every line by our self. The process is
      divided into two parts:<br>
    </p>
    <p>As a basis we shall develop an SVG library containing a bunch of
      "atomic" symbols of simple graphical elements (rectangle, arrow,
      ...) up to complex elements (magnetic disc, laptop, cloud,
      UML-elements, ...). The SVG routines creating those symbols shall
      accept parameters for position, size, rotation, colour, ... . This
      library shortens the individual SVG files, it ensures a consistent
      rendering of common graphical elements, it is diff-able, and it
      will reach a stable state - some day. </p>
    <p>The real graphics shall use the elements of the library and add
      individual SVG elements. The rules for this part are the same as
      above: create SVG commands with vi (or similar), store it in git.<br>
    </p>
    If such an approach works (we must distribute the docs across a wide
    range of different systems, a proof-of-system is necessary) and the
    community accepts my proposal, I would like to work on the
    library-part - starting after finishing my actual project in about 6
    weeks from now. The attached file contains a very first draft as of
    Jan. 2016.<br>
    <br>
    Kind regards<br>
    Jürgen Purtz<br>
    <br>
    <br>
    <br>
    <div class="moz-cite-prefix">On 23.02.2018 22:14, Daniel Westermann
      wrote:<br>
    </div>
    <blockquote type="cite"
cite="mid:1914747379.117313.1519402446241.JavaMail.zimbra@dbi-services.com">
      <div style="font-family: arial,helvetica,sans-serif; font-size:
        12pt; color: #000000">
        <div>Hi %,<br>
        </div>
        <div><br data-mce-bogus="1">
        </div>
        <div>I am working with PostgreSQL documentation quite a few
          years now and I am almost happy. What I think is completely
          missing (especially if you compare to commercial product
          documentation) are pictures that illustrate a topic, e.g. the
          relation of
          instance-&gt;database-&gt;user/role-&gt;schema-&gt;objects.<br
            data-mce-bogus="1">
        </div>
        <div><br data-mce-bogus="1">
        </div>
        <div>Is there an agreement not to include that pictures for any
          reason? I can not promise that I find time for that in the
          near future but if that will be appreciated I am willing to
          spend time on that to make the documentation even better.<br
            data-mce-bogus="1">
        </div>
        <div><br data-mce-bogus="1">
        </div>
        <div>Regards<br>
        </div>
        <div>Daniel<br data-mce-bogus="1">
        </div>
      </div>
    </blockquote>
    <br>
  </body>
</html>

--------------8F8DF816E96B1CB80B05E37B--

--------------114CCCA48262D369C770884E
Content-Type: image/svg+xml;
 name="pg_lib_basic_objects.svg"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
 filename="pg_lib_basic_objects.svg"

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+
CjxzdmcKIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIKIHhtbG5zOnhsaW5r
PSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIgogdmVyc2lvbj0iMS4xIgo+CgogPGRl
c2M+CgogIEJhc2ljIFNWRyBlbGVtZW50cyBmb3IgdXNlIGluIGdyYXBoaWNzIG9mIFBvc3Rn
cmVTUUwgZG9jdW1lbnRhdGlvbi4KCiAgVGhlIGZpbGUgd2lsbCByZW5kZXIgdG8gYW4gZW1w
dHkgc2NyZWVuIGFzIGV2ZXJ5dGhpbmcgaXMgc3RvcmVkIGluIGRlZnN8c3ltYm9sLgoKIDwv
ZGVzYz4KCgogPGRlZnM+IAoKICA8c3ltYm9sIGlkPSJwZ19yZWN0Ij4gIDxyZWN0IHdpZHRo
PSIwNTAiIGhlaWdodD0iMDUwIiBmaWxsPSJ5ZWxsb3ciIHN0cm9rZT0iYmxhY2siLz48L3N5
bWJvbD4KICA8c3ltYm9sIGlkPSJwZ19yZWN0XzEiPjxyZWN0IHdpZHRoPSIxMjAiIGhlaWdo
dD0iMDQwIiBmaWxsPSJ3aGl0ZSIgIHN0cm9rZT0iYmxhY2siLz48L3N5bWJvbD4KICA8c3lt
Ym9sIGlkPSJwZ19lbGxpcHNlIj48ZWxsaXBzZSBjeD0iMDYwIiBjeT0iMDIwIiByeD0iMDU5
IiByeT0iMDE5IiBmaWxsPSIjMDA3YWE5IiBzdHJva2U9ImJsYWNrIi8+PC9zeW1ib2w+Cgog
IDxzeW1ib2wgaWQ9InBnX2Rpc2MiPgogICA8ZWxsaXBzZSBjeD0iMDM1IiBjeT0iMDUwIiBy
eD0iMDI1IiByeT0iMDA2IiAgICAgICBmaWxsPSJ3aGl0ZSIgc3Ryb2tlPSJibGFjayIvPiA8
IS0tIGJvdHRvbSAtLT4KICAgPCEtLSBoaWRlIHVwcGVyIGhhbGYgb2YgYm90dG9tIC0tPgog
ICA8cmVjdCAgICB4PSIwMTAiIHk9IjAzMCIgd2lkdGg9IjA1MCIgaGVpZ2h0PSIwMjAiICBm
aWxsPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIwIi8+CiAgIDxlbGxpcHNlIGN4PSIwMzUiIGN5
PSIwMTAiIHJ4PSIwMjUiIHJ5PSIwMDYiICAgICAgIGZpbGw9IndoaXRlIiBzdHJva2U9ImJs
YWNrIi8+IDwhLS0gdG9wIC0tPgogICA8cGF0aCAgICBkPSJNMDEwIDAxMCBsIDAwMCAwNDAi
ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgc3Ryb2tlPSJibGFjayIvPgogICA8
cGF0aCAgICBkPSJNMDYwIDAxMCBsIDAwMCAwNDAiICAgICAgICAgICAgICAgICAgICAgICAg
ICAgICAgICAgc3Ryb2tlPSJibGFjayIvPgogIDwvc3ltYm9sPgoKICA8c3ltYm9sIGlkPSJw
Z19jbG91ZCI+CiAgIDxwYXRoIGQ9Ik0gMDIwIDA1MCBDIDAzMCAwNzAsIDA1MCAwNzAsIDA3
MCAwNjAiIGZpbGw9IndoaXRlIiBzdHJva2U9ImJsYWNrIi8+IAogICA8cGF0aCBkPSJNIDA3
MCAwNjAgQyAxMDAgMDYwLCAxMTAgMDYwLCAxMTAgMDQwIiBmaWxsPSJ3aGl0ZSIgc3Ryb2tl
PSJibGFjayIvPiAKICAgPHBhdGggZD0iTSAxMTAgMDQwIEMgMTIwIDAyMCwgMTEwIDAxMCwg
MDk1IDAxMCIgZmlsbD0id2hpdGUiIHN0cm9rZT0iYmxhY2siLz4gCiAgIDxwYXRoIGQ9Ik0g
MDk1IDAxMCBDIDA5MCAwMDAsIDA3MCAwMDAsIDA2MCAwMTAiIGZpbGw9IndoaXRlIiBzdHJv
a2U9ImJsYWNrIi8+IAogICA8cGF0aCBkPSJNIDA2MCAwMTAgQyAwMTAgMDAwLCAwMDAgMDQw
LCAwMjAgMDUwIiBmaWxsPSJ3aGl0ZSIgc3Ryb2tlPSJibGFjayIvPiAKICA8L3N5bWJvbD4K
CiA8L2RlZnM+CgogPCEtLSBUZXN0cwogPHVzZSB4bGluazpocmVmPSIjcGdfZGlzYyIvPgog
PHVzZSB4bGluazpocmVmPSIjcGdfY2xvdWQiLz4KIC0tPgoKPC9zdmc+Cgo=
--------------114CCCA48262D369C770884E--