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 <pe...@eisentraut.org>
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
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 2420c55681..4ca6cc0259 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)
+ALL_IMAGES = gin.svg pagelayout.svg
+
##
## Man pages
@@ -125,9 +127,10 @@ endif
html: html-stamp
-html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML)
+html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS)
$(wordlist 1,2,$^)
+ cp $(ALL_IMAGES) html/
cp $(srcdir)/stylesheet.css html/
touch $@
@@ -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->e1 -->
+<g id="edge24" class="edge">
+<title>m1->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->n1 -->
+<g id="edge28" class="edge">
+<title>m1->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->e2 -->
+<g id="edge9" class="edge">
+<title>e1->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->e3 -->
+<g id="edge8" class="edge">
+<title>e1->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->e4 -->
+<g id="edge7" class="edge">
+<title>e1->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->e3 -->
+<g id="edge1" class="edge">
+<title>e2->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->e5 -->
+<g id="edge10" class="edge">
+<title>e2->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->e6 -->
+<g id="edge11" class="edge">
+<title>e2->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->e4 -->
+<g id="edge2" class="edge">
+<title>e3->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->e7 -->
+<g id="edge12" class="edge">
+<title>e3->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->e8 -->
+<g id="edge13" class="edge">
+<title>e4->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->e9 -->
+<g id="edge14" class="edge">
+<title>e4->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->e6 -->
+<g id="edge3" class="edge">
+<title>e5->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->p1 -->
+<g id="edge25" class="edge">
+<title>e5->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->e7 -->
+<g id="edge4" class="edge">
+<title>e6->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->e8 -->
+<g id="edge5" class="edge">
+<title>e7->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->p4 -->
+<g id="edge26" class="edge">
+<title>e7->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->p5 -->
+<g id="edge27" class="edge">
+<title>e7->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->e9 -->
+<g id="edge6" class="edge">
+<title>e8->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->p2 -->
+<g id="edge16" class="edge">
+<title>p1->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->p3 -->
+<g id="edge17" class="edge">
+<title>p1->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->p3 -->
+<g id="edge15" class="edge">
+<title>p2->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->p6 -->
+<g id="edge19" class="edge">
+<title>p5->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->p7 -->
+<g id="edge20" class="edge">
+<title>p5->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->p7 -->
+<g id="edge18" class="edge">
+<title>p6->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->n2 -->
+<g id="edge21" class="edge">
+<title>n1->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->n3 -->
+<g id="edge22" class="edge">
+<title>n2->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->n4 -->
+<g id="edge23" class="edge">
+<title>n3->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">pgsql-docs@lists.postgresql.org</xsl:param>
<xsl:param name="toc.max.depth">2</xsl:param>
--
2.21.0
