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 <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
1 parent 477422c commit ea55aec

14 files changed

+602
-6
lines changed

‎.gitattributes

Lines changed: 1 addition & 0 deletions
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

Lines changed: 9 additions & 5 deletions
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

Lines changed: 11 additions & 1 deletion
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

Lines changed: 18 additions & 0 deletions
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

Lines changed: 61 additions & 0 deletions
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

Lines changed: 93 additions & 0 deletions
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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy