Skip to content

P
Postgres FD Implementation
Commit ea55aec0 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

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
parent 477422c9
Expand all Show whitespace changes
Inline Side-by-side
Showing with 602 additions and 6 deletions
.gitattributes
View file @ ea55aec0
......@@ -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
......
doc/src/sgml/Makefile
View file @ ea55aec0
......@@ -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 $@ $<
......
doc/src/sgml/gin.sgml
View file @ ea55aec0
......@@ -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>
......
doc/src/sgml/images/Makefile 0 → 100644
View file @ ea55aec0
# 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 $< $@
doc/src/sgml/images/README 0 → 100644
View file @ ea55aec0
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.)
doc/src/sgml/images/gin.dot 0 → 100644
View file @ ea55aec0
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];
}
doc/src/sgml/images/gin.svg 0 → 100644
View file @ ea55aec0
This diff is collapsed.
doc/src/sgml/images/pagelayout.svg 0 → 100644
View file @ ea55aec0
<?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
doc/src/sgml/images/pagelayout.txt 0 → 100644
View file @ ea55aec0
+----------------+--------+--------+--------------------+
| PageHeaderData | ItemId | ItemId +=--------> |
+----------------+---+----+---+----+ |
| | | |
| | +-----+ |
| +--+------+ |
| | | |
| v v |
| +----------+-----------------+---------+
| <----=+ Item | Item | Special |
+----------------+----------+-----------------+---------+
doc/src/sgml/storage.sgml
View file @ ea55aec0
......@@ -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>
......
doc/src/sgml/stylesheet-hh.xsl
View file @ ea55aec0
......@@ -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>
doc/src/sgml/stylesheet-html-common.xsl
View file @ ea55aec0
......@@ -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>
......
doc/src/sgml/stylesheet-html-nochunk.xsl
View file @ ea55aec0
......@@ -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>
doc/src/sgml/stylesheet.xsl
View file @ ea55aec0
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment