Re: Improvement of GIN figure
Jürgen Purtz <[email protected]>
| Newsgroups | gmane.comp.db.postgresql.devel.documentation |
|---|---|
| Message-ID | <[email protected]> |
> On Tue, Jul 9, 2019 at 3:22 PM Tatsuo Ishii <[email protected]> wrote: >>> I agree that the existing colors look awful, and that muted pastel >>> colors would work better. Doesn't seem like something that should >>> happen at the cost of making the diagram less informative, though. >> I am not an expert in the area but I think we should cosider people >> with color disability. > Good point. I think that that shouldn't be too hard to mostly get right. > > It's good that the diagrams will already work with a screen reader. > Due to the discussions of recent days as well as some improvements of the graphiz know-how, the graphic is subject to many changes: different colors (variations of 'PG blue', and possibly helpful for people with color vision deficiency), a different font (adaption to the font in PG's documentation), changes in the meaning and explanation of nodes (as a result of discussion with Oleg Bartunov), introduction of a - hopefully unobtrusive - background color (to circumvent graphic from text), use of DOT syntax.
gin.patch
(text/x-patch, 6.4 KB)
diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README
index 07c4580255..c451d4bca4 100644
--- a/doc/src/sgml/images/README
+++ b/doc/src/sgml/images/README
@@ -13,7 +13,8 @@ involve diffable source files.
These tools are acceptable:
- Graphviz (https://graphviz.org/)
-- Ditaa (http://ditaa.sourceforge.net/)
+- Ditaa (https://github.com/stathissideris/ditaa), version 0.11 or
+ higher. Previous versions does not support SVG.
We use SVG as the format for integrating the image into the ultimate
output formats of the documentation, that is, HTML, PDF, and others.
diff --git a/doc/src/sgml/images/gin.gv b/doc/src/sgml/images/gin.gv
index 097e91029a..35520736ec 100644
--- a/doc/src/sgml/images/gin.gv
+++ b/doc/src/sgml/images/gin.gv
@@ -1,85 +1,101 @@
digraph "gin" {
+
layout=dot;
- node [label="", shape=box, style=filled, fillcolor=gray, width=1.4];
- m1 [label="meta page"];
+ // default values
+ node [shape=box, label="", fontname="sans-serif", style=filled, fillcolor=lightgray, width=1.4];
+ graph [fontname="sans-serif"]; // must be specified separately
+ edge [fontname="sans-serif"]; // must be specified separately
+
+ // an unobtrusive background color
+ pad="1.0, 0.5";
+ bgcolor=whitesmoke;
+ // The top node
+ m1 [label="meta page", style=filled, fillcolor=beige];
+
+ // other nodes
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"];
+ bgcolor=white;
+ 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;
+
+ e5 [fillcolor=cyan];
+ e6 [fillcolor=cyan];
+ e7 [fillcolor=cyan];
+ e8 [fillcolor=cyan];
+ e9 [fillcolor=cyan];
+
}
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"];
+ bgcolor=white;
+ label="posting tree";
+ subgraph pgroup1 {
+ p1;
+ }
+ subgraph pgroup2 {
+ rank=same;
+ p2 -> p3;
+ }
+ p1 -> p2;
+ p1 -> p3;
+
+ p2 [fillcolor=deepskyblue];
+ p3 [fillcolor=deepskyblue];
}
subgraph cluster03 {
- label="posting tree";
- subgraph pgroup3 {
- rank=same;
- p4;
- }
+ bgcolor=white;
+ label="posting tree";
+ subgraph pgroup3 {
+ p4;
+ }
- p4 [fillcolor=green, label="heap ptr"];
+ p4 [fillcolor=deepskyblue];
}
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"];
+ bgcolor=white;
+ label="posting tree";
+ subgraph pgroup4 {
+ p5;
+ }
+ subgraph pgroup5 {
+ rank=same;
+ p6 -> p7;
+ }
+ p5 -> p6;
+ p5 -> p7;
+
+ p6 [fillcolor=deepskyblue];
+ p7 [fillcolor=deepskyblue];
}
subgraph cluster05 {
- label="pending list";
- node [style=filled, fillcolor=red];
- n1 -> n2 -> n3 -> n4;
+ bgcolor=white;
+ label="pending list";
+ node [fillcolor=wheat, label="pending entries", width=1.8];
+ n1 -> n2 -> n3 -> n4 -> n5;
}
m1 -> e1;
@@ -88,6 +104,12 @@ digraph "gin" {
e7 -> p5;
m1 -> n1;
- e5 [style=filled, fillcolor=green4];
- e7 [style=filled, fillcolor=green4];
+ // Explanations
+ expl_1 [shape=plaintext, width=2.5, label="Internal tree node"];
+ expl_2 [shape=plaintext, fillcolor=cyan, width=5.2, label="<posting list> and/or pointer to <posting tree>"];
+ expl_3 [shape=plaintext, fillcolor=deepskyblue, width=2.0, label="Only <posting list>"];
+ p6 -> expl_1 [style=invis];
+ p6 -> expl_2 [style=invis];
+ p6 -> expl_3 [style=invis];
+
}
gin.gv
(text/vnd.graphviz, 3.3 KB)
digraph "gin" {
layout=dot;
// default values
node [shape=box, label="", fontname="sans-serif", style=filled, fillcolor=lightgray, width=1.4];
graph [fontname="sans-serif"]; // must be specified separately
edge [fontname="sans-serif"]; // must be specified separately
// an unobtrusive background color
pad="1.0, 0.5";
bgcolor=whitesmoke;
// The top node
m1 [label="meta page", style=filled, fillcolor=beige];
// other nodes
subgraph cluster01 {
bgcolor=white;
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;
e5 [fillcolor=cyan];
e6 [fillcolor=cyan];
e7 [fillcolor=cyan];
e8 [fillcolor=cyan];
e9 [fillcolor=cyan];
}
subgraph cluster02 {
bgcolor=white;
label="posting tree";
subgraph pgroup1 {
p1;
}
subgraph pgroup2 {
rank=same;
p2 -> p3;
}
p1 -> p2;
p1 -> p3;
p2 [fillcolor=deepskyblue];
p3 [fillcolor=deepskyblue];
}
subgraph cluster03 {
bgcolor=white;
label="posting tree";
subgraph pgroup3 {
p4;
}
p4 [fillcolor=deepskyblue];
}
subgraph cluster04 {
bgcolor=white;
label="posting tree";
subgraph pgroup4 {
p5;
}
subgraph pgroup5 {
rank=same;
p6 -> p7;
}
p5 -> p6;
p5 -> p7;
p6 [fillcolor=deepskyblue];
p7 [fillcolor=deepskyblue];
}
subgraph cluster05 {
bgcolor=white;
label="pending list";
node [fillcolor=wheat, label="pending entries", width=1.8];
n1 -> n2 -> n3 -> n4 -> n5;
}
m1 -> e1;
e5 -> p1;
e7 -> p4;
e7 -> p5;
m1 -> n1;
// Explanations
expl_1 [shape=plaintext, width=2.5, label="Internal tree node"];
expl_2 [shape=plaintext, fillcolor=cyan, width=5.2, label="<posting list> and/or pointer to <posting tree>"];
expl_3 [shape=plaintext, fillcolor=deepskyblue, width=2.0, label="Only <posting list>"];
p6 -> expl_1 [style=invis];
p6 -> expl_2 [style=invis];
p6 -> expl_3 [style=invis];
}
Screenshot from 2019-07-13 12-07-08.png
(image/png, 39.3 KB) - not displayed