Skip to content

Commit ea55aec

Browse files
peterepetere
committed
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 <[email protected]> Author: Peter Eisentraut <[email protected]> Discussion: https://www.postgresql.org/message-id/flat/[email protected]
1 parent 477422c commit ea55aec

14 files changed

+602
-6
lines changed

‎.gitattributes

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ README.* conflict-marker-size=32
1313

1414
# Certain data files that contain special whitespace, and other special cases
1515
*.data -whitespace
16+
*.svg whitespace=-blank-at-eol
1617
contrib/pgcrypto/sql/pgp-armor.sql whitespace=-blank-at-eol
1718
doc/bug.template whitespace=space-before-tab,-blank-at-eof,blank-at-eol
1819
src/backend/catalog/sql_features.txt whitespace=space-before-tab,blank-at-eof,-blank-at-eol

‎doc/src/sgml/Makefile

+9-5
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ GENERATED_SGML = version.sgml \
5757

5858
ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
5959

60+
ALL_IMAGES := $(wildcard $(srcdir)/images/*.svg)
61+
6062

6163
##
6264
## Man pages
@@ -125,22 +127,24 @@ endif
125127

126128
html: html-stamp
127129

128-
html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML)
130+
html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
129131
$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
130132
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
133+
cp $(ALL_IMAGES) html/
131134
cp $(srcdir)/stylesheet.css html/
132135
touch $@
133136

134137
htmlhelp: htmlhelp-stamp
135138

136-
htmlhelp-stamp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
139+
htmlhelp-stamp: stylesheet-hh.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
137140
$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
138141
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
142+
cp $(ALL_IMAGES) htmlhelp/
139143
cp $(srcdir)/stylesheet.css htmlhelp/
140144
touch $@
141145

142146
# single-page HTML
143-
postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML)
147+
postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
144148
$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
145149
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
146150

@@ -164,7 +168,7 @@ postgres.pdf:
164168
$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
165169
$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
166170

167-
%.pdf: %.fo
171+
%.pdf: %.fo $(ALL_IMAGES)
168172
$(FOP) -fo $< -pdf $@
169173

170174

@@ -173,7 +177,7 @@ postgres.pdf:
173177
##
174178

175179
epub: postgres.epub
176-
postgres.epub: postgres.sgml $(ALLSGML)
180+
postgres.epub: postgres.sgml $(ALLSGML) $(ALL_IMAGES)
177181
$(XMLLINT) --noout --valid $<
178182
$(DBTOEPUB) -o $@ $<
179183

‎doc/src/sgml/gin.sgml

+11-1
Original file line numberDiff line numberDiff line change
@@ -436,7 +436,8 @@
436436
page contains either a pointer to a B-tree of heap pointers (a
437437
<quote>posting tree</quote>), or a simple list of heap pointers (a <quote>posting
438438
list</quote>) when the list is small enough to fit into a single index tuple along
439-
with the key value.
439+
with the key value. <xref linkend="gin-internals-figure"/> illustrates
440+
these components of a GIN index.
440441
</para>
441442

442443
<para>
@@ -453,6 +454,15 @@
453454
key values for different columns can be of different types.
454455
</para>
455456

457+
<figure id="gin-internals-figure">
458+
<title>GIN Internals</title>
459+
<mediaobject>
460+
<imageobject>
461+
<imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
462+
</imageobject>
463+
</mediaobject>
464+
</figure>
465+
456466
<sect2 id="gin-fast-update">
457467
<title>GIN Fast Update Technique</title>
458468

‎doc/src/sgml/images/Makefile

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# doc/src/sgml/images/Makefile
2+
#
3+
# see README in this directory about image handling
4+
5+
ALL_IMAGES = \
6+
gin.svg \
7+
pagelayout.svg
8+
9+
DITAA = ditaa
10+
DOT = dot
11+
12+
all: $(ALL_IMAGES)
13+
14+
%.svg: %.dot
15+
$(DOT) -T svg -o $@ $<
16+
17+
%.svg: %.txt
18+
$(DITAA) -E -S --svg $< $@

‎doc/src/sgml/images/README

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
Images
2+
======
3+
4+
This directory contains images for use in the documentation.
5+
6+
Creating an image
7+
-----------------
8+
9+
A variety of tools can be used to create an image. The appropriate
10+
choice depends on the nature of the image. We prefer workflows that
11+
involve diffable source files.
12+
13+
These tools are acceptable:
14+
15+
- Graphviz (https://graphviz.org/)
16+
- Ditaa (http://ditaa.sourceforge.net/)
17+
18+
We use SVG as the format for integrating the image into the ultimate
19+
output formats of the documentation, that is, HTML, PDF, and others.
20+
Therefore, any tool used needs to be able to produce SVG.
21+
22+
This directory contains makefile rules to build SVG from common input
23+
formats, using some common styling.
24+
25+
Both the source and the SVG output file are committed in this
26+
directory. That way, we don't need all developers to have all the
27+
tools installed. While we accept that there could be some gratuitous
28+
diffs in the SVG output depending the specific tool, let's keep an eye
29+
on that and keep it to a minimum.
30+
31+
Using an image in DocBook
32+
-------------------------
33+
34+
Here is an example for using an image in DocBook:
35+
36+
<figure id="gin-internals-figure">
37+
<title>GIN Internals</title>
38+
<mediaobject>
39+
<imageobject>
40+
<imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
41+
</imageobject>
42+
</mediaobject>
43+
</figure>
44+
45+
Notes:
46+
47+
- The real action is in the <mediaobject> element, but typically a
48+
<figure> should be wrapped around it and an <xref> to the figure
49+
should be put into the text somewhere. Don't just put an image into
50+
the documentation without a link to it and an explanation of it.
51+
52+
- Things are set up so that we only need one <imagedata> element, even
53+
with different output formats.
54+
55+
- The attribute format="SVG" is required. If you omit it, it will
56+
still appear to work, but the stylesheets do a better job if the
57+
image is declared as SVG explicitly.
58+
59+
- The width should be set to something. This ensures that the image
60+
is scaled to fit the page in PDF output. (Other widths than 100%
61+
might be appropriate.)

‎doc/src/sgml/images/gin.dot

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
digraph "gin" {
2+
layout=dot;
3+
node [label="", shape=box, style=filled, fillcolor=gray, width=1.4];
4+
5+
m1 [label="meta page"];
6+
7+
subgraph cluster01 {
8+
label="entry tree";
9+
subgraph egroup1 {
10+
rank=same;
11+
e1;
12+
}
13+
subgraph egroup2 {
14+
rank=same;
15+
e2 -> e3 -> e4;
16+
}
17+
subgraph egroup3 {
18+
rank=same;
19+
e5 -> e6 -> e7 -> e8 -> e9;
20+
}
21+
e1 -> e4;
22+
e1 -> e3;
23+
e1 -> e2;
24+
e2 -> e5;
25+
e2 -> e6;
26+
e3 -> e7;
27+
e4 -> e8;
28+
e4 -> e9;
29+
30+
e6 [fillcolor=green, label="posting list"];
31+
e8 [fillcolor=green, label="posting list"];
32+
e9 [fillcolor=green, label="posting list"];
33+
}
34+
35+
subgraph cluster02 {
36+
label="posting tree";
37+
subgraph pgroup1 {
38+
rank=same;
39+
p1;
40+
}
41+
subgraph pgroup2 {
42+
rank=same;
43+
p2 -> p3;
44+
}
45+
p1 -> p2;
46+
p1 -> p3;
47+
48+
p2 [fillcolor=green, label="heap ptr"];
49+
p3 [fillcolor=green, label="heap ptr"];
50+
}
51+
52+
subgraph cluster03 {
53+
label="posting tree";
54+
subgraph pgroup3 {
55+
rank=same;
56+
p4;
57+
}
58+
59+
p4 [fillcolor=green, label="heap ptr"];
60+
}
61+
62+
subgraph cluster04 {
63+
label="posting tree";
64+
subgraph pgroup4 {
65+
rank=same;
66+
p5;
67+
}
68+
subgraph pgroup5 {
69+
rank=same;
70+
p6 -> p7;
71+
}
72+
p5 -> p6;
73+
p5 -> p7;
74+
75+
p6 [fillcolor=green, label="heap ptr"];
76+
p7 [fillcolor=green, label="heap ptr"];
77+
}
78+
79+
subgraph cluster05 {
80+
label="pending list";
81+
node [style=filled, fillcolor=red];
82+
n1 -> n2 -> n3 -> n4;
83+
}
84+
85+
m1 -> e1;
86+
e5 -> p1;
87+
e7 -> p4;
88+
e7 -> p5;
89+
m1 -> n1;
90+
91+
e5 [style=filled, fillcolor=green4];
92+
e7 [style=filled, fillcolor=green4];
93+
}

0 commit comments

Comments
 (0)