mirror of https://github.com/postgres/postgres
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.depull/40/head
Peter Eisentraut
6 years ago
parent
477422c9d1
commit
ea55aec0a9
@ -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 $< $@
|
||||
@ -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: |
||||
|
||||
<figure id="gin-internals-figure"> |
||||
<title>GIN Internals</title> |
||||
<mediaobject> |
||||
<imageobject> |
||||
<imagedata fileref="images/gin.svg" format="SVG" width="100%"/> |
||||
</imageobject> |
||||
</mediaobject> |
||||
</figure> |
||||
|
||||
Notes: |
||||
|
||||
- The real action is in the <mediaobject> element, but typically a |
||||
<figure> should be wrapped around it and an <xref> 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 <imagedata> 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.) |
||||
@ -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]; |
||||
} |
||||
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 4.0 KiB |
@ -0,0 +1,11 @@ |
||||
+----------------+--------+--------+--------------------+ |
||||
| PageHeaderData | ItemId | ItemId +=--------> | |
||||
+----------------+---+----+---+----+ | |
||||
| | | | |
||||
| | +-----+ | |
||||
| +--+------+ | |
||||
| | | | |
||||
| v v | |
||||
| +----------+-----------------+---------+ |
||||
| <----=+ Item | Item | Special | |
||||
+----------------+----------+-----------------+---------+ |
||||
Loading…
Reference in new issue