On 20.02.19 17:28, Peter Eisentraut wrote:
On 2019-02-15 11:58, Jürgen Purtz wrote:
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.
I think we should have some in-tree documentation about how to edit
images, probably at doc/src/sgml/svg/README. You had published some of
that documentation earlier in this thread, and whatever is relevant to
developers should be included in the tree. I'm specifically wondering
about the relationship between the *.svg and the inkscape/*.svg files.
Good idea. README is created. Also chapter "J.4. Documentation
Authoring" has some enhancements to differentiate between text and
graphic. It's also possible that we will see more sub-chapters in J.4 in
the future, e.g.: "Creating Mathematical Formulas".
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
