Re: TOC: List of Figures
Peter Eisentraut writes: On 2019-07-02 10:13, Jürgen Purtz wrote: After the integration of figures into the documentation it may be helpful to extent the TOC with a 'List of Figures'. Any opinion? If yes: The same for 'List of Tables' and 'List of Examples'? I have never found these useful. What would you use them for? Who goes to the documentation (or any other book-like material) thinking, I'm in the mood to look at some tables today, let's see what's in them. +1. I have a vague recollection that we once had such lists in the TOC (because that was the default behavior for whatever toolchain we were then using) and later took them out precisely because they were useless. Not sure how a list of figures would be any more useful. regards, tom lane The two main reasons for using the documentation are 'reference for concepts and syntax' and 'learning'. For the first issue figures are less important - at least as BNF is not presented graphically. The second issue is important for all persons which are not very familiar with PG. Pedagogues tell us, that learning is done best with different media types, where typical methods are direct speech, videos (see the huge number of learning videos at YouTube), graphics, exercises, reading manuals. In essence, they recommend some kind of 'media changes' within each lesson. Currently our documentation is not much more than a manual, the rising element 'graphics' is and will be tiny small (unless we integrate BNF). To support the didactic method of media changes we should promote graphics with a summarizing list at a prominent place in front of the manual. Kind regards, Jürgen Purtz
Re: TOC: List of Figures
Peter Eisentraut writes: > On 2019-07-02 10:13, Jürgen Purtz wrote: >> After the integration of figures into the documentation it may be >> helpful to extent the TOC with a 'List of Figures'. Any opinion? >> >> If yes: The same for 'List of Tables' and 'List of Examples'? > I have never found these useful. What would you use them for? Who goes > to the documentation (or any other book-like material) thinking, I'm in > the mood to look at some tables today, let's see what's in them. +1. I have a vague recollection that we once had such lists in the TOC (because that was the default behavior for whatever toolchain we were then using) and later took them out precisely because they were useless. Not sure how a list of figures would be any more useful. regards, tom lane
Re: TOC: List of Figures
On 2019-07-02 10:13, Jürgen Purtz wrote: > After the integration of figures into the documentation it may be > helpful to extent the TOC with a 'List of Figures'. Any opinion? > > If yes: The same for 'List of Tables' and 'List of Examples'? I have never found these useful. What would you use them for? Who goes to the documentation (or any other book-like material) thinking, I'm in the mood to look at some tables today, let's see what's in them. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Postgres 11: Table Partitioning and Primary Keys
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/11/ddl-partitioning.html
Description:
In the documentation for Postgres 11 table partitioning, there is no mention
of the requirement that the Primary Key of a partitioned table must contain
the partition key.
In fact the documentation on primary keys is so light that I am not even
100% sure the above is correct. If the following table is not possible in
Postgres 11, the documentation should find some way to make that clear.
-- Create partitioned table with partition key not in primary key
create table events (
id bigint not null default nextval('events_id_seq'),
created_date timestamp not null,
constraint events_pk primary key (id)
) partition by range (created_date);
-- end create table
I believe this should be documented in section "5.10.2.3. Limitations"
Improvement of GIN figure
To increase the consistency between the surrounding, explaining text and
the figure, there are some changes and additions to the texts within the
figure.
Also: Added a hint in README for ditaa developers.
Jürgen Purtz
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..d0442abf15 100644
--- a/doc/src/sgml/images/gin.gv
+++ b/doc/src/sgml/images/gin.gv
@@ -27,9 +27,12 @@ digraph "gin" {
e4 -> e8;
e4 -> e9;
-e6 [fillcolor=green, label="posting list"];
-e8 [fillcolor=green, label="posting list"];
-e9 [fillcolor=green, label="posting list"];
+e5 [fillcolor=green4, label="pointer to\nposting tree"];
+e6 [fillcolor=green, label="posting list"];
+e7 [fillcolor=green4, label="pointer to\nposting tree"];
+e8 [fillcolor=green, label="posting list"];
+e9 [fillcolor=green, label="posting list"];
+
}
subgraph cluster02 {
@@ -45,8 +48,8 @@ digraph "gin" {
p1 -> p2;
p1 -> p3;
-p2 [fillcolor=green, label="heap ptr"];
-p3 [fillcolor=green, label="heap ptr"];
+p2 [fillcolor=green, label="posting list"];
+p3 [fillcolor=green, label="posting list"];
}
subgraph cluster03 {
@@ -56,7 +59,7 @@ digraph "gin" {
p4;
}
-p4 [fillcolor=green, label="heap ptr"];
+p4 [fillcolor=green, label="posting list"];
}
subgraph cluster04 {
@@ -72,14 +75,14 @@ digraph "gin" {
p5 -> p6;
p5 -> p7;
-p6 [fillcolor=green, label="heap ptr"];
-p7 [fillcolor=green, label="heap ptr"];
+p6 [fillcolor=green, label="posting list"];
+p7 [fillcolor=green, label="posting list"];
}
subgraph cluster05 {
label="pending list";
-node [style=filled, fillcolor=red];
-n1 -> n2 -> n3 -> n4;
+node [fillcolor=red, label="pend. entries"];
+n1 -> n2 -> n3 -> n4 -> n5;
}
m1 -> e1;
@@ -88,6 +91,8 @@ digraph "gin" {
e7 -> p5;
m1 -> n1;
-e5 [style=filled, fillcolor=green4];
-e7 [style=filled, fillcolor=green4];
+// An explanation for readers
+expl [shape=plaintext, fillcolor=green, label=" A is a list of heap pointers (row IDs) "];
+p6 -> expl [style=invis];
+
}
