New vs old values collision in UPDATE RETURNING docs

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/11/sql-update.html
Description:

What we have in doc:

[ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
output_expression: An expression to be computed and returned by the UPDATE
command after each row is updated.

What we have in the wild (Pg8..11):
* when using field names, expression represents NEW values after update;
* when using sub-selects or joined table references, expression represents
OLD values before update.

POC code:

create temporary table test(id int primary key, status text not null);

insert into test(id, status) values(1, 'initial');

update test t set status='new'
where id=1
returning id,
status as new_status,
(select status from test where id=t.id) as old_status;


Thus that "after each row is updated" sentence is rather confusing.

/Alexey

Re: First SVG graphic

[Jürgen Purtz]

The graphic for dump/restore is transferred from 'pg_dump utility' 
chapter to the 'backup and restore' chapter in sgml/backup.sgml. In this 
chapter I made a lot of textual changes to explain the relation between 
pg_dump, pg_restore and psql in more detail. Especially I tried to 
introduce a more stringent use of terms, eg: avoiding 'archive' because 
this term is used with a different meaning in the PITR chapter. (It 
would be a good idea to do the same for the description of the pg_dump 
utility.) Because I'm not a native English speaker, feel free to correct 
my wording.


The list of figures as well as lists of other prominent elements are 
removed. 'lists in TOC' seems to be a topic of its own and will be 
resumed later.


Kind regards, Jürgen


diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 8326c7c673..12997e903c 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -57,6 +57,8 @@ GENERATED_SGML = version.sgml \
 
 ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
 
+ALLSVG := $(wildcard $(srcdir)/svg/*.svg)
+
 
 ##
 ## Man pages
@@ -125,10 +127,12 @@ endif
 
 html: html-stamp
 
-html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML)
+html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALLSVG)
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
 	cp $(srcdir)/stylesheet.css html/
+	$(MKDIR_P) html/svg
+	cp $(ALLSVG) html/svg
 	touch $@
 
 htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
@@ -136,7 +140,7 @@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
 
 # single-page HTML
-postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML)
+postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) $(ALLSVG)
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
 
@@ -160,7 +164,7 @@ postgres.pdf:
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
 
-%.pdf: %.fo
+%.pdf: %.fo $(ALLSVG)
 	$(FOP) -fo $< -pdf $@
 
 
@@ -169,7 +173,7 @@ postgres.pdf:
 ##
 
 epub: postgres.epub
-postgres.epub: postgres.sgml $(ALLSGML)
+postgres.epub: postgres.sgml $(ALLSGML) $(ALLSVG)
 	$(XMLLINT) --noout --valid $<
 	$(DBTOEPUB) $<
 
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index a73fd4d044..f192ea3b52 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -16,7 +16,7 @@
   There are three fundamentally different approaches to backing up
   PostgreSQL data:
   
-   SQL dump
+   Dump into SQL INSERT syntax or a binary format
File system level backup
Continuous archiving
   
@@ -25,23 +25,28 @@
  
 
  
-  SQL Dump
+  Dump
 
   
-   The idea behind this dump method is to generate a file with SQL
-   commands that, when fed back to the server, will recreate the
-   database in the same state as it was at the time of the dump.
+   The idea behind this dump technique is to generate a file
+   that, when fed back to the server, will recreate the
+   database in the same state as it was at the time of the dump generation.
+  
+
+  
+   Creating the Dump
+  
PostgreSQL provides the utility program
 for this purpose. The basic usage of this
command is:
 
 pg_dump dbname  dumpfile
 
-   As you see, pg_dump writes its result to the
+   As you see, pg_dump in this basic form writes its result to the
standard output. We will see below how this can be useful.
-   While the above command creates a text file, pg_dump
-   can create files in other formats that allow for parallelism and more
-   fine-grained control of object restoration.
+   While the above command creates a plain-text SQL script, pg_dump
+   can create files also in other, dense binary formats that allow for parallelism and more
+   fine-grained control of object restoration, see: 
   
 
   
@@ -100,12 +105,13 @@ pg_dump dbname  ALTER TABLE.)
   
+  
 
   
Restoring the Dump
 

-Text files created by pg_dump are intended to
+Such plain-text SQL scripts created by pg_dump are intended to
 be read in by the psql program. The
 general command form to restore a dump is
 
@@ -121,8 +127,6 @@ psql dbname  pg_dump for specifying
 the database server to connect to and the user name to use. See
 the  reference page for more information.
-Non-text file dumps are restored using the  utility.

 

@@ -239,12 +243,12 @@ psql -f dumpfile postgres
 Some operating systems have maximum file size limits that cause
 problems when creating large pg_dump output files.
 Fortunately, pg_dump can write to the standard
-output, so you can use standard Unix tools to work around this
+output, so you can use standard tools to work around this