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
