doc: Add some images

Add infrastructure for having images in the documentation, in SVG
format.  Add two images to start with.  See the included README file
for instructions.

Author: Jürgen Purtz <juergen@purtz.de>
Author: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Discussion: https://www.postgresql.org/message-id/flat/aaa54502-05c0-4ea5-9af8-770411a6bf4b@purtz.de

diff --git a/.gitattributes b/.gitattributes
index bdbcdb560af3b38a49ff66fd3e9fb97b5876877b..fa87ca812afe4b6d36181e75a88676c3099e9ad4 100644 (file)
--- a/.gitattributes
+++ b/.gitattributes
@@ -13,6 +13,7 @@ README.*      conflict-marker-size=32
 
 # Certain data files that contain special whitespace, and other special cases
 *.data                                         -whitespace
+*.svg                                          whitespace=-blank-at-eol
 contrib/pgcrypto/sql/pgp-armor.sql             whitespace=-blank-at-eol
 doc/bug.template                               whitespace=space-before-tab,-blank-at-eof,blank-at-eol
 src/backend/catalog/sql_features.txt           whitespace=space-before-tab,blank-at-eof,-blank-at-eol

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 72f8075c73427edb3e6a9848b358701b1c60b120..0d0db18ff8957d1d335ba3d8fe309de2d9119652 100644 (file)
--- 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 := $(wildcard $(srcdir)/images/*.svg)
+
 
 ##
 ## Man pages
@@ -125,22 +127,24 @@ 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 $@
 
 htmlhelp: htmlhelp-stamp
 
-htmlhelp-stamp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
+htmlhelp-stamp: stylesheet-hh.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
        $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
        $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
+       cp $(ALL_IMAGES) htmlhelp/
        cp $(srcdir)/stylesheet.css htmlhelp/
        touch $@
 
 # 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,$^)
 
@@ -164,7 +168,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 $@
 
 
@@ -173,7 +177,7 @@ postgres.pdf:
 ##
 
 epub: postgres.epub
-postgres.epub: postgres.sgml $(ALLSGML)
+postgres.epub: postgres.sgml $(ALLSGML) $(ALL_IMAGES)
        $(XMLLINT) --noout --valid $<
        $(DBTOEPUB) -o $@ $<
 

diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index cc7cd1ed2c4cc9152355f7f2e825919324581110..488c3d8b45de0a33c2c9bc7b9a1f0c19d6b0b96d 100644 (file)
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -436,7 +436,8 @@
   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 @@
   key values for different columns can be of different types.
  </para>
 
+ <figure id="gin-internals-figure">
+  <title>GIN Internals</title>
+  <mediaobject>
+   <imageobject>
+    <imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
+   </imageobject>
+  </mediaobject>
+ </figure>
+
  <sect2 id="gin-fast-update">
   <title>GIN Fast Update Technique</title>
 

diff --git a/doc/src/sgml/images/Makefile b/doc/src/sgml/images/Makefile
new file mode 100644 (file)
index 0000000..6b229f0
--- /dev/null
+++ b/doc/src/sgml/images/Makefile
@@ -0,0 +1,18 @@
+# doc/src/sgml/images/Makefile
+#
+# see README in this directory about image handling
+
+ALL_IMAGES = \
+       gin.svg \
+       pagelayout.svg
+
+DITAA = ditaa
+DOT = dot
+
+all: $(ALL_IMAGES)
+
+%.svg: %.dot
+       $(DOT) -T svg -o $@ $<
+
+%.svg: %.txt
+       $(DITAA) -E -S --svg $< $@

diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README
new file mode 100644 (file)
index 0000000..dd29486
--- /dev/null
+++ b/doc/src/sgml/images/README
@@ -0,0 +1,61 @@
+Images
+======
+
+This directory contains images for use in the documentation.
+
+Creating an image
+-----------------
+
+A variety of tools can be used to create an image.  The appropriate
+choice depends on the nature of the image.  We prefer workflows that
+involve diffable source files.
+
+These tools are acceptable:
+
+- Graphviz (https://graphviz.org/)
+- Ditaa (http://ditaa.sourceforge.net/)
+
+We use SVG as the format for integrating the image into the ultimate
+output formats of the documentation, that is, HTML, PDF, and others.
+Therefore, any tool used needs to be able to produce SVG.
+
+This directory contains makefile rules to build SVG from common input
+formats, using some common styling.
+
+Both the source and the SVG output file are committed in this
+directory.  That way, we don't need all developers to have all the
+tools installed.  While we accept that there could be some gratuitous
+diffs in the SVG output depending the specific tool, let's keep an eye
+on that and keep it to a minimum.
+
+Using an image in DocBook
+-------------------------
+
+Here is an example for using an image in DocBook:
+
+    <figure id="gin-internals-figure">
+     <title>GIN Internals</title>
+     <mediaobject>
+      <imageobject>
+       <imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
+      </imageobject>
+     </mediaobject>
+    </figure>
+
+Notes:
+
+- The real action is in the <mediaobject> element, but typically a
+  <figure> should be wrapped around it and an <xref> to the figure
+  should be put into the text somewhere.  Don't just put an image into
+  the documentation without a link to it and an explanation of it.
+
+- Things are set up so that we only need one <imagedata> element, even
+  with different output formats.
+
+- The attribute format="SVG" is required.  If you omit it, it will
+  still appear to work, but the stylesheets do a better job if the
+  image is declared as SVG explicitly.
+
+- The width should be set to something.  This ensures that the image
+  is scaled to fit the page in PDF output.  (Other widths than 100%
+  might be appropriate.)

diff --git a/doc/src/sgml/images/gin.dot b/doc/src/sgml/images/gin.dot
new file mode 100644 (file)
index 0000000..097e910
--- /dev/null
+++ b/doc/src/sgml/images/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/images/gin.svg b/doc/src/sgml/images/gin.svg
new file mode 100644 (file)
index 0000000..eacb5c8
--- /dev/null
+++ b/doc/src/sgml/images/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/images/pagelayout.svg b/doc/src/sgml/images/pagelayout.svg
new file mode 100644 (file)
index 0000000..6b819a5
--- /dev/null
+++ b/doc/src/sgml/images/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/images/pagelayout.txt b/doc/src/sgml/images/pagelayout.txt
new file mode 100644 (file)
index 0000000..40bee5d
--- /dev/null
+++ b/doc/src/sgml/images/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 cbdad0c3fb5759fd19924a567b85a5e8f16d4d36..7af918d36ee70e789fe0995507ec86c2e495acfd 100644 (file)
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -917,6 +917,20 @@ data. Empty in ordinary tables.</entry>
 
  </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="images/pagelayout.svg" format="SVG" width="100%"/>
+   </imageobject>
+  </mediaobject>
+ </figure>
+
  <sect2 id="storage-tuple-layout">
 
  <title>Table Row Layout</title>

diff --git a/doc/src/sgml/stylesheet-hh.xsl b/doc/src/sgml/stylesheet-hh.xsl
index fb2da0b72f68acfee6f66b7a29a6ccbe758f0cf1..1b1ab4bbe9e681ce58737b068e0dbd1d9b1de014 100644 (file)
--- a/doc/src/sgml/stylesheet-hh.xsl
+++ b/doc/src/sgml/stylesheet-hh.xsl
@@ -40,4 +40,10 @@
   </span><br/>
 </xsl:template>
 
+
+<!-- strip directory name from image filerefs -->
+<xsl:template match="imagedata/@fileref">
+ <xsl:value-of select="substring-after(., '/')"/>
+</xsl:template>
+
 </xsl:stylesheet>

diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl
index 8942d9947254016bcce59f9422e7cc7e162110b5..b105005235d7824faac1185e140fee9520c9334a 100644 (file)
--- 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>
 

diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl
index ffd2012e918eb6a09cea5d7d7b3e3e6a11454ea0..78add26a9f46ea58e15bc6ee93b3e996c9b80137 100644 (file)
--- a/doc/src/sgml/stylesheet-html-nochunk.xsl
+++ b/doc/src/sgml/stylesheet-html-nochunk.xsl
@@ -9,4 +9,15 @@
 <xsl:include href="stylesheet-html-common.xsl" />
 <xsl:include href="stylesheet-speedup-xhtml.xsl" />
 
+<!-- embed SVG images into output file -->
+<xsl:template match="imagedata[@format='SVG']">
+  <xsl:variable name="filename">
+    <xsl:call-template name="mediaobject.filename">
+      <xsl:with-param name="object" select=".."/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:copy-of select="document($filename)"/>
+</xsl:template>
+
 </xsl:stylesheet>

diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index 22dd3b93c626ba287643ae2af095a9afa4e123c2..4ff6e8ed242af4a6785aa3cc0b30bbe3078d47d8 100644 (file)
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -28,6 +28,12 @@
 </xsl:param>
 
 
+<!-- strip directory name from image filerefs -->
+<xsl:template match="imagedata/@fileref">
+ <xsl:value-of select="substring-after(., '/')"/>
+</xsl:template>
+
+
 <!--
 Customization of header
 - add Up and Home links