From 6eb9c5a5657d1fe77b55cc261450f3538d35a94d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 4 May 2024 14:19:15 +0200 Subject: Adding upstream version 13.4. Signed-off-by: Daniel Baumann --- doc/src/sgml/images/Makefile | 27 +++ doc/src/sgml/images/README | 65 ++++++ doc/src/sgml/images/fixup-svg.xsl | 44 +++++ doc/src/sgml/images/genetic-algorithm.gv | 48 +++++ doc/src/sgml/images/genetic-algorithm.svg | 140 +++++++++++++ doc/src/sgml/images/gin.gv | 93 +++++++++ doc/src/sgml/images/gin.svg | 317 ++++++++++++++++++++++++++++++ doc/src/sgml/images/pagelayout.svg | 35 ++++ doc/src/sgml/images/pagelayout.txt | 11 ++ 9 files changed, 780 insertions(+) create mode 100644 doc/src/sgml/images/Makefile create mode 100644 doc/src/sgml/images/README create mode 100644 doc/src/sgml/images/fixup-svg.xsl create mode 100644 doc/src/sgml/images/genetic-algorithm.gv create mode 100644 doc/src/sgml/images/genetic-algorithm.svg create mode 100644 doc/src/sgml/images/gin.gv create mode 100644 doc/src/sgml/images/gin.svg create mode 100644 doc/src/sgml/images/pagelayout.svg create mode 100644 doc/src/sgml/images/pagelayout.txt (limited to 'doc/src/sgml/images') diff --git a/doc/src/sgml/images/Makefile b/doc/src/sgml/images/Makefile new file mode 100644 index 0000000..f9e3563 --- /dev/null +++ b/doc/src/sgml/images/Makefile @@ -0,0 +1,27 @@ +# doc/src/sgml/images/Makefile +# +# see README in this directory about image handling + +ALL_IMAGES = \ + genetic-algorithm.svg \ + gin.svg \ + pagelayout.svg + +DITAA = ditaa +DOT = dot +XSLTPROC = xsltproc + +all: $(ALL_IMAGES) + +%.svg.tmp: %.gv + $(DOT) -T svg -o $@ $< + +%.svg.tmp: %.txt + $(DITAA) -E -S --svg $< $@ + +# Post-processing for SVG files coming from other tools +# +# Use --novalid to avoid loading SVG DTD if a file specifies it, since +# it might not be available locally, and we don't need it. +%.svg: %.svg.tmp fixup-svg.xsl + $(XSLTPROC) --novalid -o $@ $(word 2,$^) $< diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README new file mode 100644 index 0000000..07c4580 --- /dev/null +++ b/doc/src/sgml/images/README @@ -0,0 +1,65 @@ +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. + +fixup-svg.xsl applies some postprocessing to the SVG files produced by +those external tools to address assorted issues. See comments in +there, and adjust and expand as necessary. + +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/fixup-svg.xsl b/doc/src/sgml/images/fixup-svg.xsl new file mode 100644 index 0000000..d6c46b3 --- /dev/null +++ b/doc/src/sgml/images/fixup-svg.xsl @@ -0,0 +1,44 @@ + + + + + + + + + + + 0 0 + + + + + + + + + + + + none + + + + + + + + + + diff --git a/doc/src/sgml/images/genetic-algorithm.gv b/doc/src/sgml/images/genetic-algorithm.gv new file mode 100644 index 0000000..80c354c --- /dev/null +++ b/doc/src/sgml/images/genetic-algorithm.gv @@ -0,0 +1,48 @@ +digraph { + layout=dot; + + // default values + node [shape=box, label="", fontname="sans-serif", style=filled, fillcolor=white, fontsize=8]; + 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; + + // layout of edges and nodes + splines=ortho; + nodesep=0.3; + ranksep=0.3; + + // nodes + a1[label="INITIALIZE t := 0"]; + a2[label="INITIALIZE P(t)"]; + a3[label="evaluate FITNESS of P(t)"]; + a4[shape="diamond", label="STOPPING CRITERION"; width=4]; + + // connect 'end' node with 'a9' node (bottom of figure) + { + rank=same; + a9[label="t := t + 1"]; + // end-symbol similar to UML notation + end[shape=doublecircle, label="end", width=0.5]; + } + + a5[label="P'(t) := RECOMBINATION{P(t)}"]; + a6[label="P''(t) := MUTATION{P'(t)}"]; + a7[label="P(t+1) := SELECTION{P''(t) + P(t)}"]; + a8[label="evaluate FITNESS of P''(t)"]; + + // edges + a1 -> a2 -> a3 -> a4; + a4 -> a5[xlabel="false ", fontsize=10]; + a4 -> end[xlabel="true ", fontsize=10]; + a5 -> a6 -> a7 -> a8 -> a9; + a4 -> a9 [dir=back]; + + // explain the notation + expl [shape=plaintext, fontsize=10, width=3.2, fillcolor=whitesmoke, + label="P(t): generation of ancestors at a time t\lP''(t): generation of descendants at a time t\l"]; + +} diff --git a/doc/src/sgml/images/genetic-algorithm.svg b/doc/src/sgml/images/genetic-algorithm.svg new file mode 100644 index 0000000..fb9fdd1 --- /dev/null +++ b/doc/src/sgml/images/genetic-algorithm.svg @@ -0,0 +1,140 @@ + + + + + +%3 + + + +a1 + +INITIALIZE t := 0 + + + +a2 + +INITIALIZE P(t) + + + +a1->a2 + + + + + +a3 + +evaluate FITNESS of P(t) + + + +a2->a3 + + + + + +a4 + +STOPPING CRITERION + + + +a3->a4 + + + + + +a9 + +t := t + 1 + + + +a4->a9 + + + + + +end + + +end + + + +a4->end + + +true   + + + +a5 + +P'(t) := RECOMBINATION{P(t)} + + + +a4->a5 + + +false    + + + +a6 + +P''(t) := MUTATION{P'(t)} + + + +a5->a6 + + + + + +a7 + +P(t+1) := SELECTION{P''(t) + P(t)} + + + +a6->a7 + + + + + +a8 + +evaluate FITNESS of P''(t) + + + +a7->a8 + + + + + +a8->a9 + + + + + +expl + +P(t): generation of ancestors at a time t +P''(t): generation of descendants at a time t + + + diff --git a/doc/src/sgml/images/gin.gv b/doc/src/sgml/images/gin.gv new file mode 100644 index 0000000..097e910 --- /dev/null +++ b/doc/src/sgml/images/gin.gv @@ -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 0000000..04fe85b --- /dev/null +++ b/doc/src/sgml/images/gin.svg @@ -0,0 +1,317 @@ + + + + + +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 0000000..5b2caaf --- /dev/null +++ b/doc/src/sgml/images/pagelayout.svg @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + PageHeaderData + Item + ItemId + ItemId + Item + Special + + diff --git a/doc/src/sgml/images/pagelayout.txt b/doc/src/sgml/images/pagelayout.txt new file mode 100644 index 0000000..40bee5d --- /dev/null +++ b/doc/src/sgml/images/pagelayout.txt @@ -0,0 +1,11 @@ ++----------------+--------+--------+--------------------+ +| PageHeaderData | ItemId | ItemId +=--------> | ++----------------+---+----+---+----+ | +| | | | +| | +-----+ | +| +--+------+ | +| | | | +| v v | +| +----------+-----------------+---------+ +| <----=+ Item | Item | Special | ++----------------+----------+-----------------+---------+ -- cgit v1.2.3