diff --git a/.gitattributes b/.gitattributes index bdbcdb560af..fa87ca812af 100644 --- 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 72f8075c734..0d0db18ff89 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 := $(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 cc7cd1ed2c4..488c3d8b45d 100644 --- 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 posting tree), or a simple list of heap pointers (a posting list) when the list is small enough to fit into a single index tuple along - with the key value. + with the key value. illustrates + these components of a GIN index. @@ -453,6 +454,15 @@ key values for different columns can be of different types. +
+ GIN Internals + + + + + +
+ GIN Fast Update Technique diff --git a/doc/src/sgml/images/Makefile b/doc/src/sgml/images/Makefile new file mode 100644 index 00000000000..6b229f03ad9 --- /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 index 00000000000..dd29486a092 --- /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: + +
+ GIN Internals + + + + + +
+ +Notes: + +- The real action is in the element, but typically a +
should be wrapped around it and an 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 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 index 00000000000..097e91029a4 --- /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 index 00000000000..eacb5c8c160 --- /dev/null +++ b/doc/src/sgml/images/gin.svg @@ -0,0 +1,320 @@ + + + + + + +gin + + +cluster01 + +entry tree + + +cluster02 + +posting tree + + +cluster03 + +posting tree + + +cluster04 + +posting tree + + +cluster05 + +pending list + + + +m1 + +meta page + + + +e1 + + + + +m1->e1 + + + + + +n1 + + + + +m1->n1 + + + + + +e2 + + + + +e1->e2 + + + + + +e3 + + + + +e1->e3 + + + + + +e4 + + + + +e1->e4 + + + + + +e2->e3 + + + + + +e5 + + + + +e2->e5 + + + + + +e6 + +posting list + + + +e2->e6 + + + + + +e3->e4 + + + + + +e7 + + + + +e3->e7 + + + + + +e8 + +posting list + + + +e4->e8 + + + + + +e9 + +posting list + + + +e4->e9 + + + + + +e5->e6 + + + + + +p1 + + + + +e5->p1 + + + + + +e6->e7 + + + + + +e7->e8 + + + + + +p4 + +heap ptr + + + +e7->p4 + + + + + +p5 + + + + +e7->p5 + + + + + +e8->e9 + + + + + +p2 + +heap ptr + + + +p1->p2 + + + + + +p3 + +heap ptr + + + +p1->p3 + + + + + +p2->p3 + + + + + +p6 + +heap ptr + + + +p5->p6 + + + + + +p7 + +heap ptr + + + +p5->p7 + + + + + +p6->p7 + + + + + +n2 + + + + +n1->n2 + + + + + +n3 + + + + +n2->n3 + + + + + +n4 + + + + +n3->n4 + + + + + diff --git a/doc/src/sgml/images/pagelayout.svg b/doc/src/sgml/images/pagelayout.svg new file mode 100644 index 00000000000..6b819a553e2 --- /dev/null +++ b/doc/src/sgml/images/pagelayout.svg @@ -0,0 +1,40 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + PageHeaderData + Item + ItemId + ItemId + Item + Special + + \ 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 index 00000000000..40bee5d1699 --- /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 cbdad0c3fb5..7af918d36ee 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -917,6 +917,20 @@ data. Empty in ordinary tables. + + illustrates how these parts are + layed out in a page. + + +
+ Page Layout + + + + + +
+ Table Row Layout diff --git a/doc/src/sgml/stylesheet-hh.xsl b/doc/src/sgml/stylesheet-hh.xsl index fb2da0b72f6..1b1ab4bbe9e 100644 --- a/doc/src/sgml/stylesheet-hh.xsl +++ b/doc/src/sgml/stylesheet-hh.xsl @@ -40,4 +40,10 @@
+ + + + + + diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl index 8942d994725..b105005235d 100644 --- a/doc/src/sgml/stylesheet-html-common.xsl +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -14,6 +14,7 @@ + pgsql-docs@lists.postgresql.org 2 diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl index ffd2012e918..78add26a9f4 100644 --- a/doc/src/sgml/stylesheet-html-nochunk.xsl +++ b/doc/src/sgml/stylesheet-html-nochunk.xsl @@ -9,4 +9,15 @@ + + + + + + + + + + + diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl index 22dd3b93c62..4ff6e8ed242 100644 --- a/doc/src/sgml/stylesheet.xsl +++ b/doc/src/sgml/stylesheet.xsl @@ -28,6 +28,12 @@ + + + + + +