Re: Shrinking SVG (Again)

From: Jürgen Purtz <juergen(at)purtz(dot)de>
To: pgsql-docs(at)lists(dot)postgresql(dot)org
Subject: Re: Shrinking SVG (Again)
Date: 2020-02-04 05:41:21
Message-ID: 974e09b8-edf5-f38f-2fb5-a5875782ffc9@purtz.de
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

This patch deals with two different topics. First, it creates a glossary
with basic PG-terms and second, it supplies new figures with explanations.

a) In our documentation we name some objects inconsistently (e.g.: WAL,
WAL file, WAL log, log segment file, WAL segment file, segment file -
whereas a 'file segment' is a very different thing) and often without a
definition of its meaning. For experienced users this is not a problem,
but novice users can get confused easily. In the last months we have
seen some more initiatives to clarify the situation. My attempt to
introduce such a glossary is focused on fundamental PG-related terms
such as CLUSTER or POSTMASTER. Terms with a consistent usage in the
database community, such as SELECT, are not part of it.

b) The figures and their explanations are summed up in a new chapter,
which is intended as an introduction to the PG architecture directly
after the 'Getting Started' chapter. The text makes heavy use of the
glossary. Therefore the glossary must be applied before or together with
the figures.

The source of the figures do not completely comply to our guidelines and
the opinion of the community, which says, that we should use tools
(actually ditaa and graphviz) to create SVG files. However, this figures
are too complex for the two tools. I provide each figure in 3 variants
using a certain name convention: xxx-raw.svg (created in a text- or
XML-editor), xxx-ink.svg (created with Inkscape by reading xxx-raw.svg),
and xxx-ink-svgo.svg (created out of xxx-ink.svg with the tool SVGO).
The 3 variants render to the same output. My personal favorite is 'raw'.
If the community prefers 'ink' or 'ink-svgo' it's ok for me. 'ink-svgo'
has the advantage over 'ink' that it does not contain Inkscape specific
namespaces, elements, or attributes; other elements are reduced in their
size (measured in characters). 'ink-svgo' is notable smaller that the
original Inkscape file - especially in such situations, where files are
really created with the use of Inkscape. The size reduction acts very
efficient. Generate the reduced file with:

# disable 'mergePaths' is necessary (bug); 'config' is helpful for readability
svgo xxx-ink.svg --output=xxx-ink-svgo.svg \
--pretty --indent=2 --precision=2 --multipass \
--disable=removeTitle,mergePaths,convertColors,removeViewBox \
--config '{ "plugins": [ { "cleanupIDs": { "force": true, "minify": false} }] }'

The describing sgml files use two different 'role' attributes for
'imageobject' elements. This is necessary in order to keep rendering of
font sizes of HTML-text and text inside SVG in correlation when you
choose different screen resolutions in the browser.

J. Purtz

Attachment Content-Type Size
architecture-01.patch text/x-patch 125.8 KB
ram-proc-file.png image/png 100.7 KB
cluster-db-schema.png image/png 95.3 KB
directories.png image/png 86.2 KB

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Jürgen Purtz 2020-02-04 06:39:50 Re: Users/Roles do not align.
Previous Message Alvaro Herrera 2020-02-03 21:25:10 Re: Documentation: 21.5. Default Roles