Subject: First SVG graphic

From: Jürgen Purtz <[email-masked]>
Date: Wed, 21 Nov 2018 13:28:07 +0100

Please find in the attachment a SVG file which shows the internal 
structure of PG's pages and a patch to insert it to "storage.sgml". 
Because this is the first graphic for our documentation many additional 
work must be done. SvgHandling.pdf explains how to create graphics and 
integrate them into the textual description, which definitions are 
actually missing (style guide?), and what problems may occur.

We shall create two new directories: doc/src/sgml/svg (as source 
directory for all svg files) and doc/src/sgml/html/svg. The patch for 
Makefile is also attached - HTML, PDF, and EPUB are tested. There is a 
conceptual problem with single-page HTML. The SVG files keep separate 
and I don't know how to include them into the generated single file 
"postgres.html".

@Committers: If you tend to accept this patch, I will start to create 
wiki-pages and additional documentation pages to describe the 
proceeding. If you reject the patch, please give me a justification.

Kind regards

Jürgen Purtz

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 74aac01c39..1fb90cc3f3 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -131,10 +131,11 @@ endif
 
 html: html-stamp
 
-html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML)
+html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) svg/*.svg
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
 	cp $(srcdir)/stylesheet.css html/
+	cp $(srcdir)/svg/*.svg html/svg/
 	touch $@
 
 htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
@@ -142,7 +143,7 @@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
 
 # single-page HTML
-postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML)
+postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) svg/*.svg
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
 
@@ -158,11 +159,11 @@ postgres.txt: postgres.html
 postgres.pdf:
 	$(error Invalid target;  use postgres-A4.pdf or postgres-US.pdf as targets)
 
-%-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
+%-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML) svg/*.svg
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
 
-%-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
+%-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML) svg/*.svg
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
 
@@ -175,7 +176,7 @@ postgres.pdf:
 ##
 
 epub: postgres.epub
-postgres.epub: postgres.sgml $(ALLSGML)
+postgres.epub: postgres.sgml $(ALLSGML) svg/*.svg
 	$(XMLLINT) --noout --valid $<
 	$(DBTOEPUB) $<
 
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 8ef2ac8010..676bb6ecf4 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -775,6 +775,18 @@ data. Empty in ordinary tables.</entry>
 </tgroup>
 </table>
 
+
+ <para>
+  <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>
+ </para>
+
  <para>
 
   The first 24 bytes of each page consists of a page header

---

From: Jürgen Purtz <[email-masked]>
Date: Wed, 28 Nov 2018 18:34:26 +0100

After one week no response at all? Neither positive nor negative. It 
seems that the community has little interest in the SVG issue. Or in my 
suggestion?

Jürgen Purtz

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 28 Nov 2018 13:05:28 -0500

On Wed, Nov 28, 2018 at 06:34:26PM +0100, Jürgen Purtz wrote:
> After one week no response at all? Neither positive nor negative. It seems that
> the community has little interest in the SVG issue. Or in my suggestion?

I have been waiting for someone to take leadership on this important
topic, and have read your 11-page PDF with great interest.

I think your work flow on page 4 clearly illustrates that, even if we
store both native, e.g., Inkscape, and optimized SVG files, we are going
to have a problem.  If someone takes the optimized SVG file, loads it
into a tool other than the tool that created the original file, modifies
it, saves new native and optimized SVG files, and then someone goes back
to the original tool, the native file will not have the modifications
that were made by the new tool and in the new native SVG file.  This
suggests we should just use one tool to handle SVG files, probably
Inkscape.  We can consider other tools later, but let's just standardize
on one tool now and get going.  I realize you can import SVG files into
tools that did not create them, but it seems unlikely the new optimized
SVG file will appear similar to the old one.

As far as rendering in HTML, I think we have two choices:

1.  make images a link to an SVG file that can be rendered in a new
browser tab

2.  convert the SVG to PNG for HTML rendering.

I kind of prefer #2.

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 28 Nov 2018 13:06:29 -0500

> topic, and have read your 11-page PDF with great interest.

Also, I like your idea of a default Inkscape configuration file.

---

From: Andres Freund <[email-masked]>
Date: Wed, 28 Nov 2018 11:46:33 -0800

Hi,

On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote:
> After one week no response at all? Neither positive nor negative. It seems
> that the community has little interest in the SVG issue. Or in my
> suggestion?

I'd suggest describing your proposed workflow in sgml, not a pdf file.

Greetings,

Andres Freund

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 28 Nov 2018 14:49:10 -0500

> I'd suggest describing your proposed workflow in sgml, not a pdf file.

Well, there were a number of images in the PDF that would be harder to
do in SGML.

---

From: Andres Freund <[email-masked]>
Date: Wed, 28 Nov 2018 11:50:37 -0800

Hi,

> Well, there were a number of images in the PDF that would be harder to

My point is that that description is going to be needed going forward,
and thus needs to be in a normal doc format. And if the graphics therein
are the first examples for graphics in PG docs, that works for me.

Greetings,

Andres Freund

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 28 Nov 2018 16:53:09 -0300

> Well, there were a number of images in the PDF that would be harder to

I think the point is how do you integrate the images from the SVG source
into the documentation output.  Presumably that won't be PDF, for
example the HTML output will not use a PDF as an image embedded in the
page.  It probably works ok for the PDF output (of the whole
documentation) to use the PDF of the image ... I suppose the HTML output
will need a PNG or such.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

---

From: Magnus Hagander <[email-masked]>
Date: Wed, 28 Nov 2018 21:08:44 +0100

On Wed, Nov 28, 2018 at 8:53 PM Alvaro Herrera <[email-masked]>
wrote:

> seems
If the source is SVG, why not just use SVG? SVG support in browsers has to
be pushing 10 years now, shouldn't be a problem at all...  And SVG can be
embedded in the HTML itself (whether that would work in this particular
case I don't know, but in theory it can)

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ <http://www.hagander.net/>
 Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>

---

From: Tatsuo Ishii <[email-masked]>
Date: Thu, 29 Nov 2018 09:32:48 +0900 (JST)

> case I don't know, but in theory it can)

+1.
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp

---

From: Craig Ringer <[email-masked]>
Date: Thu, 29 Nov 2018 11:48:17 +0800

> seems that the community has little interest in the SVG issue. Or in my

I'm excited you're doing it. I thought it was part of an existing/ongoing
discussion and didn't really have much to say. I think it's a vital step
forward and we really need to get some graphics into Pg.

Personally I want to let go a bit of the diff-able, merge-able requirements
and accept that not everything plays well when hand written. I got tired of
the arguments that seemed to require that no tool written since 1972 could
be used in our source tree lest SunOS 0.9.ancient have a fit, or someone
find a (gasp) binary in a diff.

So good on you for getting positive action rolling.

-- 
 Craig Ringer                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services

---

From: Oleg Bartunov <[email-masked]>
Date: Thu, 29 Nov 2018 12:54:03 +0300

On Wed, Nov 28, 2018 at 8:33 PM Jürgen Purtz <[email-masked]> wrote:
>
> After one week no response at all? Neither positive nor negative. It seems that the community has little interest in the SVG issue. Or in my suggestion?

First of all, I am BIG + for having diagrams in our documentation.

I once estimated the number of diagrams in our official documentation
and it was only  50 or so, that means, it is possible to make them
more or less centralized, at least for the initial version. If Jurgen+
agree to work on this I would be happy to help them in the parts I was
working on. For the initial version we could even provide the
generated images along with SVG-source files.

-- 
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company

---

From: Jürgen Purtz <[email-masked]>
Date: Fri, 30 Nov 2018 18:04:06 +0100

I take the reactions of the last days as a strong consent to go on with 
the effort to integrate graphics into the documentation and use SVG as 
the language which creates such graphics. Also the proposed parallel 
handling of two SVG files - a rich but tool-specific version (optional 
and not normative) and a poor tool-independent version (mandatory and 
normative) - for the same graphic seems to be accepted. The community 
agrees that this way is not optimal because the use of *different 
SVG-tools* will lead to unnecessary problems - but there is no consensus 
about tools.

What shall we do next:

  * I will create one or more wiki pages where the procedure is
    described. Everybody can extend this pages or contribute to their
    discussion sites. The pages will be found in the category
    'Documentation' and its subcategory 'SVG' (to be created).
  * Actually, we have the very simple example 'PageLayout.svg' and an
    example of medium complexity 'gin.svg'. For testing purposes we
    shall have a third one of high complexity and with many different
    graphical elements. Can someone send such an example - as a
    screenshot or in any other format?
  * I want to engage everybody to identify important issues of PG and
    visualize them (similar to Oleg's proposal). We will have a -
    possibly long lasting - period of experiments with different
    examples. I think, it's necessary that we make our experiences with
    different tools and proceedings (one person creates a graphic,
    another one contributes changes, using the same or a different tool,
    ...). Those examples shall not be pure academic use cases. They
    shall reflect real situations with the expectation to be included
    into the documentation - one day or another.
  * In the initial phase, it may be helpful to do some centralized
    clearings on the first SVG source files. 'Copy&Paste' is widely used
    and the first examples will have the meaning of a lighthouse.
  * I will contact our web-team to discuss style-guide related issues.

Kind regards, Jürgen

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 30 Nov 2018 17:36:31 -0500

On Fri, Nov 30, 2018 at 06:04:06PM +0100, Jürgen Purtz wrote:
> I take the reactions of the last days as a strong consent to go on with the
> effort to integrate graphics into the documentation and use SVG as the language
> which creates such graphics. Also the proposed parallel handling of two SVG
> files - a rich but tool-specific version (optional and not normative) and a
> poor tool-independent version (mandatory and normative) - for the same graphic
> seems to be accepted. The community agrees that this way is not optimal because
> the use of different SVG-tools will lead to unnecessary problems - but there is
> no consensus about tools.
> 
> What shall we do next:
> 
>   • I will create one or more wiki pages where the procedure is described.
>     Everybody can extend this pages or contribute to their discussion sites.
>     The pages will be found in the category 'Documentation' and its subcategory
>     'SVG' (to be created).
>   • Actually, we have the very simple example 'PageLayout.svg' and an example
>     of medium complexity 'gin.svg'. For testing purposes we shall have a third
>     one of high complexity and with many different graphical elements. Can
>     someone send such an example - as a screenshot or in any other format?
>   • I want to engage everybody to identify important issues of PG and visualize
>     them (similar to Oleg's proposal). We will have a - possibly long lasting -
>     period of experiments with different examples. I think, it's necessary that
>     we make our experiences with different tools and proceedings (one person
>     creates a graphic, another one contributes changes, using the same or a
>     different tool, ...). Those examples shall not be pure academic use cases.
>     They shall reflect real situations with the expectation to be included into
>     the documentation - one day or another.
>   • In the initial phase, it may be helpful to do some centralized clearings on
>     the first SVG source files. 'Copy&Paste' is widely used and the first
>     examples will have the meaning of a lighthouse.
>   • I will contact our web-team to discuss style-guide related issues.

Sounds good.  I have many xfig/SVG images in my presentations if you
want to use any of them:

	https://momjian.us/presentations

---

From: Jürgen Purtz <[email-masked]>
Date: Mon, 3 Dec 2018 16:29:42 +0100

> I will create one or more wiki pages where the procedure is described. 
> Everybody can extend this pages or contribute to their discussion 
> sites. The pages will be found in the category 'Documentation' and its 
> subcategory 'SVG' (to be created).

The wiki pages are online: https://wiki.postgresql.org/wiki/Category:SVG

Kind regards

Jürgen Purtz

---

From: Jürgen Purtz <[email-masked]>
Date: Tue, 18 Dec 2018 16:54:53 +0100

There are three wiki pages describing the procedure: general 
description, Inkscape specifics, colors. You can find them in the 
category SVG.

This mail has 3 SVG graphics attached, each in pure SVG and in Inksape 
SVG format. Furthermore there is a patch for the Makefile and the 
modifications to three sgml files, which are necessary to incorporate 
the graphics.

Kind regards

Jürgen Purtz

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 74aac01c39..2433571358 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -131,10 +131,12 @@ endif
 
 html: html-stamp
 
+	mkdir -p $(srcdir)/html/svg/
 
 htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
@@ -142,7 +144,7 @@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
 
 # single-page HTML
 
@@ -158,11 +160,11 @@ postgres.txt: postgres.html
 postgres.pdf:
 	$(error Invalid target;  use postgres-A4.pdf or postgres-US.pdf as targets)

 
@@ -175,7 +177,7 @@ postgres.pdf:
 ##
 
 epub: postgres.epub
 
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index cc7cd1ed2c..34e4eabaad 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -453,6 +453,18 @@
   key values for different columns can be of different types.
  </para>
 
+ <para>
+  <mediaobject id="gin-trees-and-lists">
+   <imageobject role="html">
+    <imagedata fileref="svg/gin.svg" format="SVG" align="center" />
+    <!-- or: <imagedata fileref="svg/gin.svg" format="SVG" align="center" /> -->
+   </imageobject>
+   <imageobject role="fo">
+    <imagedata fileref="svg/gin.svg" format="SVG" scale="70" />
+   </imageobject>
+  </mediaobject>
+ </para>
+
  <sect2 id="gin-fast-update">
   <title>GIN Fast Update Technique</title>
 
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 2015410a42..ea2681d707 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -73,6 +73,17 @@ PostgreSQL documentation
    architectures.
   </para>
 
+  <para>
+   <mediaobject id="pg-dump-svg">
+    <imageobject role="html">
+     <imagedata fileref="svg/pgDump.svg" format="SVG" align="center" />
+    </imageobject>
+    <imageobject role="fo">
+     <imagedata fileref="svg/pgDump.svg" format="SVG" scale="70" />
+    </imageobject>
+   </mediaobject>
+  </para>
+
   <para>
    When used with one of the archive file formats and combined with
    <application>pg_restore</application>,
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 8ef2ac8010..144c1deeef 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -775,6 +775,18 @@ data. Empty in ordinary tables.</entry>
 </tgroup>
 </table>
 
+ <para>
+  <mediaobject id="PageLayoutSVG">
+   <imageobject role="html">
+    <imagedata fileref="svg/PageLayout.svg" format="SVG" />
+    <!-- or: <imagedata fileref="svg/PageLayout.svg" format="SVG" align="center" /> -->
+   </imageobject>
+   <imageobject role="fo">
+    <imagedata fileref="svg/PageLayout.svg" format="SVG" scale="70" />
+   </imageobject>
+  </mediaobject>
+ </para>
+
  <para>

---

From: Jürgen Purtz <[email-masked]>
Date: Sun, 23 Dec 2018 16:10:30 +0100

a) The "Entry tree" and the "Posting trees" of the graphic "gin.svg" 
shows links not only from one tree-level to the next but also within 
each level from node to node. Is that correct?

b) Is it worth to visualize PG's tree-implementation in a separate 
graphic - or is it the same as in every other tree-implementation that 
you have learned in your academic studies? If yes: in which chapter?

Kind regards, Jürgen

---

From: Jürgen Purtz <[email-masked]>
Date: Fri, 28 Dec 2018 19:28:49 +0100

I failed to generate the "single HTML file".

The default Makefile task, which creates multiple HTML files, works 
properly, because it confines itself to create links to SVG files. The 
SVG structure keeps hidden to the Docbook validation and processing - 
Docbook recognises only some additional links. What I have tried to 
generate a single HTML file is the use of xi:XInclude before validating 
and further processing. In this case the SVG structure is visible to 
Docbook.

In general it is possible to use SVG within Docbook 4.x, if you switch 
the doctype to

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook SVG Module V1.1CR1//EN"
                          "http://www.oasis-open.org/docbook/xml/svg/1.1CR1/dbsvg.dtd"  

This is an Docbook 4.x extension 
(https://docbook.org/specs/wd-docbook-svg-1.1cr1) for SVG-integration. 
But it's only a working draft from 2004, it never reached the status of 
an official OASIS standard. As far as I have seen, it works (with some 
limitations), if the SVG data is an integral part of the xml/sgml source 
file. I failed to combine it with xi:XInclude. In opposite to this the 
combination of xi:XInclude, SVG, and Docbook 5.1 works well. In my 
opinion this results from the fact, that the structure of Docbook 4.x is 
based on a DTD, whereas Docbook 5.x uses Relax-NG (and generates xsd 
files out of rng). DTDs natively are not namespace-aware, you must do 
some trickery to handle namespaces. Docbook 5.x is not only namespace 
aware, it natively includes definitions for SVG and other important 
standards like MathML.

My questions to the community are:

  * Does anyone has an idea how to generate single HTML file in the
    actual situation?
  * Shall we delay the SVG integration until we have switched to Docbook
    5.x? This task is a great step, but it must be done in any case,
    because Docbook 4.x is outdated since many years. Btw: Because of
    other problems (https://github.com/docbook/docbook/issues/74) it is
    likely that we cannot use 5.1 but have to wait for the upcoming
    release 5.2.

Kind regards

Jürgen Purtz

---

From: Jürgen Purtz <[email-masked]>
Date: Mon, 7 Jan 2019 17:44:07 +0000

>   * Does anyone has an idea how to generate single HTML file in the

Thanks to an additional template created by Alexander Lakhin, which 
extends the 'nochunk' stylesheet for SVG and MathML processing, it is 
now possible to create the "single HTML file" of our documentation 
including SVG. For me this is a working solution as long as we use 
Docbook 4. After the migration to Docbook 5, both languages as well as 
full namespace support will be natively included in Docbook.

Does anyone faced some more problems? Or can we start to include the 
three first SVG graphics into PG's documentation?

Kind regards

Jürgen Purtz

diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl
index ffd2012e91..3a20a47bce 100644
--- a/doc/src/sgml/stylesheet-html-nochunk.xsl
+++ b/doc/src/sgml/stylesheet-html-nochunk.xsl
@@ -9,4 +9,23 @@
 <xsl:include href="stylesheet-html-common.xsl" />
 <xsl:include href="stylesheet-speedup-xhtml.xsl" />
 
+<xsl:template match="imagedata">
+  <xsl:variable name="filename">
+    <xsl:call-template name="mediaobject.filename">
+      <xsl:with-param name="object" select=".."/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:choose>
+    <!-- Handle MathML and SVG markup in imagedata -->
+    <xsl:when xmlns:mml="http://www.w3.org/1998/Math/MathML" test="mml:*">
+      <xsl:apply-templates/>
+    </xsl:when>
+    <xsl:when xmlns:svg="http://www.w3.org/2000/svg" test="svg:*">
+      <xsl:apply-templates/>
+    </xsl:when>
+  </xsl:choose>
+  <xsl:copy-of select="document($filename)"/>
+</xsl:template>
+
 </xsl:stylesheet>

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 17 Jan 2019 12:20:17 -0500

On Sun, Dec 23, 2018 at 04:10:30PM +0100, Jürgen Purtz wrote:
> a) The "Entry tree" and the "Posting trees" of the graphic "gin.svg" shows
> links not only from one tree-level to the next but also within each level
> from node to node. Is that correct?
> 
> b) Is it worth to visualize PG's tree-implementation in a separate graphic -
> or is it the same as in every other tree-implementation that you have
> learned in your academic studies? If yes: in which chapter?

I am CC'ing Oleg, Teodor, and Alexander, who can answer the first
question, and maybe the second.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 17 Jan 2019 12:40:53 -0500

On Mon, Jan  7, 2019 at 05:44:07PM +0000, Jürgen Purtz wrote:
>       □ Does anyone has an idea how to generate single HTML file in the actual
>         situation?
> 
> 
> Thanks to an additional template created by Alexander Lakhin, which extends the
> 'nochunk' stylesheet for SVG and MathML processing, it is now possible to
> create the "single HTML file" of our documentation including SVG. For me this
> is a working solution as long as we use Docbook 4. After the migration to
> Docbook 5, both languages as well as full namespace support will be natively
> included in Docbook.
> 
> Does anyone faced some more problems? Or can we start to include the three
> first SVG graphics into PG's documentation?

OK, the wiki pages look good, as do the diagrams, and I think you have
the process we all agreed with.  Should we move ahead and commit some of
these diagrams to the souce tree for PG 12?

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 17 Jan 2019 14:49:48 -0300

> learned in your academic studies? If yes: in which chapter?

Who's to say that every single reader of the PG documentation has had
relevant academic studies?  My opinion is that these graphics are worth
including even if they're well-known to many.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 17 Jan 2019 13:26:52 -0500

> including even if they're well-known to many.

Agreed.  Indexing methods are mysterious without diagrams.

---

From: Tatsuo Ishii <[email-masked]>
Date: Fri, 18 Jan 2019 07:43:07 +0900 (JST)

> these diagrams to the souce tree for PG 12? 

Yes, I think we should.

Best regards,

---

From: Jürgen Purtz <[email-masked]>
Date: Mon, 21 Jan 2019 15:02:43 +0100

The attached patch contains all necessary changes to the sgml, svg, and 
Makefile. (Possibly we need some more changes regarding the 'install*' 
tasks of Makefile.) How to go on? Shall I send the patch to a different 
list or to Commitfest 2019-03?

Kind regards

Jürgen Purtz

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 8326c7c673..27d1e674f4 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -57,6 +57,8 @@ GENERATED_SGML = version.sgml \
 
 ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
 
+SVGSRC := $(wildcard $(srcdir)/svg/*.svg)
+
 
 ##
 ## Man pages
@@ -125,10 +127,12 @@ endif
 
 html: html-stamp
 
+html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(SVGSRC)
+	$(MKDIR_P) html/svg
+	cp $(SVGSRC) html/svg
 	touch $@
 
 htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
@@ -136,7 +140,7 @@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
 
 # single-page HTML
-postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML)
+postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) $(SVGSRC)
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
 
@@ -152,15 +156,15 @@ postgres.txt: postgres.html
 postgres.pdf:
 	$(error Invalid target;  use postgres-A4.pdf or postgres-US.pdf as targets)
 
-%-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
+%-A4.fo: stylesheet-fo.xsl %.sgml
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
 
-%-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
+%-US.fo: stylesheet-fo.xsl %.sgml
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
 
-%.pdf: %.fo
+%.pdf: %.fo $(ALLSGML) $(SVGSRC)
 	$(FOP) -fo $< -pdf $@

@@ -169,7 +173,7 @@ postgres.pdf:
 ##
 
 epub: postgres.epub
-postgres.epub: postgres.sgml $(ALLSGML)
+postgres.epub: postgres.sgml $(ALLSGML) $(SVGSRC)
 	$(XMLLINT) --noout --valid $<
 	$(DBTOEPUB) $<
 
@@ -209,7 +213,7 @@ check: postgres.sgml $(ALLSGML) check-tabs
 install: install-html install-man
 
 installdirs:
-	$(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
+	$(MKDIR_P) '$(DESTDIR)$(htmldir)'/html/svg html/svg $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
 
 # If the install used a man directory shared with other applications, this will remove all files.
 uninstall:
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index cc7cd1ed2c..195e385798 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -453,6 +453,17 @@
   key values for different columns can be of different types.
  </para>
 
+ <para>
 
index 9e0bb93f08..1fd9ced5f5 100644
 
+  <para>
index 8ef2ac8010..4d39ceb958 100644
@@ -775,6 +775,17 @@ data. Empty in ordinary tables.</entry>
 </tgroup>
 </table>
 
+ <para>
 
index ffd2012e91..9e756708f5 100644
@@ -9,4 +9,27 @@
 
+<!--
+  Integrate SVG and MathML files into the nochunk version (one single HTML file).
+  After migrating to Docbook 5.x this template becomes superfluous.
+-->
+<xsl:template match="imagedata">
+  <xsl:variable name="filename">
+    <xsl:call-template name="mediaobject.filename">
+      <xsl:with-param name="object" select=".."/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:choose>
+    <!-- Handle MathML and SVG markup in imagedata -->
+    <xsl:when xmlns:mml="http://www.w3.org/1998/Math/MathML" test="mml:*">
+      <xsl:apply-templates/>
+    </xsl:when>
+    <xsl:when xmlns:svg="http://www.w3.org/2000/svg" test="svg:*">
+      <xsl:apply-templates/>
+    </xsl:when>
+  </xsl:choose>
+  <xsl:copy-of select="document($filename)"/>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/doc/src/sgml/svg/Inkscape/PageLayout_Inkscape.svg b/doc/src/sgml/svg/Inkscape/PageLayout_Inkscape.svg
new file mode 100644
index 0000000000..5803077781
--- /dev/null
+++ b/doc/src/sgml/svg/Inkscape/PageLayout_Inkscape.svg
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" width="580" height="280" viewBox="0 0 580 280" version="1.1" id="svg53" sodipodi:docname="PageLayout_Inkscape.svg" inkscape:version="0.92.3 (2405546, 2018-03-11)">
+  <metadata id="metadata57">
+    <rdf:RDF>
+      <cc:Work rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" borderopacity="1" objecttolerance="10" gridtolerance="10" guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="640" inkscape:window-height="480" id="namedview55" showgrid="false" inkscape:zoom="1.2896552" inkscape:cx="329.04306" inkscape:cy="137.84105" inkscape:current-layer="svg53" />
+  <style type="text/css" id="style2">
+  .text_small   {font-style:normal;
+                 font-weight:normal;
+                 font-size:11px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_normal  {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_big     {font-style:normal;
+                 font-weight:normal;
+                 font-size:28px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_comment {font-style:italic;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_mono    {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:monospace, monospace;
+                 white-space:pre;
+                 fill:black;
+                }
+  </style>
+  <defs id="defs7">
+    <marker id="a" markerHeight="10" markerWidth="10" orient="auto" refY="5">
+      <path d="m0 0 10 5-10 5 3-5z" id="path4" />
+    </marker>
+  </defs>
+  <!-- border and background -->
+  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%" fill="whitesmoke" stroke="#CCCCCC" id="rect9" />
+  <!-- fill="hsl(0, 0%, 97%)" stroke="hsl(0, 0%, 80%)" /> -->
+  <!-- outer rectangle and texts -->
+  <rect x="20" y="80" width="500" height="150" fill="white" stroke="black" id="rect11" />
+  <text class="text_big" x="178" y="50" id="text13">Page Layout</text>
+  <text class="text_mono" x="540" y="125" transform="rotate(90 540 125)" id="text15">8   k B</text>
+  <text class="text_normal" x="392" y="144" id="text17">Free space</text>
+  <!-- first line -->
+  <rect x="20" y="80" width="90" height="30" fill="lime" stroke="black" id="rect19" />
+  <text class="text_normal" x="30" y="100" id="text21">Header</text>
+  <rect x="110" y="80" width="60" height="30" fill="cornflowerblue" stroke="black" id="rect23" />
+  <text class="text_normal" x="115" y="100" id="text25">ItemId</text>
+  <rect x="170" y="80" width="60" height="30" fill="cornflowerblue" stroke="black" id="rect27" />
+  <text class="text_normal" x="175" y="100" id="text29">ItemId</text>
+  <path d="m235 95h78" style="marker-end:url(#a);stroke-dasharray:5, 5" stroke="black" id="path31" />
+  <path d="m184 105-71 85" style="marker-end:url(#a)" fill="none" stroke="black" id="path33" />
+  <path d="m138 105 202 85" style="marker-end:url(#a)" fill="none" stroke="black" id="path35" />
+  <!-- last line -->
+  <path d="m100 215h-30" style="marker-end:url(#a);stroke-dasharray:5, 5" stroke="black" id="path37" />
+  <rect x="105" y="200" width="245" height="30" style="fill:#80BFFF" stroke="black" id="rect39" />
+  <!-- fill:hsl(210, 100%, 75%) -->
+  <text class="text_normal" x="121" y="220" id="text41">Item</text>
+  <rect x="345" y="200" width="85" height="30" style="fill:#80BFFF" stroke="black" id="rect43" />
+  <!-- fill:hsl(210, 100%, 75%) -->
+  <text class="text_normal" x="352" y="220" id="text45">Item</text>
+  <rect x="430" y="200" width="90" height="30" style="fill:springgreen" stroke="black" id="rect47" />
+  <text class="text_normal" x="440" y="220" id="text49">Special</text>
+  <!-- explanation -->
+  <text class="text_small" x="100" y="260" id="text51">Content grows from start to center and from end to center.</text>
+</svg>
diff --git a/doc/src/sgml/svg/Inkscape/gin_Inkscape.svg b/doc/src/sgml/svg/Inkscape/gin_Inkscape.svg
new file mode 100644
index 0000000000..be9a9b4c73
--- /dev/null
+++ b/doc/src/sgml/svg/Inkscape/gin_Inkscape.svg
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" width="580" height="320" viewBox="0 0 580 320" version="1.1" id="svg139" sodipodi:docname="gin_Inkscape.svg" inkscape:version="0.92.3 (2405546, 2018-03-11)">
+  <metadata id="metadata143">
+    <rdf:RDF>
+      <cc:Work rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" borderopacity="1" objecttolerance="10" gridtolerance="10" guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="640" inkscape:window-height="480" id="namedview141" showgrid="false" inkscape:zoom="2.5793103" inkscape:cx="356.431" inkscape:cy="207.50734" inkscape:current-layer="svg139" />
+  <style type="text/css" id="style2">
+  .text_small   {font-style:normal;
+                 font-weight:normal;
+                 font-size:11px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_normal  {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_big     {font-style:normal;
+                 font-weight:normal;
+                 font-size:28px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_comment {font-style:italic;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_mono    {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:monospace, monospace;
+                 white-space:pre;
+                 fill:black;
+                }
+  </style>
+  <defs id="defs7">
+    <marker id="a" markerHeight="10" markerWidth="10" orient="auto" refY="5">
+      <path d="m0 0 10 5-10 5 3-5z" id="path4" />
+    </marker>
+  </defs>
+  <!-- border and background -->
+  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%" fill="whitesmoke" stroke="#CCCCCC" id="rect9" />
+  <!-- fill="hsl(0, 0%, 97%)" stroke="hsl(0, 0%, 80%)" /> -->
+  <!-- Meta page -->
+  <rect x="30" y="50" width="80" height="40" fill="white" stroke="black" id="rect11" />
+  <text class="text_normal" x="32" y="65" id="text13">Meta page</text>
+  <!-- Entry tree -->
+  <rect x="181" y="19" width="209" height="160" fill="white" stroke="black" id="rect15" />
+  <text class="text_normal" x="186" y="35" id="text17">Entry tree</text>
+  <path d="m110 70h83" style="marker-end:url(#a)" stroke="black" id="path19" />
+  <rect x="206" y="64" width="25" height="10" style="fill:lightgrey" stroke="black" id="rect21" />
+  <path d="m231 65 11-12" style="marker-end:url(#a)" stroke="black" id="path23" />
+  <path d="m231 69 11 9" style="marker-end:url(#a)" stroke="black" id="path25" />
+  <path d="m231 73 14 35" style="marker-end:url(#a)" stroke="black" id="path27" />
+  <rect x="251" y="39" width="25" height="10" style="fill:lightgrey" stroke="black" id="rect29" />
+  <rect x="251" y="79" width="25" height="10" style="fill:lightgrey" stroke="black" id="rect31" />
+  <rect x="251" y="119" width="25" height="10" style="fill:lightgrey" stroke="black" id="rect33" />
+  <path d="m266 49v18" style="marker-end:url(#a)" stroke="black" id="path35" />
+  <path d="m266 89v18" style="marker-end:url(#a)" stroke="black" id="path37" />
+  <path d="m276 44 32 -5" style="marker-end:url(#a)" stroke="black" id="path39" />
+  <path d="m276 44 32 15" style="marker-end:url(#a)" stroke="black" id="path41" />
+  <path d="m276 84 32 8" style="marker-end:url(#a)" stroke="black" id="path43" />
+  <path d="m276 124 32 0" style="marker-end:url(#a)" stroke="black" id="path45" />
+  <path d="m276 124 32 23" style="marker-end:url(#a)" stroke="black" id="path47" />
+  <rect x="320" y="30" width="25" height="10" style="fill:green" id="rect49" stroke="black" />
+  <rect x="320" y="60" width="25" height="10" style="fill:limegreen" id="rect51" stroke="black" />
+  <rect x="320" y="90" width="25" height="10" style="fill:green" id="rect53" stroke="black" />
+  <rect x="320" y="120" width="25" height="10" style="fill:limegreen" id="rect55" stroke="black" />
+  <rect x="320" y="150" width="25" height="10" style="fill:limegreen" id="rect57" stroke="black" />
+  <path d="m331 40v6" style="marker-end:url(#a)" stroke="black" id="path59" />
+  <path d="m331 70v6" style="marker-end:url(#a)" stroke="black" id="path61" />
+  <path d="m331 100v6" style="marker-end:url(#a)" stroke="black" id="path63" />
+  <path d="m331 130v6" style="marker-end:url(#a)" stroke="black" id="path65" />
+  <!-- Posting tree 1 -->
+  <rect x="430" y="10" width="115" height="70" fill="white" stroke="black" id="rect67" />
+  <text class="text_normal" x="440" y="26" id="text69">Posting tree</text>
+  <path d="m345 35 83 14" style="marker-end:url(#a)" stroke="black" id="path71" />
+  <rect x="440" y="45" width="25" height="10" style="fill:lightgrey" stroke="black" id="rect73" />
+  <path d="m465 50 30 -9" style="marker-end:url(#a)" stroke="black" id="path75" />
+  <path d="m465 50 30 18" style="marker-end:url(#a)" stroke="black" id="path77" />
+  <rect x="505" y="35" width="25" height="10" style="fill:limegreen" stroke="black" id="rect79" />
+  <rect x="505" y="65" width="25" height="10" style="fill:limegreen" stroke="black" id="rect81" />
+  <path d="m515 47v8" style="marker-end:url(#a)" stroke="black" id="path83" />
+  <!-- Posting tree 2 -->
+  <rect x="430" y="100" width="115" height="70" fill="white" stroke="black" id="rect85" />
+  <text class="text_normal" x="440" y="115" id="text87">Posting tree</text>
+  <path d="m345 95 148 37" style="marker-end:url(#a)" stroke="black" id="path89" />
+  <rect x="505" y="130" width="25" height="10" style="fill:limegreen" stroke="black" id="rect91" />
+  <!-- Posting tree 3 -->
+  <rect x="430" y="190" width="115" height="70" fill="white" stroke="black" id="rect93" />
+  <text class="text_normal" x="440" y="205" id="text95">Posting tree</text>
+  <path d="m345 95 85 125" style="marker-end:url(#a)" stroke="black" id="path97" />
+  <rect x="440" y="225" width="25" height="10" style="fill:lightgrey" stroke="black" id="rect99" />
+  <path d="m465 230 30 -9" style="marker-end:url(#a)" stroke="black" id="path101" />
+  <path d="m465 230 30 18" style="marker-end:url(#a)" stroke="black" id="path103" />
+  <rect x="505" y="215" width="25" height="10" style="fill:limegreen" stroke="black" id="rect105" />
+  <rect x="505" y="245" width="25" height="10" style="fill:limegreen" stroke="black" id="rect107" />
+  <path d="m515 227v8" style="marker-end:url(#a)" stroke="black" id="path109" />
+  <!-- Pending list -->
+  <rect x="30" y="215" width="360" height="45" fill="white" stroke="black" id="rect111" />
+  <text class="text_normal" x="37" y="232" id="text113">Pending list</text>
+  <path d="m70 90 77 138" style="fill:none;marker-end:url(#a)" stroke="black" id="path115" />
+  <rect x="155" y="235" width="25" height="10" style="fill:orangered" stroke="black" id="rect117" />
+  <rect x="210" y="235" width="25" height="10" style="fill:orangered" stroke="black" id="rect119" />
+  <rect x="265" y="235" width="25" height="10" style="fill:orangered" stroke="black" id="rect121" />
+  <rect x="320" y="235" width="25" height="10" style="fill:orangered" stroke="black" id="rect123" />
+  <path d="m180 240h18" style="marker-end:url(#a)" stroke="black" id="path125" />
+  <path d="m235 240h18" style="marker-end:url(#a)" stroke="black" id="path127" />
+  <path d="m290 240h18" style="marker-end:url(#a)" stroke="black" id="path129" />
+  <!-- Explanation -->
+  <rect x="30" y="291" width="25" height="10" fill="green" stroke="black" id="rect131" />
+  <text class="text_small" x="60" y="300" id="text133">Pointers to Posting tree</text>
+  <rect x="230" y="291" width="25" height="10" fill="limegreen" stroke="black" id="rect135" />
+  <text class="text_small" x="260" y="300" id="text137">Heap pointers (in Posting list or Posting tree)</text>
+</svg>
diff --git a/doc/src/sgml/svg/Inkscape/pgDump_Inkscape.svg b/doc/src/sgml/svg/Inkscape/pgDump_Inkscape.svg
new file mode 100644
index 0000000000..3e74b485a0
--- /dev/null
+++ b/doc/src/sgml/svg/Inkscape/pgDump_Inkscape.svg
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" width="580" height="370" viewBox="0 0 580 370" version="1.1" id="svg75" sodipodi:docname="pgDump_Inkscape.svg" inkscape:version="0.92.3 (2405546, 2018-03-11)">
+  <metadata id="metadata79">
+    <rdf:RDF>
+      <cc:Work rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" borderopacity="1" objecttolerance="10" gridtolerance="10" guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="640" inkscape:window-height="480" id="namedview77" showgrid="false" inkscape:zoom="0.57538462" inkscape:cx="-79.946524" inkscape:cy="185" inkscape:current-layer="svg75" />
+  <style type="text/css" id="style2">
+  .text_small   {font-style:normal;
+                 font-weight:normal;
+                 font-size:11px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_normal  {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_big     {font-style:normal;
+                 font-weight:normal;
+                 font-size:28px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_comment {font-style:italic;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:&quot;Open Sans&quot;, sans-serif;
+                 fill:black;
+                }
+  .text_mono    {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:monospace, monospace;
+                 white-space:pre;
+                 fill:black;
+                }
+  </style>
+  <defs id="defs23">
+    <marker id="a" markerHeight="10" markerWidth="10" orient="auto" refY="5">
+      <path d="m0 0 10 5 -10 5 3 -5z" id="path4" />
+    </marker>
+    <linearGradient id="gradient_disc" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="10%" style="stop-color:white" id="stop7" />
+      <stop offset="90%" style="stop-color:steelblue" id="stop9" />
+    </linearGradient>
+    <symbol id="disc" fill="url(#gradient_disc)" stroke="black">
+      <ellipse cx="52" cy="100" rx="50" ry="12" id="ellipse12" />
+      <!-- bottom -->
+      <!-- hide upper half of bottom. use <rect> instead of <clipPath> to support gradient -->
+      <rect x="2" y="20" width="100" height="80" stroke-width="0" id="rect14" />
+      <ellipse cx="52" cy="20" rx="50" ry="12" id="ellipse16" />
+      <!-- top -->
+      <path d="m2 21 v80" id="path18" />
+      <!-- left  -->
+      <path d="m102 21 v80" id="path20" />
+      <!-- right -->
+    </symbol>
+  </defs>
+  <!-- border and background -->
+  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%" fill="whitesmoke" stroke="#CCCCCC" id="rect25" />
+  <!-- fill="hsl(0, 0%, 97%)" stroke="hsl(0, 0%, 80%)" /> -->
+  <!-- Original DB -->
+  <g transform="translate(220 10)" id="g33">
+    <use xlink:href="#disc" id="use27" />
+    <text x="25" y="60" class="text_normal" id="text29">Original</text>
+    <text x="18" y="75" class="text_normal" id="text31">Database</text>
+  </g>
+  <text x="50" y="60" class="text_normal" id="text35">pg_dump, script format</text>
+  <path d="m210 70 h-138 v40" fill="none" stroke="black" marker-end="url(#a)" id="path37" />
+  <text x="340" y="60" class="text_normal" id="text39">pg_dump, other archive formats</text>
+  <path d="m340 70 h155 v40" fill="none" stroke="black" marker-end="url(#a)" id="path41" />
+  <!-- SQL script -->
+  <g transform="translate(20 120)" id="g49">
+    <use xlink:href="#disc" id="use43" />
+    <text x="10" y="60" class="text_normal" id="text45">SQL INSERT</text>
+    <text x="10" y="75" class="text_normal" id="text47">commands</text>
+  </g>
+  <text x="130" y="285" class="text_normal" id="text51">psql</text>
+  <path d="m72 240 v55 h130" fill="none" stroke="black" marker-end="url(#a)" id="path53" />
+  <!-- Binary dump -->
+  <g transform="translate(440 120)" id="g61">
+    <use xlink:href="#disc" id="use55" />
+    <text x="30" y="60" class="text_normal" id="text57">Binary</text>
+    <text x="35" y="75" class="text_normal" id="text59">File(s)</text>
+  </g>
+  <text x="370" y="285" class="text_normal" id="text63">pg_restore</text>
+  <path d="m495 240 v55 h-155" fill="none" stroke="black" marker-end="url(#a)" id="path65" />
+  <!-- New DB -->
+  <g transform="translate(220 230)" id="g73">
+    <use xlink:href="#disc" id="use67" />
+    <text x="20" y="60" class="text_normal" id="text69">Restored</text>
+    <text x="18" y="75" class="text_normal" id="text71">Database</text>
+  </g>
+</svg>
diff --git a/doc/src/sgml/svg/PageLayout.svg b/doc/src/sgml/svg/PageLayout.svg
new file mode 100644
index 0000000000..cf504ad640
--- /dev/null
+++ b/doc/src/sgml/svg/PageLayout.svg
@@ -0,0 +1,70 @@
+<svg width="580" height="280" viewBox="0 0 580 280" version="1.1" xmlns="http://www.w3.org/2000/svg">
+  <style type="text/css">
+  .text_small   {font-style:normal;
+                 font-weight:normal;
+                 font-size:11px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_normal  {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_big     {font-style:normal;
+                 font-weight:normal;
+                 font-size:28px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_comment {font-style:italic;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_mono    {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:monospace, monospace;
+                 white-space:pre;
+                 fill:black;
+                }
+  </style>
+  <defs>
+    <marker id="a" markerHeight="10" markerWidth="10" orient="auto" refY="5">
+      <path d="m0 0 10 5-10 5 3-5z"/>
+    </marker>
+  </defs>
+
+<!-- border and background -->
+  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%" 
+        fill="whitesmoke" stroke="#CCCCCC" /> <!-- fill="hsl(0, 0%, 97%)" stroke="hsl(0, 0%, 80%)" /> -->
+<!-- outer rectangle and texts -->
+  <rect x="20" y="80" width="500" height="150" fill="white" stroke="black"/>
+  <text class="text_big" x="178" y="50">Page Layout</text>
+  <text class="text_mono" x="540" y="125" transform="rotate(90 540 125)">8   k B</text>
+  <text class="text_normal" x="392" y="144">Free space</text>
+<!-- first line -->
+  <rect x="20" y="80" width="90" height="30" fill="lime" stroke="black"/>
+  <text class="text_normal" x="30" y="100">Header</text>
+  <rect x="110" y="80" width="60" height="30" fill="cornflowerblue" stroke="black"/>
+  <text class="text_normal" x="115" y="100">ItemId</text>
+  <rect x="170" y="80" width="60" height="30" fill="cornflowerblue" stroke="black"/>
+  <text class="text_normal" x="175" y="100">ItemId</text>
+  <path d="m235 95h78" style="marker-end:url(#a);stroke-dasharray:5, 5" stroke="black"/>
+  <path d="m184 105-71 85" style="marker-end:url(#a)" fill="none" stroke="black"/>
+  <path d="m138 105 202 85" style="marker-end:url(#a)" fill="none" stroke="black"/>
+<!-- last line -->
+  <path d="m100 215h-30" style="marker-end:url(#a);stroke-dasharray:5, 5" stroke="black"/>
+  <rect x="105" y="200" width="245" height="30" style="fill:#80BFFF" stroke="black"/> <!-- fill:hsl(210, 100%, 75%) -->
+  <text class="text_normal" x="121" y="220">Item</text>
+  <rect x="345" y="200" width="85" height="30" style="fill:#80BFFF" stroke="black"/>  <!-- fill:hsl(210, 100%, 75%) -->
+  <text class="text_normal" x="352" y="220">Item</text>
+  <rect x="430" y="200" width="90" height="30" style="fill:springgreen" stroke="black"/>
+  <text class="text_normal" x="440" y="220">Special</text>
+<!-- explanation -->
+  <text class="text_small" x="100" y="260">Content grows from start to center and from end to center.</text>
+</svg>
+
diff --git a/doc/src/sgml/svg/gin.svg b/doc/src/sgml/svg/gin.svg
new file mode 100644
index 0000000000..8a5e77b252
--- /dev/null
+++ b/doc/src/sgml/svg/gin.svg
@@ -0,0 +1,123 @@
+<svg width="580" height="320" viewBox="0 0 580 320" version="1.1" xmlns="http://www.w3.org/2000/svg">
+  <style type="text/css">
+  .text_small   {font-style:normal;
+                 font-weight:normal;
+                 font-size:11px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_normal  {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_big     {font-style:normal;
+                 font-weight:normal;
+                 font-size:28px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_comment {font-style:italic;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_mono    {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:monospace, monospace;
+                 white-space:pre;
+                 fill:black;
+                }
+  </style>
+  <defs>
+    <marker id="a" markerHeight="10" markerWidth="10" orient="auto" refY="5">
+      <path d="m0 0 10 5-10 5 3-5z"/>
+    </marker>
+  </defs>
+<!-- border and background -->
+  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%" 
+        fill="whitesmoke" stroke="#CCCCCC" /> <!-- fill="hsl(0, 0%, 97%)" stroke="hsl(0, 0%, 80%)" /> -->
+
+<!-- Meta page -->
+  <rect x="30" y="50" width="80" height="40" fill="white" stroke="black"/>
+  <text class="text_normal" x="32" y="65">Meta page</text>
+
+<!-- Entry tree -->
+  <rect x="181" y="19" width="209" height="160" fill="white" stroke="black"/>
+  <text class="text_normal" x="186" y="35">Entry tree</text>
+  <path d="m110 70h83" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="206" y="64" width="25" height="10" style="fill:lightgrey" stroke="black"/>
+  <path d="m231 65 11-12" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m231 69 11 9" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m231 73 14 35" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="251" y="39" width="25" height="10" style="fill:lightgrey" stroke="black"/>
+  <rect x="251" y="79" width="25" height="10" style="fill:lightgrey" stroke="black"/>
+  <rect x="251" y="119" width="25" height="10" style="fill:lightgrey" stroke="black"/>
+  <path d="m266 49v18" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m266 89v18" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m276 44 32 -5" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m276 44 32 15" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m276 84 32 8" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m276 124 32 0" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m276 124 32 23" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="320" y="30" width="25" height="10" style="fill:green" stroke="black"/>
+  <rect x="320" y="60" width="25" height="10" style="fill:limegreen" stroke="black"/>
+  <rect x="320" y="90" width="25" height="10" style="fill:green" stroke="black"/>
+  <rect x="320" y="120" width="25" height="10" style="fill:limegreen" stroke="black"/>
+  <rect x="320" y="150" width="25" height="10" style="fill:limegreen" stroke="black"/>
+  <path d="m331 40v6" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m331 70v6" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m331 100v6" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m331 130v6" style="marker-end:url(#a)" stroke="black"/>
+
+
+<!-- Posting tree 1 -->
+  <rect x="430" y="10" width="115" height="70" fill="white" stroke="black"/>
+  <text class="text_normal" x="440" y="26">Posting tree</text>
+  <path d="m345 35 83 14" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="440" y="45" width="25" height="10" style="fill:lightgrey" stroke="black"/>
+  <path d="m465 50 30 -9" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m465 50 30 18" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="505" y="35" width="25" height="10" style="fill:limegreen" stroke="black"/>
+  <rect x="505" y="65" width="25" height="10" style="fill:limegreen" stroke="black"/>
+  <path d="m515 47v8" style="marker-end:url(#a)" stroke="black"/>
+
+<!-- Posting tree 2 -->
+  <rect x="430" y="100" width="115" height="70" fill="white" stroke="black"/>
+  <text class="text_normal" x="440" y="115">Posting tree</text>
+  <path d="m345 95 148 37" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="505" y="130" width="25" height="10" style="fill:limegreen" stroke="black"/>
+
+<!-- Posting tree 3 -->
+  <rect x="430" y="190" width="115" height="70" fill="white" stroke="black"/>
+  <text class="text_normal" x="440" y="205">Posting tree</text>
+  <path d="m345 95 85 125" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="440" y="225" width="25" height="10" style="fill:lightgrey" stroke="black"/>
+  <path d="m465 230 30 -9" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m465 230 30 18" style="marker-end:url(#a)" stroke="black"/>
+  <rect x="505" y="215" width="25" height="10" style="fill:limegreen" stroke="black"/>
+  <rect x="505" y="245" width="25" height="10" style="fill:limegreen" stroke="black"/>
+  <path d="m515 227v8" style="marker-end:url(#a)" stroke="black"/>
+
+<!-- Pending list -->
+  <rect x="30" y="215" width="360" height="45" fill="white" stroke="black"/>
+  <text class="text_normal" x="37" y="232">Pending list</text>
+  <path d="m70 90 77 138" style="fill:none;marker-end:url(#a)" stroke="black"/>
+  <rect x="155" y="235" width="25" height="10" style="fill:orangered" stroke="black"/>
+  <rect x="210" y="235" width="25" height="10" style="fill:orangered" stroke="black"/>
+  <rect x="265" y="235" width="25" height="10" style="fill:orangered" stroke="black"/>
+  <rect x="320" y="235" width="25" height="10" style="fill:orangered" stroke="black"/>
+  <path d="m180 240h18" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m235 240h18" style="marker-end:url(#a)" stroke="black"/>
+  <path d="m290 240h18" style="marker-end:url(#a)" stroke="black"/>
+
+<!-- Explanation -->
+  <rect x="30" y="291" width="25" height="10" fill="green" stroke="black"/>
+  <text class="text_small" x="60" y="300">Pointers to Posting tree</text>
+  <rect x="230" y="291" width="25" height="10" fill="limegreen" stroke="black"/>
+  <text class="text_small" x="260" y="300">Heap pointers (in Posting list or Posting tree)</text>
+
+</svg>
diff --git a/doc/src/sgml/svg/pgDump.svg b/doc/src/sgml/svg/pgDump.svg
new file mode 100644
index 0000000000..33e4a7d467
--- /dev/null
+++ b/doc/src/sgml/svg/pgDump.svg
@@ -0,0 +1,96 @@
+<svg width="580" height="370" viewBox="0 0 580 370" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <style type="text/css">
+  .text_small   {font-style:normal;
+                 font-weight:normal;
+                 font-size:11px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_normal  {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_big     {font-style:normal;
+                 font-weight:normal;
+                 font-size:28px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_comment {font-style:italic;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:"Open Sans", sans-serif;
+                 fill:black;
+                }
+  .text_mono    {font-style:normal;
+                 font-weight:normal;
+                 font-size:14px;
+                 font-family:monospace, monospace;
+                 white-space:pre;
+                 fill:black;
+                }
+  </style>
+  <defs>
+    <marker id="a" markerHeight="10" markerWidth="10" orient="auto" refY="5">
+      <path d="m0 0 10 5 -10 5 3 -5z"/>
+    </marker>
+
+    <linearGradient id="gradient_disc" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="10%" style="stop-color:white" />
+      <stop offset="90%" style="stop-color:steelblue" />
+    </linearGradient>
+
+    <symbol id="disc" fill="url(#gradient_disc)" stroke="black">
+      <ellipse cx="52" cy="100" rx="50" ry="12" /> <!-- bottom -->
+      <!-- hide upper half of bottom. use <rect> instead of <clipPath> to support gradient -->
+      <rect    x="2" y="20" width="100" height="80" stroke-width="0" />
+      <ellipse cx="52" cy="20" rx="50" ry="12"/> <!-- top -->
+      <path    d="m2 21 v80"/>                   <!-- left  -->
+      <path    d="m102 21 v80"/>                 <!-- right -->      
+    </symbol>
+  </defs>
+
+<!-- border and background -->
+  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%" 
+        fill="whitesmoke" stroke="#CCCCCC" /> <!-- fill="hsl(0, 0%, 97%)" stroke="hsl(0, 0%, 80%)" /> -->
+
+  <!-- Original DB -->
+  <g transform="translate(220 10)">
+    <use xlink:href="#disc" />
+    <text x="25" y="60" class="text_normal">Original</text>
+    <text x="18" y="75" class="text_normal">Database</text>
+  </g>
+  <text x="50" y="60" class="text_normal">pg_dump, script format</text>
+  <path d="m210 70 h-138 v40" fill="none" stroke="black" marker-end="url(#a)"/>
+  <text x="340" y="60" class="text_normal">pg_dump, other archive formats</text>
+  <path d="m340 70 h155 v40" fill="none" stroke="black" marker-end="url(#a)"/>
+
+  <!-- SQL script -->
+  <g transform="translate(20 120)">
+    <use xlink:href="#disc"/>
+    <text x="10" y="60" class="text_normal">SQL INSERT</text>
+    <text x="10" y="75" class="text_normal">commands</text>
+  </g>
+  <text x="130" y="285" class="text_normal">psql</text>
+  <path d="m72 240 v55 h130" fill="none" stroke="black" marker-end="url(#a)"/>
+
+  <!-- Binary dump -->
+  <g transform="translate(440 120)">
+    <use xlink:href="#disc"/>
+    <text x="30" y="60" class="text_normal">Binary</text>
+    <text x="35" y="75" class="text_normal">File(s)</text>
+  </g>
+  <text x="370" y="285" class="text_normal">pg_restore</text>
+  <path d="m495 240 v55 h-155" fill="none" stroke="black" marker-end="url(#a)"/>
+
+  <!-- New DB -->
+  <g transform="translate(220 230)">
+    <use xlink:href="#disc"/>
+    <text x="20" y="60" class="text_normal">Restored</text>
+    <text x="18" y="75" class="text_normal">Database</text>
+  </g>
+
+</svg>
+

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 23 Jan 2019 18:53:12 -0500

On Mon, Jan 21, 2019 at 03:02:43PM +0100, Jürgen Purtz wrote:
> Makefile. (Possibly we need some more changes regarding the 'install*' tasks
> of Makefile.) How to go on? Shall I send the patch to a different list or to
> Commitfest 2019-03?

This is a pretty complicated issue with a lot of back-story.  I am
thinking Tatsuo or me will probably commit it before March.

---------------------------------------------------------------------------

---

From: Tatsuo Ishii <[email-masked]>
Date: Thu, 24 Jan 2019 10:09:21 +0900 (JST)

> thinking Tatsuo or me will probably commit it before March.

Maybe I am missing in the discussion, but I realized that the patch
does not include something like "figure number". I think it would be
convenient for users to find that in the index.

BTW, the patch has some trailing spaces.

Best regards,

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 25 Jan 2019 10:39:28 +0100

> thinking Tatsuo or me will probably commit it before March.

Isn't that all the more reason to add it to the commitfest?

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 25 Jan 2019 08:45:14 -0500

> Isn't that all the more reason to add it to the commitfest?

Uh, if you think so.  Please add it then.

---

From: Tatsuo Ishii <[email-masked]>
Date: Sat, 26 Jan 2019 10:32:12 +0900 (JST)

+1.

---

From: Jürgen Purtz <[email-masked]>
Date: Tue, 5 Feb 2019 21:10:21 +0100

> Isn't that all the more reason to add it to the commitfest?
I added it to commitfest 2019-03.

In the attachment you find a new patch which extends the first one in 
regards of three topics:

  * Index terms for each graphic
  * List of figures in the TOC for HTML and PDF output
  * More or less a side-effect: List of tables and examples for HTML.
    This already exists for PDF.
  * (In a future version there may also be a 'List of Program-Listings'.
    But this requires some more actions.)

Kind regards, Jürgen Purtz

 
 
 ##
 ## Man pages
 
 html: html-stamp

 
 # single-page HTML

 
 
-%.pdf: %.fo

 epub: postgres.epub

 installdirs:
 
 # If the install used a man directory shared with other applications, this will remove all files.
 uninstall:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4930ec17f6..fe83c46d2c 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11228,17 +11228,18 @@ table2-mapping
 
    <para>
     As an example of using the output produced by these functions,
-    <xref linkend="xslt-xml-html"/> shows an XSLT stylesheet that
-    converts the output of
+    the following <xref linkend="xslt-xml-html"/> shows
+    an XSLT stylesheet that converts the output of
     <function>table_to_xml_and_xmlschema</function> to an HTML
     document containing a tabular rendition of the table data.  In a
     similar manner, the results from these functions can be
     converted into other XML-based formats.
    </para>
 
-   <figure id="xslt-xml-html">
+   <formalpara id="xslt-xml-html" xreflabel="listing">
     <title>XSLT Stylesheet for Converting SQL/XML Output to HTML</title>
-<programlisting><![CDATA[
+    <para>
+    <programlisting><![CDATA[
 <?xml version="1.0"?>
 <xsl:stylesheet version="1.0"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
@@ -11284,7 +11285,8 @@ table2-mapping
 
 </xsl:stylesheet>
 ]]></programlisting>
-   </figure>
+   </para>
+   </formalpara>
   </sect2>
  </sect1>
 
index cc7cd1ed2c..75dbbf36df 100644
@@ -453,6 +453,23 @@
 
+ <figure id="gin_implementation_svg">
+  <title>GIN Overview</title>
+  <indexterm>
+   <primary>index</primary>
+   <secondary>GIN</secondary>
+   <tertiary>GIN (Figure)</tertiary>
+  </indexterm>
+  <mediaobject>
+   <imageobject role="html">
+    <imagedata fileref="svg/gin.svg" format="SVG" align="center" />
+   </imageobject>
+   <imageobject role="fo">
+    <imagedata fileref="svg/gin.svg" format="SVG" scale="70" />
+   </imageobject>
+  </mediaobject>
+ </figure>
+
  <sect2 id="gin-fast-update">
   <title>GIN Fast Update Technique</title>
 
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 96d196d229..06d270aed6 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -280,6 +280,22 @@
 
  </part>
 
+ <part>
+  <title>Lists of Figures, Tables and Examples</title>
+  <appendix id="list-of-figures">
+   <title>List of Figures</title>
+   <para />
+  </appendix>
+  <appendix id="list-of-tables">
+   <title>List of Tables</title>
+   <para />
+  </appendix>
+  <appendix id="list-of-examples">
+   <title>List of Examples</title>
+   <para />
+  </appendix>
+ </part>
+
  &biblio;
  <index id="bookindex"></index>
 
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 9e0bb93f08..d31ee2d210 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -73,6 +73,21 @@ PostgreSQL documentation
    architectures.
   </para>
 
+  <figure id="pg_dump_svg">
+   <title><command>pg_dump</command>: Formats and Restore Proceedings</title>
+   <indexterm><primary>pg_dump</primary>
+              <secondary>Formats and Restore Proceedings (Figure)</secondary>
+   </indexterm>
+   <mediaobject>
+    <imageobject role="html">
+     <imagedata fileref="svg/pgDump.svg" format="SVG" align="center" />
+    </imageobject>
+    <imageobject role="fo">
+     <imagedata fileref="svg/pgDump.svg" format="SVG" scale="70" />
+    </imageobject>
+   </mediaobject>
+  </figure>
+
   <para>
    When used with one of the archive file formats and combined with
    <application>pg_restore</application>,
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 8ef2ac8010..194e53d111 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -775,6 +775,19 @@ data. Empty in ordinary tables.</entry>
 </tgroup>
 </table>
 
+ <figure id="PageLayoutSVG">
+  <title>Overall Page Layout</title>
+  <indexterm><primary>Page Layout (Figure)</primary></indexterm>
+  <mediaobject>
+   <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>
 
   The first 24 bytes of each page consists of a page header
diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index 6d26e7e5c9..c95b64f212 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -86,4 +86,28 @@
   <xsl:text>?</xsl:text>
 </xsl:template>
 
+
+<!--  List of Figures and more  -->
+<xsl:template match="/book/part/appendix[@id='list-of-figures']/para">
+  <xsl:call-template name="list.of.titles">
+    <xsl:with-param name="titles" select="'figure'"/>
+    <xsl:with-param name="nodes" select="//figure"/>
+  </xsl:call-template>
+</xsl:template>
+
+<xsl:template match="/book/part/appendix[@id='list-of-tables']/para">
+  <xsl:call-template name="list.of.titles">
+    <xsl:with-param name="titles" select="'table'"/>
+    <xsl:with-param name="nodes" select="//table"/>
+  </xsl:call-template>
+</xsl:template>
+
+<xsl:template match="/book/part/appendix[@id='list-of-examples']/para">
+  <xsl:call-template name="list.of.titles">
+    <xsl:with-param name="titles" select="'example'"/>
+    <xsl:with-param name="nodes" select="//example"/>
+  </xsl:call-template>
+</xsl:template>
+
+
 </xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl
index ffd2012e91..9e756708f5 100644
--- a/doc/src/sgml/stylesheet-html-nochunk.xsl
+++ b/doc/src/sgml/stylesheet-html-nochunk.xsl
@@ -9,4 +9,27 @@
 <xsl:include href="stylesheet-html-common.xsl" />
 <xsl:include href="stylesheet-speedup-xhtml.xsl" />
 
+<!--
+  Integrate SVG and MathML files into the nochunk version (one single HTML file).
+  After migrating to Docbook 5.x this template becomes superfluous.
+-->
+<xsl:template match="imagedata">
+  <xsl:variable name="filename">
+    <xsl:call-template name="mediaobject.filename">
+      <xsl:with-param name="object" select=".."/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:choose>
+    <!-- Handle MathML and SVG markup in imagedata -->
+    <xsl:when xmlns:mml="http://www.w3.org/1998/Math/MathML" test="mml:*">
+      <xsl:apply-templates/>
+    </xsl:when>
+    <xsl:when xmlns:svg="http://www.w3.org/2000/svg" test="svg:*">
+      <xsl:apply-templates/>
+    </xsl:when>
+  </xsl:choose>
+  <xsl:copy-of select="document($filename)"/>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet-speedup-common.xsl b/doc/src/sgml/stylesheet-speedup-common.xsl
index e3fb582a1c..93a4251496 100644
--- a/doc/src/sgml/stylesheet-speedup-common.xsl
+++ b/doc/src/sgml/stylesheet-speedup-common.xsl
@@ -91,6 +91,19 @@
   </xsl:choose>
 </xsl:template>
 
+<!--  pure sequential numbering of figures ('pg_dump' and others does not have a chapter number)  -->
+<xsl:template match="figure" mode="label.markup">
+  <xsl:choose>
+    <xsl:when test="@label">
+      <xsl:value-of select="@label"/>
+    </xsl:when>
+    <xsl:otherwise>
+     <!-- Use simple sequential numbering within a book -->
+     <xsl:number format="1" from="book" level="any"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
 <!-- from common/l10n.xsl -->
 
 <!-- Just hardcode the language for the whole document, to make it faster. -->
index 0000000000..511a7f1c45

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 7 Feb 2019 12:06:14 +0100

First, let's fix some of these whitespace errors:

firstSvg_2.patch:677: trailing whitespace.
  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%"
firstSvg_2.patch:752: trailing whitespace.
  <rect x="1" y="1" width="99.4%" height="99.4%" rx="1%"
firstSvg_2.patch:705: new blank line at EOF.
+
firstSvg_2.patch:936: new blank line at EOF.
+
warning: 4 lines add whitespace errors.

Let's not use mixed-case file names:

Inkscape/
PageLayout.svg
gin.svg
pgDump.svg

> +%.pdf: %.fo $(ALLSGML) $(SVGSRC)

This seems a bit wrong.  The .fo target does depend on ALLSGML.  The
.pdf target does not, but it presumably does depend on SVGSRC.

The variable name SVGSRC is a bit confusing.  What is it the source of?

>  # If the install used a man directory shared with other applications, this will remove all files.

html/svg is not an installation directory.  You need to create it
somewhere else.

> +   <title>List of Examples</title>

These ought to be created by the stylesheet.  We have probably turned
them off somewhere, so you should see where you can turn them on.

> @@ -73,6 +73,21 @@

This doesn't work for man page output.

I think we should avoid putting images into reference pages.  This one
could perhaps go into the Backup chapter.

Also, it should be linked to from somewhere.  An image that's just
floating around and not referred to in the text seems odd.

Also we tend to use hyphens instead of underscores for IDs.  (At some
point, underscores where not allowed.  I'm surprised that that's no
longer the case.)  I also wouldn't put "_svg" into the ID.  The format
is irrelevant to the ID.

---

From: Jürgen Purtz <[email-masked]>
Date: Thu, 7 Feb 2019 18:11:08 +0100

> warning: 4 lines add whitespace errors.

Done.

> Let's not use mixed-case file names:
Done.
> .pdf target does not, but it presumably does depend on SVGSRC.
It's a transitive dependency: the pdf target is triggered after changes 
in svg (or sgml), this triggers the fo targets. Therefore it's not 
necessary to have svg (or sgml) dependencies at the fo level.
> The variable name SVGSRC is a bit confusing.  What is it the source of?
The variable SVGSRC points to all svg-files, similar to ALLSGML which 
points to the sgml files. Whenever any of them changes, certain targets 
will fire.
> html/svg is not an installation directory.  You need to create it
Please help. I haven't understood the distinction between installation 
directory and DESTDIR. On the other hand, in the Makefile there is a - 
redundant - command within the html-stamp target: $(MKDIR_P) html/svg. 
But this will run frequently, which is not necessary.
> them off somewhere, so you should see where you can turn them on.

There is a simple mechanism to create those list of figures: change line 
55 of stylesheet-html-common.xsl to "book toc,title,*figure*". But the 
result is ugly - see attached screenshot. The list is out-of-line. 
Additionally, in the future we will have many figures (and examples and 
tables). This will lead to similar problems we actually faced with the 
release notes. The proposed solution moves this inflation of lists to 
deeper levels of the TOC. We can and have defined theirs layout within 
stylesheet-common.xsl.

> could perhaps go into the Backup chapter.

What is the problem here? Actually I don't have enough time to evaluate 
it in deep. If it is an urgent problem (I have seen that the 
commitfest-entry is tagged as "release 12") we shall shift the pg_dump 
figure to a later release.

I think that the Backup chapter isn't a good place for this because it 
does not explain the complete interaction between pg_dump, psql and restore.

> longer the case.)
Done. (But I hate the use of the minus-signs within any identifier of 
any language. For me it's an operator.)
>    I also wouldn't put "_svg" into the ID.  The format
> is irrelevant to the ID.
>
I changed _svg to _figure. I agree that the format is irrelevant. But it 
may be of interest, whether it is an id to a text or a figure.

Kind regards, Jürgen

index 8326c7c673..1179d29096 100644

 
 ##
 ## Man pages
 
 html: html-stamp

 
 # single-page HTML

 
 
-%.pdf: %.fo

 epub: postgres.epub

 installdirs:
-	$(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))
+	$(MKDIR_P) '$(DESTDIR)$(htmldir)'/html/svg $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum))

    <para>

 </xsl:stylesheet>
 ]]></programlisting>
-   </figure>
+   </para>
+   </formalpara>
   </sect2>
  </sect1>
 
index cc7cd1ed2c..7e49254afe 100644
 
+ <figure id="gin-implementation-figure">

  </part>
 
+ <part>
 
index 9e0bb93f08..a6c91e68ef 100644
 
+  <figure id="pg-dump-figure">
+   <title><command>pg_dump</command>: Formats and Restore Proceedings</title>
+   <indexterm><primary>pg_dump</primary>
+              <secondary>Formats and Restore Proceedings (Figure)</secondary>
+   </indexterm>
+   <mediaobject>
+    <imageobject role="html">
+     <imagedata fileref="svg/pgdump.svg" format="SVG" align="center" />
+    </imageobject>
+    <imageobject role="fo">
+     <imagedata fileref="svg/pgdump.svg" format="SVG" scale="70" />
+    </imageobject>
+   </mediaobject>
+  </figure>
+
   <para>
    When used with one of the archive file formats and combined with
    <application>pg_restore</application>,
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index cbdad0c3fb..d630366a9a 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -776,6 +776,19 @@ data. Empty in ordinary tables.</entry>
 </tgroup>
 </table>
 
+ <figure id="page-layout-figure">
+  <title>Overall Page Layout</title>
+  <indexterm><primary>Page Layout (Figure)</primary></indexterm>
+  <mediaobject>
+   <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>

+
 
+<!--

index 0000000000..9ea11f8b1f
diff --git a/doc/src/sgml/svg/inkscape/gin_inkscape.svg b/doc/src/sgml/svg/inkscape/gin_inkscape.svg
+++ b/doc/src/sgml/svg/inkscape/gin_inkscape.svg
diff --git a/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg b/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg
+++ b/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg
diff --git a/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg b/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg
+++ b/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg
diff --git a/doc/src/sgml/svg/pagelayout.svg b/doc/src/sgml/svg/pagelayout.svg
index 0000000000..223fcaf749
+++ b/doc/src/sgml/svg/pagelayout.svg
@@ -0,0 +1,74 @@
diff --git a/doc/src/sgml/svg/pgdump.svg b/doc/src/sgml/svg/pgdump.svg
index 0000000000..5cf171de0e
+++ b/doc/src/sgml/svg/pgdump.svg
@@ -0,0 +1,95 @@

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 8 Feb 2019 09:01:09 +0100

> necessary to have svg (or sgml) dependencies at the fo level.

If $(ALLSGML) changes, then the .fo file needs to be rebuilt.  If
$(SVGSRC) changes, then the .pdf file needs to be rebuilt.  So those two
groups of files need to be handled differently.  The way you have
written it, a change in $(ALLSGML) will just rebuild the .pdf file from
a stale .fo.

> points to the sgml files. Whenever any of them changes, certain targets

Right, so maybe name it ALLSVG?

> But this will run frequently, which is not necessary.

Right, so you probably don't need this change in the installdirs target
at all.

> 55 of stylesheet-html-common.xsl to "book      toc,title,*figure*". But
> the result is ugly - see attached screenshot. The list is out-of-line.
> release notes.

Maybe we don't need a list of figures at all?  Let's just turn it off if
we don't like it.

> figure to a later release.

The problem is that images don't show up in man pages, so we can't put
any images in there, or it will look silly.

> does not explain the complete interaction between pg_dump, psql and restore.

Then maybe it should explain it.  The pg_dump man page should be
strictly about pg_dump.  The Backup chapter should explain how it fits
together with the other tools.

---

From: Jürgen Purtz <[email-masked]>
Date: Fri, 15 Feb 2019 11:58:46 +0100

The graphic for dump/restore is transferred from 'pg_dump utility' 
chapter to the 'backup and restore' chapter in sgml/backup.sgml. In this 
chapter I made a lot of textual changes to explain the relation between 
pg_dump, pg_restore and psql in more detail. Especially I tried to 
introduce a more stringent use of terms, eg: avoiding 'archive' because 
this term is used with a different meaning in the PITR chapter. (It 
would be a good idea to do the same for the description of the pg_dump 
utility.) Because I'm not a native English speaker, feel free to correct 
my wording.

The list of figures as well as lists of other prominent elements are 
removed. 'lists in TOC' seems to be a topic of its own and will be 
resumed later.

Kind regards, Jürgen

index 8326c7c673..12997e903c 100644

+ALLSVG := $(wildcard $(srcdir)/svg/*.svg)
+
 
 ##
 ## Man pages
 
 html: html-stamp
 
+html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALLSVG)
+	cp $(ALLSVG) html/svg
 	touch $@

 # single-page HTML
-postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML)
+postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) $(ALLSVG)
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
 
@@ -160,7 +164,7 @@ postgres.pdf:
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
 
-%.pdf: %.fo
+%.pdf: %.fo $(ALLSVG)
 	$(FOP) -fo $< -pdf $@

 epub: postgres.epub
-postgres.epub: postgres.sgml $(ALLSGML)
+postgres.epub: postgres.sgml $(ALLSGML) $(ALLSVG)
 	$(XMLLINT) --noout --valid $<
 	$(DBTOEPUB) $<
 
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index a73fd4d044..f192ea3b52 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -16,7 +16,7 @@
   There are three fundamentally different approaches to backing up
   <productname>PostgreSQL</productname> data:
   <itemizedlist>
-   <listitem><para><acronym>SQL</acronym> dump</para></listitem>
+   <listitem><para>Dump into <acronym>SQL INSERT</acronym> syntax or a binary format</para></listitem>
    <listitem><para>File system level backup</para></listitem>
    <listitem><para>Continuous archiving</para></listitem>
   </itemizedlist>
@@ -25,23 +25,28 @@
  </para>
 
  <sect1 id="backup-dump">
-  <title><acronym>SQL</acronym> Dump</title>
+  <title>Dump</title>
 
   <para>
-   The idea behind this dump method is to generate a file with SQL
-   commands that, when fed back to the server, will recreate the
-   database in the same state as it was at the time of the dump.
+   The idea behind this dump technique is to generate a file
+   that, when fed back to the server, will recreate the
+   database in the same state as it was at the time of the dump generation.
+  </para>
+
+  <sect2>
+   <title>Creating the Dump</title>
+  <para>
    <productname>PostgreSQL</productname> provides the utility program
    <xref linkend="app-pgdump"/> for this purpose. The basic usage of this
    command is:
 <synopsis>
 pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable class="parameter">dumpfile</replaceable>
 </synopsis>
-   As you see, <application>pg_dump</application> writes its result to the
+   As you see, <application>pg_dump</application> in this basic form writes its result to the
    standard output. We will see below how this can be useful.
-   While the above command creates a text file, <application>pg_dump</application>
-   can create files in other formats that allow for parallelism and more
-   fine-grained control of object restoration.
+   While the above command creates a plain-text SQL script, <application>pg_dump</application>
+   can create files also in other, dense binary formats that allow for parallelism and more
+   fine-grained control of object restoration, see: <xref linkend="backup-dump-binary"/>
   </para>
 
   <para>
@@ -100,12 +105,13 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
    (Exceptions are those operations that need to operate with an
    exclusive lock, such as most forms of <command>ALTER TABLE</command>.)
   </para>
+  </sect2>
 
   <sect2 id="backup-dump-restore">
    <title>Restoring the Dump</title>
 
    <para>
-    Text files created by <application>pg_dump</application> are intended to
+    Such plain-text SQL scripts created by <application>pg_dump</application> are intended to
     be read in by the <application>psql</application> program. The
     general command form to restore a dump is
 <synopsis>
@@ -121,8 +127,6 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
     supports options similar to <application>pg_dump</application> for specifying
     the database server to connect to and the user name to use. See
     the <xref linkend="app-psql"/> reference page for more information.
-    Non-text file dumps are restored using the <xref
-    linkend="app-pgrestore"/> utility.
    </para>
 
    <para>
@@ -239,12 +243,12 @@ psql -f <replaceable class="parameter">dumpfile</replaceable> postgres
     Some operating systems have maximum file size limits that cause
     problems when creating large <application>pg_dump</application> output files.
     Fortunately, <application>pg_dump</application> can write to the standard
-    output, so you can use standard Unix tools to work around this
+    output, so you can use standard tools to work around this
     potential problem.  There are several possible methods:
    </para>
 
    <formalpara>
-    <title>Use compressed dumps.</title>
+    <title>Compress dumps.</title>
     <para>
      You can use your favorite compression program, for example
      <application>gzip</application>:
@@ -268,7 +272,7 @@ cat <replaceable class="parameter">filename</replaceable>.gz | gunzip | psql <re
    </formalpara>
 
    <formalpara>
-    <title>Use <command>split</command>.</title>
+    <title>Split dumps.</title>
     <para>
      The <command>split</command> command
      allows you to split the output into smaller files that are
@@ -287,22 +291,57 @@ cat <replaceable class="parameter">filename</replaceable>* | psql <replaceable c
     </para>
    </formalpara>
 
-   <formalpara>
-    <title>Use <application>pg_dump</application>'s custom dump format.</title>
+   <formalpara id="backup-dump-binary">
+    <title>Use binary formats.</title>
+    <para>
+     In addition to the above mentioned plain-text SQL script format <application>pg_dump</application>
+     can create its output files in denser, binary formats: <literal>custom</literal>,
+     <literal>directory</literal>, and <literal>tar</literal>.
+     Dumps in such binary formats are restored using the utility program
+     <xref linkend="app-pgrestore"/> instead of <application>psql</application>.
+    </para>
+   </formalpara>
+
+   <para>
+    <figure id="pg-dump-figure">
+     <title><command>pg_dump</command>, <command>psql</command>, and <command>pg_restore</command>:
+     Dump Formats and Restore Proceedings</title>
+     <indexterm><primary>pg_dump</primary>
+                <secondary>Dump Formats and Restore Proceedings (Figure)</secondary>
+     </indexterm>
+     <indexterm><primary>pg_restore</primary>
+                <secondary>Dump Formats and Restore Proceedings (Figure)</secondary>
+     </indexterm>
+     <indexterm><primary>backup</primary>
+                <secondary>Dump Formats and Restore Proceedings (Figure)</secondary>
+     </indexterm>
+     <mediaobject>
+      <imageobject role="html">
+       <imagedata fileref="svg/pgdump.svg" format="SVG" align="center" />
+      </imageobject>
+      <imageobject role="fo">
+       <imagedata fileref="svg/pgdump.svg" format="SVG" scale="70" />
+      </imageobject>
+     </mediaobject>
+    </figure>
+   </para>
+
     <para>
      If <productname>PostgreSQL</productname> was built on a system with the
-     <application>zlib</application> compression library installed, the custom dump
+     <application>zlib</application> compression library installed, the
+     <literal>custom</literal> dump
      format will compress data as it writes it to the output file. This will
      produce dump file sizes similar to using <command>gzip</command>, but it
      has the added advantage that tables can be restored selectively. The
-     following command dumps a database using the custom dump format:
+     following command dumps a database using the <literal>custom</literal> dump format:
 
 <programlisting>
 pg_dump -Fc <replaceable class="parameter">dbname</replaceable> &gt; <replaceable class="parameter">filename</replaceable>
 </programlisting>
 
-     A custom-format dump is not a script for <application>psql</application>, but
-     instead must be restored with <application>pg_restore</application>, for example:
+     As mentioned above dumps in <literal>custom</literal> format are binary
+     and not plain-text SQL scripts, they must be restored with <application>pg_restore</application>
+     instead of <application>psql</application>, for example:
 
 <programlisting>
 pg_restore -d <replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">filename</replaceable>
@@ -311,11 +350,10 @@ pg_restore -d <replaceable class="parameter">dbname</replaceable> <replaceable c
      See the <xref linkend="app-pgdump"/> and <xref
      linkend="app-pgrestore"/> reference pages for details.
     </para>
-   </formalpara>
 
    <para>
     For very large databases, you might need to combine <command>split</command>
-    with one of the other two approaches.
+    with one of the other approaches.
    </para>
 
    <formalpara>
@@ -325,15 +363,16 @@ pg_restore -d <replaceable class="parameter">dbname</replaceable> <replaceable c
      <application>pg_dump</application>'s parallel mode. This will dump
      multiple tables at the same time. You can control the degree of
      parallelism with the <command>-j</command> parameter. Parallel dumps
-     are only supported for the "directory" archive format.
+     are only supported for the <literal>directory</literal> format.
 
 <programlisting>
 pg_dump -j <replaceable class="parameter">num</replaceable> -F d -f <replaceable class="parameter">out.dir</replaceable> <replaceable class="parameter">dbname</replaceable>
 </programlisting>
 
      You can use <command>pg_restore -j</command> to restore a dump in parallel.
-     This will work for any archive of either the "custom" or the "directory"
-     archive mode, whether or not it has been created with <command>pg_dump -j</command>.
+     This will work for any dump output of either the <literal>custom</literal>
+     or the <literal>directory</literal> 
+     format, whether or not it has been created with <command>pg_dump -j</command>.
     </para>
    </formalpara>
   </sect2>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 86ff4e5c9e..ef299dd7f3 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11228,17 +11228,18 @@ table2-mapping
 
    <para>

 </xsl:stylesheet>
 ]]></programlisting>
-   </figure>
+   </para>
+   </formalpara>
   </sect2>
  </sect1>

 

 
+<!--
index 0000000000..967ca9966a
+  <text x="20" y="60" class="text_normal" id="text35">pg_dump, plain-text format</text>
+  <text x="340" y="60" class="text_normal" id="text39">pg_dump, other formats</text>
index 0000000000..c327136de4
+  <text x="20" y="60" class="text_normal">pg_dump, plain-text format</text>
+  <text x="340" y="60" class="text_normal">pg_dump, other formats</text>

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 20 Feb 2019 17:28:50 +0100

> utility.) Because I'm not a native English speaker, feel free to correct 

I think we should have some in-tree documentation about how to edit
images, probably at doc/src/sgml/svg/README.  You had published some of
that documentation earlier in this thread, and whatever is relevant to
developers should be included in the tree.  I'm specifically wondering
about the relationship between the *.svg and the inkscape/*.svg files.

---

From: Jürgen Purtz <[email-masked]>
Date: Sat, 23 Feb 2019 18:06:55 +0100

> about the relationship between the *.svg and the inkscape/*.svg files.

Good idea. README is created. Also chapter "J.4. Documentation 
Authoring" has some enhancements to differentiate between text and 
graphic. It's also possible that we will see more sub-chapters in J.4 in 
the future, e.g.: "Creating Mathematical Formulas".

Kind regards, Jürgen

 
 
 ##
 ## Man pages
 
 html: html-stamp

 
 # single-page HTML

-%.pdf: %.fo
+%.pdf: %.fo $(ALLSVG)
 	$(FOP) -fo $< -pdf $@

 epub: postgres.epub

  <sect1 id="backup-dump">
 
   <para>
 
   <para>

    <para>
 
    <para>
 
    <formalpara>
 
    <formalpara>
 
-   <formalpara>
 
 <programlisting>

 <programlisting>
 
    <para>
 
    <formalpara>
 
 <programlisting>
 
      You can use <command>pg_restore -j</command> to restore a dump in parallel.
-     This will work for any archive of either the "custom" or the "directory"
-     archive mode, whether or not it has been created with <command>pg_dump -j</command>.
+     This will work for any dump output of either the <literal>custom</literal>
+     or the <literal>directory</literal> 
+     format, whether or not it has been created with <command>pg_dump -j</command>.
     </para>
    </formalpara>
   </sect2>
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 0608b8c612..5ccc24833e 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -389,21 +389,21 @@ ADDITIONAL_FLAGS='-Xmx1500m'
   <title>Documentation Authoring</title>
 
    <para>
-    The documentation sources are most conveniently modified with an editor
-    that has a mode for editing XML, and even more so if it has some awareness
-    of XML schema languages so that it can know about
-    <productname>DocBook</productname> syntax specifically.
-   </para>
-
-   <para>
-    Note that for historical reasons the documentation source files are named
+    Note that for historical reasons most of the documentation source files are named
     with an extension <filename>.sgml</filename> even though they are now XML
     files.  So you might need to adjust your editor configuration to set the
     correct mode.
    </para>
 
    <sect2>
-    <title>Emacs</title>
+    <title>Textual Parts and Emacs</title>
+
+    <para>
+     The documentation's textual parts are most conveniently modified with an editor
+     that has a mode for editing XML, and even more so if it has some awareness
+     of XML schema languages so that it can know about
+     <productname>DocBook</productname> syntax specifically.
+    </para>
 
     <para>
      <productname>nXML Mode</productname>, which ships with
@@ -422,6 +422,43 @@ ADDITIONAL_FLAGS='-Xmx1500m'
     </para>
    </sect2>
 
+   <sect2>
+    <title>Graphic Elements</title>
+
+    <para>
+     Graphics - which are a <literal>figure</literal> in Docbook speach
+     - visualize complex situations or behaviour. They provide an
+     additional way for easy understanding what is described in the
+     text parts. Authors create them in <acronym>SVG</acronym> format
+     with any SVG tool of their choice.
+    </para>
+
+    <para>
+     Such tools show two disadvantages: They tend to use their own,
+     unportable enhancements and they produce extremely verbose,
+     unreadable source files. To overcome such drawbacks authors
+     shall create two files for every single graphic: one in
+     <literal>Optimized SVG</literal> format and another one in the
+     tool-specific <acronym>SVG</acronym> format. Both files
+     render to the same graphic. This enables 'diff-ability' (on the
+     <literal>Optimized SVG</literal> file) as well as the use of the
+     powerful tool-specific variant in any future. Both files are
+     stored in the repository, but only the <literal>Optimized SVG</literal>
+     variant is the liable one and included into the
+     <productname>PostgreSQL</productname> documentation.
+    </para>
+
+    <para>
+     This approach as well as the overall directory structure is
+     explained in more detail in <filename>doc/src/sgml/svg/README</filename>.
+     In addition, there are many more hints in
+     <productname>PostgreSQL</productname>'s wiki within the
+     <ulink url="https://wiki.postgresql.org/wiki/Category:SVG">
+     category SVG</ulink>.
+    </para>
+
+   </sect2>
+
  </sect1>

    <para>

 </xsl:stylesheet>
 ]]></programlisting>
-   </figure>
+   </para>
+   </formalpara>
   </sect2>
  </sect1>

 

 
+<!--
diff --git a/doc/src/sgml/svg/README b/doc/src/sgml/svg/README
index 0000000000..c4bd61151d
+++ b/doc/src/sgml/svg/README
@@ -0,0 +1,93 @@
+<!-- doc/src/sgml/svg/README -->
+Graphics in PG ('figure' in Docbook speach) use the SVG
+format. PG stores two different SVG files per graphic in
+the repository: a simple, more generic one to create the
+documentation and a tool-specific one for future modifications
+of the graphic. The reason for this approach and the directory
+layout are explained here.
+A more detailed description concerning the creation of graphics
+(compatibility rules, fonts, sizes, colors, general hints,
+tool-specific hints, ...) are listed in the wiki under the
+category 'SVG':
+  https://wiki.postgresql.org/wiki/Category:SVG
+Two files per graphic
+=====================
+An author can use any SVG tool of his choice to create SVG graphics.
+However, these tools create tool-specific SVG files which suffer
+from some major disadvantages:
+  - they are tool-specific
+  - they tend to use the tool's own, unportable enhancements  and
+  - they produce extremely verbose, unreadable source files.
+To overcome such disadvantages authors shall store two different
+files per graphic after they have finished their work: one in the
+original tool-specific format and another one in a simple,
+less powerful but portable and short format, which is mostly
+called the 'Optimized SVG' format. This format typically misses
+enhanced features like 'connectors' or 'groups'.
+Both files render to the same graphic. Both are stored in the
+repository, but only the 'Optimized SVG' variant is the liable
+one and included into the generated PostgreSQL documentation.
+For future versions of the graphic the tool-specific file
+can be used as the basis of enhancements. The 'Optimized SVG'
+file serves for diffs.
+The 'Optimized SVG' file is mandatory, the tool-specific
+one is optional.
+Directory Structure
+===================
+The text files, which include the graphics, reside - as usual -
+in doc/src/sgml. The SVG files, which are included by the text
+files and used for the documentation generation, reside in
+doc/src/sgml/, their tool-specific counterpart in subdirectories,
+which reflect the name of the tool:
+doc/src/sgml/                # usual text files with extension .sgml
+doc/src/sgml/svg             # SVG files in 'Optimized SVG' format
+doc/src/sgml/svg/inkscape    # SVG files in Inkscape specific format
+doc/src/sgml/svg/<toolname>  # SVG files in the format of another tool
+        ...
+        ...
+Limitation
+==========
+Man pages are created out of files in the sgml/ref/ subdirectory.
+If such a file contains a graphic, the generated man page looks
+a little ugly. Please avoid such situations and include graphics
+only into files of the sgml/ directory.
+Include graphics in text
+========================
+Graphics (<figure> element) can be included in <para> and in many other
+Docbook elements, e.g.:
+<para>
+ lorem ipsum ...
+ lorem ipsum ...
+</para>

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 8 Mar 2019 16:55:41 +0100

How do you get from the Inkscape SVG files to the what you call
"optimized SVG" files?

I loaded the gin_inkscape.svg file into Inkscape, saved it back out as
"Plain SVG", but the resultant file did not look at all similar to the
existing gin.svg.

---

From: Jürgen Purtz <[email-masked]>
Date: Sat, 9 Mar 2019 14:17:33 +0300

> "Plain SVG", but the resultant file did not look at all similar to the
Inkscape supports a lot of different formats. "Plain SVG" and "Optimized 
SVG" are two of them - and they differ in some aspects. "Plain SVG" is 
in some respect garrulous and generates unnecessary elements: 
namespaces, metadata, IDs, XML-entities. "Optimized SVG" avoids them, as 
long as you follow the hints described in 
https://wiki.postgresql.org/wiki/SVG_using_Inkscape. Conclusion: People 
working with Inkscape shall avoid "Plain SVG" and use "Optimized SVG".

Nevertheless Peter points out an important aspect. If you generate 
"Optimized SVG" out of the uploaded files, they look different in 
comparison to their original version. As mentioned in 
https://wiki.postgresql.org/wiki/SVG_using_Inkscape#Manual_corrections, 
it is possible - and sometimes advised - to manually 'optimize' the 
generated "Optimized SVG" file. I used this technique and tried to make 
the files good readable for everyone, especially because we are in an 
early phase of SVG integration. But apparently I have overstressed this 
possibility. You will find the following differences between the 
uploaded 'additionally manually optimized' files and the generated 
"Optimized SVG" files:

    - newlines

   - <g stroke="black"> element. This is an Inkscape optimization, which 
generates a group out of those elements, which are in a sequence and use 
- by chance - the same stroke-attribute. This optimization step is 
purely formal and in my opinion misuses the meaning of the <g> element 
as a cramp for logically related elements, e.g. to resize or transform 
them simultaneously.

As an example of such differences I append two files: gin.svg 
("Optimized SVG" plus my manually optimizations; the originally uploaded 
file) and gin_pure_opt.svg (pure "Optimized SVG").

What is your opinion? Should we renounce the additional manual step and 
use only the pure "Optimized SVG" format? This will increase the 
'diff-ablility', which may be valuable in the long term. But direct 
readability of the files suffers more or less.

Kind regards, Jürgen

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 9 Mar 2019 10:54:11 -0500

On Sat, Mar  9, 2019 at 02:17:33PM +0300, Jürgen Purtz wrote:
> As an example of such differences I append two files: gin.svg ("Optimized
> SVG" plus my manually optimizations; the originally uploaded file) and
> gin_pure_opt.svg (pure "Optimized SVG").
> 
> What is your opinion? Should we renounce the additional manual step and use
> only the pure "Optimized SVG" format? This will increase the

Uh, so really there is plain SVG, "Optimized SVG", and readable SVG.  I
am thinking you should store just "Optimized SVG", and provide a shell
script to convert to readable SVG for those that want it.

---

From: Tom Lane <[email-masked]>
Date: Sat, 09 Mar 2019 11:49:31 -0500

> script to convert to readable SVG for those that want it.

Man, this discussion is leaving me disheartened.  It sure sounds like
we are going to end up in a situation where either everyone touching
the graphics has to use the same version of the same tool (with the
same options, even), or else we're going to have massive, unreadable,
and mostly content-free diffs in every patch.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 9 Mar 2019 12:39:07 -0500

> and mostly content-free diffs in every patch.

Yes, that might end up being the case.  I think the only saving part is
that we aren't going to have lots of people editing the graphics.

---

From: Jürgen Purtz <[email-masked]>
Date: Sun, 10 Mar 2019 15:44:20 +0300

Please forget the term "plain SVG". What we are speaking about is:

(1) "Inkscape-original" format

(2) "Optimized SVG" format

(3) No. (2) plus"Manually modifications".

Obviously this is too complicate to handle. Therefore we shall also 
forget no. (3).

I made a small modification to the generation process of (2) by throwing 
the comments away (it's actually not documented in the wiki): "Save As" 
/ "Optimized SVG Output" / "SVG Output" tab / "Remove comments" 
checkbox. The result is an easy readable file, without comments, without 
empty lines, diff-ing is easy. The only drawback is the strange <g 
stroke="black"> element, which may confuse at the first glance. But I 
can live with that. In a simple graphic it's obvious, what happens. In a 
complex graphic the likelihood of such a situation is low. Regarding 
comments, I believe tool-users will seldom use them. We can do without 
comments in the svg files of the repository.

So find two files in the attachment: format (1): gin_Inkscape.svg and 
format (2): gin.svg.

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 11 Mar 2019 10:13:47 +0100

I played with this further.  My conclusion is that SVG as a source
format is not workable.  Aside from the tooling issues that are being
discussed, which might be solvable, I think it's not the right level of
abstraction.  The problem is that it is a *vector* format, but not a
*graph* or *chart* format.  You can draw boxes and lines and text, but
nothing in the format indicates how they are connected.  You can see
that in the provided example graphs:  The alignment of the arrow tips to
the boxes and the text in the boxes is not pixel-perfect.  If you open
this in Inkscape and move a box around, the edges don't move with it.
The final appearance of the picture is subject to how shaky the hand
holding the mouse was. ;-)  I suppose experienced graphics artists have
ways to deal with that, but they are not in evidence here.  I'm thinking
of someone, say, adding a tweak to the GIN code and wanting to update
the image, and I don't see that as being pleasant.

I looked at some alternatives.  I rebuilt the GIN image using Graphviz
and the page layout image using Ditaa.  See attached patch.  The results
look fine and useful to me.  I would be much more comfortable using
those tools: They use a higher level of abstraction, so an author can
focus on the logical structure of the image and not the pixel details.
The source formats are easily diffable.  Both can convert to SVG, so the
rest of the tooling can still be used.  (I didn't find the pg_dump image
all that useful, so I didn't do anything with it here.  But I think it
could be done using either Ditaa or Graphviz.)

Using SVG as an output format looks good.  It works in HTML, PDF, and
EPUB.  I did some tweaks to your tooling so that the images scale
automatically in the PDF output.  Everything looks good, so I would be
happy to proceed in this direction.

(We can have some discussion about whether we want to commit the
intermediate SVG files and what the directory layout should be etc.   I
didn't bother with that in my patch yet.)

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
From 86c1180718e0a84d7ac757e3b8164744f95a6526 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <[email-masked]>
Date: Mon, 11 Mar 2019 09:48:00 +0100
Subject: [PATCH] doc: Add some images

---
 doc/src/sgml/Makefile                   |  25 +-
 doc/src/sgml/gin.dot                    |  93 +++++++
 doc/src/sgml/gin.sgml                   |  12 +-
 doc/src/sgml/gin.svg                    | 320 ++++++++++++++++++++++++
 doc/src/sgml/pagelayout.svg             |  40 +++
 doc/src/sgml/pagelayout.txt             |  11 +
 doc/src/sgml/storage.sgml               |  13 +
 doc/src/sgml/stylesheet-html-common.xsl |   1 +
 8 files changed, 510 insertions(+), 5 deletions(-)
 create mode 100644 doc/src/sgml/gin.dot
 create mode 100644 doc/src/sgml/gin.svg
 create mode 100644 doc/src/sgml/pagelayout.svg
 create mode 100644 doc/src/sgml/pagelayout.txt

index 2420c55681..4ca6cc0259 100644

+ALL_IMAGES = gin.svg pagelayout.svg
+
 
 ##
 ## Man pages
@@ -125,9 +127,10 @@ endif
 
 html: html-stamp
 
+html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
+	cp $(ALL_IMAGES) html/
 
@@ -136,7 +139,7 @@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
 
 # single-page HTML
-postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML)
+postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
 
@@ -160,7 +163,7 @@ postgres.pdf:
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
 
-%.pdf: %.fo
+%.pdf: %.fo $(ALL_IMAGES)
 	$(FOP) -fo $< -pdf $@

@@ -169,7 +172,7 @@ postgres.pdf:
 ##
 
 epub: postgres.epub
-postgres.epub: postgres.sgml $(ALLSGML)
+postgres.epub: postgres.sgml $(ALLSGML) $(ALL_IMAGES)
 	$(XMLLINT) --noout --valid $<
 	$(DBTOEPUB) -o $@ $<
 
@@ -193,6 +196,20 @@ MAKEINFO = makeinfo
 	$(MAKEINFO) --enable-encoding --no-split --no-validate $< -o $@

+##
+## Images
+##
+
+DITAA = ditaa
+DOT = dot
+
+%.svg: %.dot
+	$(DOT) -T svg -o $@ $<
+
+%.svg: %.txt
+	$(DITAA) -E -S --svg $< $@
+
+
 ##
 ## Check
 ##
diff --git a/doc/src/sgml/gin.dot b/doc/src/sgml/gin.dot
new file mode 100644
index 0000000000..097e91029a
--- /dev/null
+++ b/doc/src/sgml/gin.dot
@@ -0,0 +1,93 @@
+digraph "gin" {
+        layout=dot;
+        node [label="", shape=box, style=filled, fillcolor=gray, width=1.4];
+
+        m1 [label="meta page"];
+
+        subgraph cluster01 {
+                label="entry tree";
+                subgraph egroup1 {
+                        rank=same;
+                        e1;
+                }
+                subgraph egroup2 {
+                        rank=same;
+                        e2 -> e3 -> e4;
+                }
+                subgraph egroup3 {
+                        rank=same;
+                        e5 -> e6 -> e7 -> e8 -> e9;
+                }
+                e1 -> e4;
+                e1 -> e3;
+                e1 -> e2;
+                e2 -> e5;
+                e2 -> e6;
+                e3 -> e7;
+                e4 -> e8;
+                e4 -> e9;
+
+                e6 [fillcolor=green, label="posting list"];
+                e8 [fillcolor=green, label="posting list"];
+                e9 [fillcolor=green, label="posting list"];
+        }
+
+        subgraph cluster02 {
+                label="posting tree";
+                subgraph pgroup1 {
+                        rank=same;
+                        p1;
+                }
+                subgraph pgroup2 {
+                        rank=same;
+                        p2 -> p3;
+                }
+                p1 -> p2;
+                p1 -> p3;
+
+                p2 [fillcolor=green, label="heap ptr"];
+                p3 [fillcolor=green, label="heap ptr"];
+        }
+
+        subgraph cluster03 {
+                label="posting tree";
+                subgraph pgroup3 {
+                        rank=same;
+                        p4;
+                }
+
+                p4 [fillcolor=green, label="heap ptr"];
+        }
+
+        subgraph cluster04 {
+                label="posting tree";
+                subgraph pgroup4 {
+                        rank=same;
+                        p5;
+                }
+                subgraph pgroup5 {
+                        rank=same;
+                        p6 -> p7;
+                }
+                p5 -> p6;
+                p5 -> p7;
+
+                p6 [fillcolor=green, label="heap ptr"];
+                p7 [fillcolor=green, label="heap ptr"];
+        }
+
+        subgraph cluster05 {
+                label="pending list";
+                node [style=filled, fillcolor=red];
+                n1 -> n2 -> n3 -> n4;
+        }
+
+        m1 -> e1;
+        e5 -> p1;
+        e7 -> p4;
+        e7 -> p5;
+        m1 -> n1;
+
+        e5 [style=filled, fillcolor=green4];
+        e7 [style=filled, fillcolor=green4];
+}
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index cc7cd1ed2c..8913d7d99d 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -436,7 +436,8 @@ <title>Implementation</title>
   page contains either a pointer to a B-tree of heap pointers (a
   <quote>posting tree</quote>), or a simple list of heap pointers (a <quote>posting
   list</quote>) when the list is small enough to fit into a single index tuple along
-  with the key value.
+  with the key value.  <xref linkend="gin-internals-figure"/> illustrates
+  these components of a GIN index.
  </para>
 
  <para>
@@ -453,6 +454,15 @@ <title>Implementation</title>
   key values for different columns can be of different types.
  </para>
 
+ <figure id="gin-internals-figure">
+  <title>GIN Internals</title>
+  <mediaobject>
+   <imageobject>
+    <imagedata fileref="gin.svg" format="SVG" width="100%" scalefit="1"/>
+   </imageobject>
+  </mediaobject>
+ </figure>
+
  <sect2 id="gin-fast-update">
   <title>GIN Fast Update Technique</title>
 
diff --git a/doc/src/sgml/gin.svg b/doc/src/sgml/gin.svg
new file mode 100644
index 0000000000..eacb5c8c16
--- /dev/null
+++ b/doc/src/sgml/gin.svg
@@ -0,0 +1,320 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.40.1 (20161225.0304)
+ -->
+<!-- Title: gin Pages: 1 -->
+<svg width="836pt" height="432pt"
+ viewBox="0.00 0.00 836.00 432.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 428)">
+<title>gin</title>
+<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-428 832,-428 832,4 -4,4"/>
+<g id="clust1" class="cluster">
+<title>cluster01</title>
+<polygon fill="none" stroke="#000000" points="100,-162 100,-380 694,-380 694,-162 100,-162"/>
+<text text-anchor="middle" x="397" y="-364.8" font-family="Times,serif" font-size="14.00" fill="#000000">entry tree</text>
+</g>
+<g id="clust5" class="cluster">
+<title>cluster02</title>
+<polygon fill="none" stroke="#000000" points="8,-8 8,-154 245,-154 245,-8 8,-8"/>
+<text text-anchor="middle" x="126.5" y="-138.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting tree</text>
+</g>
+<g id="clust8" class="cluster">
+<title>cluster03</title>
+<polygon fill="none" stroke="#000000" points="279,-80 279,-154 397,-154 397,-80 279,-80"/>
+<text text-anchor="middle" x="338" y="-138.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting tree</text>
+</g>
+<g id="clust10" class="cluster">
+<title>cluster04</title>
+<polygon fill="none" stroke="#000000" points="405,-8 405,-154 642,-154 642,-8 405,-8"/>
+<text text-anchor="middle" x="523.5" y="-138.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting tree</text>
+</g>
+<g id="clust13" class="cluster">
+<title>cluster05</title>
+<polygon fill="none" stroke="#000000" points="702,-80 702,-380 820,-380 820,-80 702,-80"/>
+<text text-anchor="middle" x="761" y="-364.8" font-family="Times,serif" font-size="14.00" fill="#000000">pending list</text>
+</g>
+<!-- m1 -->
+<g id="node1" class="node">
+<title>m1</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="688.5,-424 587.5,-424 587.5,-388 688.5,-388 688.5,-424"/>
+<text text-anchor="middle" x="638" y="-401.8" font-family="Times,serif" font-size="14.00" fill="#000000">meta page</text>
+</g>
+<!-- e1 -->
+<g id="node2" class="node">
+<title>e1</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="506.5,-350 405.5,-350 405.5,-314 506.5,-314 506.5,-350"/>
+</g>
+<!-- m1&#45;&gt;e1 -->
+<g id="edge24" class="edge">
+<title>m1&#45;&gt;e1</title>
+<path fill="none" stroke="#000000" d="M593.4778,-387.8976C568.2655,-377.6464 536.5468,-364.7498 509.931,-353.928"/>
+<polygon fill="#000000" stroke="#000000" points="510.9595,-350.568 500.3776,-350.0436 508.3229,-357.0525 510.9595,-350.568"/>
+</g>
+<!-- n1 -->
+<g id="node18" class="node">
+<title>n1</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-350 710.5,-350 710.5,-314 811.5,-314 811.5,-350"/>
+</g>
+<!-- m1&#45;&gt;n1 -->
+<g id="edge28" class="edge">
+<title>m1&#45;&gt;n1</title>
+<path fill="none" stroke="#000000" d="M683.1514,-387.8551C688.2504,-385.3905 693.2983,-382.7547 698,-380 709.7018,-373.1438 721.7385,-364.4455 732.115,-356.3423"/>
+<polygon fill="#000000" stroke="#000000" points="734.4083,-358.9902 740.0427,-350.0178 730.0428,-353.5181 734.4083,-358.9902"/>
+</g>
+<!-- e2 -->
+<g id="node3" class="node">
+<title>e2</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="328.5,-278 227.5,-278 227.5,-242 328.5,-242 328.5,-278"/>
+</g>
+<!-- e1&#45;&gt;e2 -->
+<g id="edge9" class="edge">
+<title>e1&#45;&gt;e2</title>
+<path fill="none" stroke="#000000" d="M411.0831,-313.8314C387.065,-304.1162 357.3166,-292.0831 332.0408,-281.8592"/>
+<polygon fill="#000000" stroke="#000000" points="333.1767,-278.5432 322.5939,-278.038 330.5518,-285.0325 333.1767,-278.5432"/>
+</g>
+<!-- e3 -->
+<g id="node4" class="node">
+<title>e3</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="447.5,-278 346.5,-278 346.5,-242 447.5,-242 447.5,-278"/>
+</g>
+<!-- e1&#45;&gt;e3 -->
+<g id="edge8" class="edge">
+<title>e1&#45;&gt;e3</title>
+<path fill="none" stroke="#000000" d="M441.1118,-313.8314C434.247,-305.454 425.9699,-295.3531 418.4489,-286.1749"/>
+<polygon fill="#000000" stroke="#000000" points="421.1341,-283.9297 412.0886,-278.4133 415.7197,-288.3665 421.1341,-283.9297"/>
+</g>
+<!-- e4 -->
+<g id="node5" class="node">
+<title>e4</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="566.5,-278 465.5,-278 465.5,-242 566.5,-242 566.5,-278"/>
+</g>
+<!-- e1&#45;&gt;e4 -->
+<g id="edge7" class="edge">
+<title>e1&#45;&gt;e4</title>
+<path fill="none" stroke="#000000" d="M471.1405,-313.8314C478.1217,-305.454 486.5391,-295.3531 494.1876,-286.1749"/>
+<polygon fill="#000000" stroke="#000000" points="496.9425,-288.3362 500.6556,-278.4133 491.5649,-283.8548 496.9425,-288.3362"/>
+</g>
+<!-- e2&#45;&gt;e3 -->
+<g id="edge1" class="edge">
+<title>e2&#45;&gt;e3</title>
+<path fill="none" stroke="#000000" d="M328.668,-260C331.1453,-260 333.6227,-260 336.1001,-260"/>
+<polygon fill="#000000" stroke="#000000" points="336.2849,-263.5001 346.2848,-260 336.2848,-256.5001 336.2849,-263.5001"/>
+</g>
+<!-- e5 -->
+<g id="node6" class="node">
+<title>e5</title>
+<polygon fill="#008b00" stroke="#000000" points="209.5,-206 108.5,-206 108.5,-170 209.5,-170 209.5,-206"/>
+</g>
+<!-- e2&#45;&gt;e5 -->
+<g id="edge10" class="edge">
+<title>e2&#45;&gt;e5</title>
+<path fill="none" stroke="#000000" d="M247.9713,-241.8314C232.7504,-232.6221 214.0872,-221.3301 197.7917,-211.4706"/>
+<polygon fill="#000000" stroke="#000000" points="199.3868,-208.345 189.0191,-206.1628 195.7631,-214.3341 199.3868,-208.345"/>
+</g>
+<!-- e6 -->
+<g id="node7" class="node">
+<title>e6</title>
+<polygon fill="#00ff00" stroke="#000000" points="328.5,-206 227.5,-206 227.5,-170 328.5,-170 328.5,-206"/>
+<text text-anchor="middle" x="278" y="-183.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting list</text>
+</g>
+<!-- e2&#45;&gt;e6 -->
+<g id="edge11" class="edge">
+<title>e2&#45;&gt;e6</title>
+<path fill="none" stroke="#000000" d="M278,-241.8314C278,-234.131 278,-224.9743 278,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="281.5001,-216.4132 278,-206.4133 274.5001,-216.4133 281.5001,-216.4132"/>
+</g>
+<!-- e3&#45;&gt;e4 -->
+<g id="edge2" class="edge">
+<title>e3&#45;&gt;e4</title>
+<path fill="none" stroke="#000000" d="M447.668,-260C450.1453,-260 452.6227,-260 455.1001,-260"/>
+<polygon fill="#000000" stroke="#000000" points="455.2849,-263.5001 465.2848,-260 455.2848,-256.5001 455.2849,-263.5001"/>
+</g>
+<!-- e7 -->
+<g id="node8" class="node">
+<title>e7</title>
+<polygon fill="#008b00" stroke="#000000" points="447.5,-206 346.5,-206 346.5,-170 447.5,-170 447.5,-206"/>
+</g>
+<!-- e3&#45;&gt;e7 -->
+<g id="edge12" class="edge">
+<title>e3&#45;&gt;e7</title>
+<path fill="none" stroke="#000000" d="M397,-241.8314C397,-234.131 397,-224.9743 397,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="400.5001,-216.4132 397,-206.4133 393.5001,-216.4133 400.5001,-216.4132"/>
+</g>
+<!-- e8 -->
+<g id="node9" class="node">
+<title>e8</title>
+<polygon fill="#00ff00" stroke="#000000" points="566.5,-206 465.5,-206 465.5,-170 566.5,-170 566.5,-206"/>
+<text text-anchor="middle" x="516" y="-183.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting list</text>
+</g>
+<!-- e4&#45;&gt;e8 -->
+<g id="edge13" class="edge">
+<title>e4&#45;&gt;e8</title>
+<path fill="none" stroke="#000000" d="M516,-241.8314C516,-234.131 516,-224.9743 516,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="519.5001,-216.4132 516,-206.4133 512.5001,-216.4133 519.5001,-216.4132"/>
+</g>
+<!-- e9 -->
+<g id="node10" class="node">
+<title>e9</title>
+<polygon fill="#00ff00" stroke="#000000" points="685.5,-206 584.5,-206 584.5,-170 685.5,-170 685.5,-206"/>
+<text text-anchor="middle" x="635" y="-183.8" font-family="Times,serif" font-size="14.00" fill="#000000">posting list</text>
+</g>
+<!-- e4&#45;&gt;e9 -->
+<g id="edge14" class="edge">
+<title>e4&#45;&gt;e9</title>
+<path fill="none" stroke="#000000" d="M546.0287,-241.8314C561.2496,-232.6221 579.9128,-221.3301 596.2083,-211.4706"/>
+<polygon fill="#000000" stroke="#000000" points="598.2369,-214.3341 604.9809,-206.1628 594.6132,-208.345 598.2369,-214.3341"/>
+</g>
+<!-- e5&#45;&gt;e6 -->
+<g id="edge3" class="edge">
+<title>e5&#45;&gt;e6</title>
+<path fill="none" stroke="#000000" d="M209.668,-188C212.1453,-188 214.6227,-188 217.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="217.2849,-191.5001 227.2848,-188 217.2848,-184.5001 217.2849,-191.5001"/>
+</g>
+<!-- p1 -->
+<g id="node11" class="node">
+<title>p1</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="209.5,-124 108.5,-124 108.5,-88 209.5,-88 209.5,-124"/>
+</g>
+<!-- e5&#45;&gt;p1 -->
+<g id="edge25" class="edge">
+<title>e5&#45;&gt;p1</title>
+<path fill="none" stroke="#000000" d="M159,-169.8015C159,-159.3976 159,-146.1215 159,-134.3768"/>
+<polygon fill="#000000" stroke="#000000" points="162.5001,-134.1476 159,-124.1476 155.5001,-134.1476 162.5001,-134.1476"/>
+</g>
+<!-- e6&#45;&gt;e7 -->
+<g id="edge4" class="edge">
+<title>e6&#45;&gt;e7</title>
+<path fill="none" stroke="#000000" d="M328.668,-188C331.1453,-188 333.6227,-188 336.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="336.2849,-191.5001 346.2848,-188 336.2848,-184.5001 336.2849,-191.5001"/>
+</g>
+<!-- e7&#45;&gt;e8 -->
+<g id="edge5" class="edge">
+<title>e7&#45;&gt;e8</title>
+<path fill="none" stroke="#000000" d="M447.668,-188C450.1453,-188 452.6227,-188 455.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="455.2849,-191.5001 465.2848,-188 455.2848,-184.5001 455.2849,-191.5001"/>
+</g>
+<!-- p4 -->
+<g id="node14" class="node">
+<title>p4</title>
+<polygon fill="#00ff00" stroke="#000000" points="388.5,-124 287.5,-124 287.5,-88 388.5,-88 388.5,-124"/>
+<text text-anchor="middle" x="338" y="-101.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- e7&#45;&gt;p4 -->
+<g id="edge26" class="edge">
+<title>e7&#45;&gt;p4</title>
+<path fill="none" stroke="#000000" d="M383.906,-169.8015C376.0383,-158.8668 365.8878,-144.7593 357.133,-132.5916"/>
+<polygon fill="#000000" stroke="#000000" points="359.7389,-130.2207 351.0574,-124.1476 354.0569,-134.309 359.7389,-130.2207"/>
+</g>
+<!-- p5 -->
+<g id="node15" class="node">
+<title>p5</title>
+<polygon fill="#c0c0c0" stroke="#000000" points="514.5,-124 413.5,-124 413.5,-88 514.5,-88 514.5,-124"/>
+</g>
+<!-- e7&#45;&gt;p5 -->
+<g id="edge27" class="edge">
+<title>e7&#45;&gt;p5</title>
+<path fill="none" stroke="#000000" d="M411.8695,-169.8015C420.8907,-158.7606 432.5549,-144.4851 442.5618,-132.2378"/>
+<polygon fill="#000000" stroke="#000000" points="445.5552,-134.1059 449.1721,-124.1476 440.1345,-129.6768 445.5552,-134.1059"/>
+</g>
+<!-- e8&#45;&gt;e9 -->
+<g id="edge6" class="edge">
+<title>e8&#45;&gt;e9</title>
+<path fill="none" stroke="#000000" d="M566.668,-188C569.1453,-188 571.6227,-188 574.1001,-188"/>
+<polygon fill="#000000" stroke="#000000" points="574.2849,-191.5001 584.2848,-188 574.2848,-184.5001 574.2849,-191.5001"/>
+</g>
+<!-- p2 -->
+<g id="node12" class="node">
+<title>p2</title>
+<polygon fill="#00ff00" stroke="#000000" points="117.5,-52 16.5,-52 16.5,-16 117.5,-16 117.5,-52"/>
+<text text-anchor="middle" x="67" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p1&#45;&gt;p2 -->
+<g id="edge16" class="edge">
+<title>p1&#45;&gt;p2</title>
+<path fill="none" stroke="#000000" d="M135.7845,-87.8314C124.453,-78.9632 110.6536,-68.1637 98.3973,-58.5718"/>
+<polygon fill="#000000" stroke="#000000" points="100.2402,-55.5697 90.2081,-52.1628 95.926,-61.0822 100.2402,-55.5697"/>
+</g>
+<!-- p3 -->
+<g id="node13" class="node">
+<title>p3</title>
+<polygon fill="#00ff00" stroke="#000000" points="236.5,-52 135.5,-52 135.5,-16 236.5,-16 236.5,-52"/>
+<text text-anchor="middle" x="186" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p1&#45;&gt;p3 -->
+<g id="edge17" class="edge">
+<title>p1&#45;&gt;p3</title>
+<path fill="none" stroke="#000000" d="M165.8132,-87.8314C168.7644,-79.9617 172.2858,-70.5712 175.555,-61.8533"/>
+<polygon fill="#000000" stroke="#000000" points="178.8609,-63.0055 179.095,-52.4133 172.3066,-60.5476 178.8609,-63.0055"/>
+</g>
+<!-- p2&#45;&gt;p3 -->
+<g id="edge15" class="edge">
+<title>p2&#45;&gt;p3</title>
+<path fill="none" stroke="#000000" d="M117.668,-34C120.1453,-34 122.6227,-34 125.1001,-34"/>
+<polygon fill="#000000" stroke="#000000" points="125.2849,-37.5001 135.2848,-34 125.2848,-30.5001 125.2849,-37.5001"/>
+</g>
+<!-- p6 -->
+<g id="node16" class="node">
+<title>p6</title>
+<polygon fill="#00ff00" stroke="#000000" points="514.5,-52 413.5,-52 413.5,-16 514.5,-16 514.5,-52"/>
+<text text-anchor="middle" x="464" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p5&#45;&gt;p6 -->
+<g id="edge19" class="edge">
+<title>p5&#45;&gt;p6</title>
+<path fill="none" stroke="#000000" d="M464,-87.8314C464,-80.131 464,-70.9743 464,-62.4166"/>
+<polygon fill="#000000" stroke="#000000" points="467.5001,-62.4132 464,-52.4133 460.5001,-62.4133 467.5001,-62.4132"/>
+</g>
+<!-- p7 -->
+<g id="node17" class="node">
+<title>p7</title>
+<polygon fill="#00ff00" stroke="#000000" points="633.5,-52 532.5,-52 532.5,-16 633.5,-16 633.5,-52"/>
+<text text-anchor="middle" x="583" y="-29.8" font-family="Times,serif" font-size="14.00" fill="#000000">heap ptr</text>
+</g>
+<!-- p5&#45;&gt;p7 -->
+<g id="edge20" class="edge">
+<title>p5&#45;&gt;p7</title>
+<path fill="none" stroke="#000000" d="M494.0287,-87.8314C509.2496,-78.6221 527.9128,-67.3301 544.2083,-57.4706"/>
+<polygon fill="#000000" stroke="#000000" points="546.2369,-60.3341 552.9809,-52.1628 542.6132,-54.345 546.2369,-60.3341"/>
+</g>
+<!-- p6&#45;&gt;p7 -->
+<g id="edge18" class="edge">
+<title>p6&#45;&gt;p7</title>
+<path fill="none" stroke="#000000" d="M514.668,-34C517.1453,-34 519.6227,-34 522.1001,-34"/>
+<polygon fill="#000000" stroke="#000000" points="522.2849,-37.5001 532.2848,-34 522.2848,-30.5001 522.2849,-37.5001"/>
+</g>
+<!-- n2 -->
+<g id="node19" class="node">
+<title>n2</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-278 710.5,-278 710.5,-242 811.5,-242 811.5,-278"/>
+</g>
+<!-- n1&#45;&gt;n2 -->
+<g id="edge21" class="edge">
+<title>n1&#45;&gt;n2</title>
+<path fill="none" stroke="#000000" d="M761,-313.8314C761,-306.131 761,-296.9743 761,-288.4166"/>
+<polygon fill="#000000" stroke="#000000" points="764.5001,-288.4132 761,-278.4133 757.5001,-288.4133 764.5001,-288.4132"/>
+</g>
+<!-- n3 -->
+<g id="node20" class="node">
+<title>n3</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-206 710.5,-206 710.5,-170 811.5,-170 811.5,-206"/>
+</g>
+<!-- n2&#45;&gt;n3 -->
+<g id="edge22" class="edge">
+<title>n2&#45;&gt;n3</title>
+<path fill="none" stroke="#000000" d="M761,-241.8314C761,-234.131 761,-224.9743 761,-216.4166"/>
+<polygon fill="#000000" stroke="#000000" points="764.5001,-216.4132 761,-206.4133 757.5001,-216.4133 764.5001,-216.4132"/>
+</g>
+<!-- n4 -->
+<g id="node21" class="node">
+<title>n4</title>
+<polygon fill="#ff0000" stroke="#000000" points="811.5,-124 710.5,-124 710.5,-88 811.5,-88 811.5,-124"/>
+</g>
+<!-- n3&#45;&gt;n4 -->
+<g id="edge23" class="edge">
+<title>n3&#45;&gt;n4</title>
+<path fill="none" stroke="#000000" d="M761,-169.8015C761,-159.3976 761,-146.1215 761,-134.3768"/>
+<polygon fill="#000000" stroke="#000000" points="764.5001,-134.1476 761,-124.1476 757.5001,-134.1476 764.5001,-134.1476"/>
+</g>
+</g>
+</svg>
diff --git a/doc/src/sgml/pagelayout.svg b/doc/src/sgml/pagelayout.svg
new file mode 100644
index 0000000000..6b819a553e
--- /dev/null
+++ b/doc/src/sgml/pagelayout.svg
@@ -0,0 +1,40 @@
+<?xml version='1.0' encoding='UTF-8' standalone='no'?>
+<svg 
+    xmlns='http://www.w3.org/2000/svg'
+    width='610'
+    height='210'
+    shape-rendering='geometricPrecision'
+    version='1.0'>
+  <defs>
+    <filter id='f2' x='0' y='0' width='200%' height='200%'>
+      <feOffset result='offOut' in='SourceGraphic' dx='5' dy='5' />
+      <feGaussianBlur result='blurOut' in='offOut' stdDeviation='3' />
+      <feBlend in='SourceGraphic' in2='blurOut' mode='normal' />
+    </filter>
+  </defs>
+  <g stroke-width='1' stroke-linecap='square' stroke-linejoin='round'>
+    <rect x='0' y='0' width='610' height='210' style='fill: #ffffff'/>
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M25.0 35.0 L25.0 175.0 L585.0 175.0 L585.0 35.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M305.0 175.0 L485.0 175.0 L485.0 147.0 L305.0 147.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M25.0 35.0 L25.0 63.0 L195.0 63.0 L195.0 35.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M305.0 147.0 L305.0 175.0 L195.0 175.0 L195.0 147.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M325.0 63.0 L325.0 91.0 L265.0 91.0 L265.0 105.0 L235.0 105.0 L235.0 63.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M585.0 147.0 L585.0 175.0 L485.0 175.0 L485.0 147.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M195.0 35.0 L285.0 35.0 L285.0 63.0 L195.0 63.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='white' d='M375.0 35.0 L375.0 63.0 L285.0 63.0 L285.0 35.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='none' d='M335.0 133.0 L335.0 105.0 L265.0 105.0 ' />
+    <path stroke='none' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='#000000' d='M470.0 42.0 L480.0 49.0 L470.0 56.0 z' />
+    <path stroke='none' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='#000000' d='M260.0 126.0 L265.0 140.0 L270.0 126.0 z' />
+    <path stroke='none' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='#000000' d='M330.0 126.0 L335.0 140.0 L340.0 126.0 z' />
+    <path stroke='none' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='#000000' d='M140.0 154.0 L130.0 161.0 L140.0 168.0 z' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-linecap='round' stroke-linejoin='round' fill='none' d='M265.0 105.0 L265.0 133.0 ' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-dasharray='5.000000,5.000000' stroke-miterlimit='0' stroke-linecap='butt' stroke-linejoin='round' fill='white' d='M375.0 49.0 L475.0 49.0 ' />
+    <path stroke='#000000' stroke-width='1.000000' stroke-dasharray='5.000000,5.000000' stroke-miterlimit='0' stroke-linecap='butt' stroke-linejoin='round' fill='white' d='M135.0 161.0 L195.0 161.0 ' />
+    <text x='48' y='54' font-family='Courier' font-size='15' stroke='none' fill='#000000' ><![CDATA[PageHeaderData]]></text>
+    <text x='214' y='166' font-family='Courier' font-size='15' stroke='none' fill='#000000' ><![CDATA[Item]]></text>
+    <text x='216' y='54' font-family='Courier' font-size='15' stroke='none' fill='#000000' ><![CDATA[ItemId]]></text>
+    <text x='306' y='54' font-family='Courier' font-size='15' stroke='none' fill='#000000' ><![CDATA[ItemId]]></text>
+    <text x='324' y='166' font-family='Courier' font-size='15' stroke='none' fill='#000000' ><![CDATA[Item]]></text>
+    <text x='509' y='166' font-family='Courier' font-size='15' stroke='none' fill='#000000' ><![CDATA[Special]]></text>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/doc/src/sgml/pagelayout.txt b/doc/src/sgml/pagelayout.txt
new file mode 100644
index 0000000000..40bee5d169
--- /dev/null
+++ b/doc/src/sgml/pagelayout.txt
@@ -0,0 +1,11 @@
++----------------+--------+--------+--------------------+
+| PageHeaderData | ItemId | ItemId +=-------->          |
++----------------+---+----+---+----+                    |
+|                    |        |                         |
+|                    |  +-----+                         |
+|                    +--+------+                        |
+|                       |      |                        |
+|                       v      v                        |
+|                +----------+-----------------+---------+
+|          <----=+ Item     | Item            | Special |
++----------------+----------+-----------------+---------+
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index cbdad0c3fb..1ed3d1cab6 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -917,6 +917,19 @@ <title>PageHeaderData Layout</title>
 
  </para>
 
+ <para>
+  <xref linkend="storage-page-layout-figure"/> illustrates how these parts are layed out in a page.
+ </para>
+
+ <figure id="storage-page-layout-figure">
+  <title>Page Layout</title>
+  <mediaobject>
+   <imageobject>
+    <imagedata fileref="pagelayout.svg" format="SVG" width="100%" scalefit="1"/>
+   </imageobject>
+  </mediaobject>
+ </figure>
+
  <sect2 id="storage-tuple-layout">
 
  <title>Table Row Layout</title>
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl
index 8942d99472..b105005235 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -14,6 +14,7 @@
 <!-- Parameters -->
 <xsl:param name="make.valid.html" select="1"></xsl:param>
 <xsl:param name="generate.id.attributes" select="1"></xsl:param>
+<xsl:param name="ignore.image.scaling" select="1"/>
 <xsl:param name="link.mailto.url">[email-masked]</xsl:param>
 <xsl:param name="toc.max.depth">2</xsl:param>
 
-- 
2.21.0

---

From: Tom Lane <[email-masked]>
Date: Mon, 11 Mar 2019 10:50:52 -0400

Peter Eisentraut <[email-masked]> writes:
> abstraction.

It does seem like using SVG as an intermediate format rather than a source
format might be a better idea.

> didn't bother with that in my patch yet.)

Ideally, we'd treat them much as we do for bison output files:
we'll supply them in tarballs but you'd better have the relevant
tools if you want to build docs from a git pull.  However, that
may be assuming too much about the portability of the tools ...

			regards, tom lane

---

From: Jürgen Purtz <[email-masked]>
Date: Tue, 12 Mar 2019 06:14:39 +0300

On 11.03.19 12:13, Peter Eisentraut wrote:
> nothing in the format indicates how they are connected.

Yes, SVG knows nothing about higher level concepts. That's one of the 
reasons why there are tools to create SVG, eg. Inkscape with the 
connectors feature (it was not used in the examples but obviously it's 
possible.)

> and the page layout image using Ditaa.

That was the heart of the proposal: Since  we couldn't find consensus 
about a single tool in the long lasting discussion, everybody shall use 
his favourite tool and deliver the original source plus a SVG version.

Kind regards,

Jürgen Purtz

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 14 Mar 2019 13:40:38 +0100

> may be assuming too much about the portability of the tools ...

The portability is not something I'm concerned about, but Ditaa requires
Java, so that might annoy some people.

---

From: Tom Lane <[email-masked]>
Date: Thu, 14 Mar 2019 09:10:42 -0400

> Java, so that might annoy some people.

Portability is something you *should* be concerned about.  We want
all patch submitters to be able to build the docs, else we'll forever
be fighting silly markup errors.  That's not a productive use of
anybody's time.

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 14 Mar 2019 21:27:25 +0100

> be fighting silly markup errors.  That's not a productive use of

Let me rephrase: I'm agree that portability is important, and I'm
confident that the tools in question are portable enough.

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 27 Mar 2019 23:17:47 +0100

This has been committed.  The SVG images are committed as well, so no
new tools are required.

---

From: Peter Geoghegan <[email-masked]>
Date: Wed, 27 Mar 2019 15:44:33 -0700

> This has been committed.  The SVG images are committed as well, so no

Apparently it's possible to run Ditaa over the web. Perhaps we'll
figure out a way to have contributors validate their changes through a
browser, rather than expecting them to install Java locally. I don't
think that it's necessary to have something like that available
immediately. It is an option, though.

-- 
Peter Geoghegan

---

From: Tatsuo Ishii <[email-masked]>
Date: Thu, 28 Mar 2019 08:41:54 +0900 (JST)

> This has been committed.  The SVG images are committed as well, so no

Is it possible to generate figure indexes?

Best regards,

---

From: Tom Lane <[email-masked]>
Date: Wed, 27 Mar 2019 20:50:31 -0400

> This has been committed.  The SVG images are committed as well, so no

Buildfarm member alabio seems less than pleased.

			regards, tom lane

---

From: Jürgen Purtz <[email-masked]>
Date: Thu, 28 Mar 2019 08:19:51 +0100

> Is it possible to generate figure indexes?

This is an additional topic and there was a brief discussion on 7 
February (and in older conversations) regarding this. It concerns list 
of figures, tables, and examples. I intend to make a proposal around May 
2019.

Kind regards

Jürgen Purtz

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 28 Mar 2019 08:50:16 +0100

> Buildfarm member alabio seems less than pleased.

See
<https://askubuntu.com/questions/695560/assistive-technology-not-found-awterror>
for how to fix that build issue.

---

From: Tatsuo Ishii <[email-masked]>
Date: Thu, 28 Mar 2019 17:03:20 +0900 (JST)

> This has been committed.  The SVG images are committed as well, so no

What is the policy of adding graphics to PostgreSQL 12? Is it
encouraged to add more graphics to 12 docs? Or do we want to prohibit
it?

Best regards,

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 28 Mar 2019 09:52:01 +0100

> encouraged to add more graphics to 12 docs? Or do we want to prohibit

I have nothing against a few more, especially if they stay within the
provided tooling.

---

From: Magnus Hagander <[email-masked]>
Date: Thu, 28 Mar 2019 09:59:06 +0100

On Thu, Mar 28, 2019 at 8:50 AM Peter Eisentraut <
[email-masked]> wrote:

> <
> https://askubuntu.com/questions/695560/assistive-technology-not-found-awterror
> >

Ugh. If I understand it right, that's something that will happen to anybody
who tries to build the docs on a headless server, which is not exactly
uncommon :/

Can we find a way to override it in the command? Or if not, we should
probably at least document it in our docs?

I have done this on alabio now, let's see if it recovers.

---

From: Magnus Hagander <[email-masked]>
Date: Thu, 28 Mar 2019 11:04:26 +0100

On Thu, Mar 28, 2019 at 9:59 AM Magnus Hagander <[email-masked]> wrote:

> Ugh. If I understand it right, that's something that will happen to
> anybody who tries to build the docs on a headless server, which is not
> exactly uncommon :/
>
FYI, it did recover. Per above, I think this is something we should
document.

---

From: Jürgen Purtz <[email-masked]>
Date: Thu, 28 Mar 2019 12:24:58 +0100

> I have nothing against a few more, especially if they stay within the
Because many of the prospective authors voted for Inkscape in the course 
of this discussion, there shall be at least one example in Inkscape format.

There were reservations against the published Inkscape files because 
they didn't made use of any 'higher-level-concept'. Please find a new 
Inkscape version of the pg_dump which uses such concepts. It groups 
texts and paths together to logical units (disc with explanation). You 
can rearrange such units as a whole or align a set of them to left, top, 
... with Inkscape (iconized) commands. Additionally those objects are 
linked together with connectors to rearrange their position by 
drag-and-drop. The resulting file in 'Optimized' version is also attached.

Kind regards, Jürgen

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 28 Mar 2019 19:06:18 +0100

On 2019-03-28 11:04, Magnus Hagander wrote:
>     anybody who tries to build the docs on a headless server, which is
>     not exactly uncommon :/
> 
>     Can we find a way to override it in the command? Or if not, we
>     should probably at least document it in our docs?
> 

It seems like this is a Debian/Ubuntu-specific packaging issue.  We
could document it, but I wonder if it's just a transient thing.

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 28 Mar 2019 19:08:32 +0100

> of this discussion, there shall be at least one example in Inkscape format.

Well, my vote is against doing anything with Inkscape, at least until
other possibilities are exhausted.

---

From: Neil <[email-masked]>
Date: Thu, 28 Mar 2019 14:21:29 -0500

> On Mar 28, 2019, at 1:08 PM, Peter Eisentraut <[email-masked]> wrote:
> 

Has anyone found an svg editor that works good on a Mac.  I tried the MacPorts version of inkscape as recommended by the inkscape website and it won’t open a file so I’m not sure it works at all.

I did find another editor https://github.com/dsward2/macSVG <https://github.com/dsward2/macSVG> and it seems to work, but have not used it much.

Neil

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 28 Mar 2019 17:23:08 -0300

I think we should first exhaust all options to use the currently
supported formats, before adding a new controversial one.  You can use
the {s} qualifier for a box in ditaa and it'll show a disk; this ascii
diagram produces a "similar enough" image to your diagram, for example:

+------------+                                +---------+
| Original   | pg_dump, other archive formats | Binary  |
|  Database  |------------------------------->| File(s) |
|         {s}|                                |     {s} |
+------------+                                +---------+
     |                                             |
     | pg_dump, script format                      | pg_restore
     |                                             |
     v                                             v
+------------+                               +----------+
| SQL INSERT |            psql               | Restored |
| commands   |------------------------------>| Database |
|        {s} |                               |       {s}|
+------------+                               +----------+

It takes more time to write this email than to get the diagram done.

(I say "controversial" about inkscape because it was initially claimed
that the output was going to be clean/readable/diffable, and that's what
got so many upvotes.  After the admission that that's not so, I suspect
votes for inkscape have decreased somewhat.)