Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gxaj4-0000MN-TR for pgsql-docs@arkaria.postgresql.org; Sat, 23 Feb 2019 17:04:35 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1gxaj1-0002Bg-Gf for pgsql-docs@arkaria.postgresql.org; Sat, 23 Feb 2019 17:04:31 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gxaj0-0002BS-Tw for pgsql-docs@lists.postgresql.org; Sat, 23 Feb 2019 17:04:31 +0000 Received: from mout.kundenserver.de ([217.72.192.74]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gxaiv-0006oK-7e for pgsql-docs@lists.postgresql.org; Sat, 23 Feb 2019 17:04:29 +0000 Received: from [192.168.178.23] ([77.179.9.116]) by mrelayeu.kundenserver.de (mreue106 [212.227.15.183]) with ESMTPSA (Nemesis) id 1MPGmZ-1geWAS37t7-00Phc2 for ; Sat, 23 Feb 2019 18:04:21 +0100 Subject: Re: First SVG graphic To: pgsql-docs@lists.postgresql.org References: <0e0b8e73-cc7c-0557-c76f-35d9592eb50e@purtz.de> <20190117174053.GC10895@momjian.us> <20190118.074307.1409947743977067766.t-ishii@sraoss.co.jp> <2e5ef806-c4f8-3fe7-e9a4-4fcfd124568e@purtz.de> <20190123235312.GB8334@momjian.us> <6a97acaf-06e8-519c-a4ff-04a13e0d2675@2ndquadrant.com> <5ad6b96d-47d0-eb08-edc4-803645d2fd31@purtz.de> <4393cdcd-4efd-3198-4ffc-c080a5af79c7@2ndquadrant.com> <55a6a8cb-bfaa-e5a6-4596-82f445f1ec7c@2ndquadrant.com> <86af349c-5bcb-a28c-d858-c5cb0a283cd2@purtz.de> From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= Message-ID: <808a932e-bc40-d57e-7de2-5e4fd9a24ac6@purtz.de> Date: Sat, 23 Feb 2019 18:06:55 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.4.0 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/mixed; boundary="------------E2BBD25C6263F6E8A87C7BD6" Content-Language: en-AU X-Provags-ID: V03:K1:rTgAOj9LrY+hNiyxxR1mzsOvclHMs2lv3YoWTEq8SHO6YD/QDxu HAcqHGpoJYJduxvvhOOZRlyL+IIPWODBENvttCPQqgloMluWhtZl6LgB4xwqIKpuTOPQssz 8w7E/1gTMPhJq/19fl35DblgjkbJuNXcCrJv6KU01inkRxB3KhuNh/xkNKHDP52NUeiYHVz oHfaoax1iRS292FAU/Nmw== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:MZ9rTjMEn6k=:ClXhNmXQtukx7TxcgVw7f2 x4gz5Smsuu7hUY7MTki/3b4gK3uhpvEGOVfBIOyA8Zpcw6GjxMLJOaiDodVQgvFvlts6kGexB DviQYAPsIQGQeK3w8LDxBuUZkc341Kvly8/PHIs3xggZ+sumu6eOaFRjkxSMYARrzf4vfvujB S1c4RHqpIyPoJJ8BfeTKEkg8pg7oBizqqvW5l3X/jXB3gY3q/4DhjxHyn28kbDT9SIlkoBkZv KElq8Rm7fVr2RLYvJ7+FxEl9wzuwQnVu3mESbFdbuYvf39uOw1REbiif14xfcAGBttjpwxu63 29io/pJXK6lCvAlnBNhzd25R7E8ibnKM1BlHbvpH6MPElwnyIj7ZpKw+vDbl28Ril6PqOE8jG Mgd9Lf8XJA/Q+PeSA3sWDukj/FRlKuxduEkcmS2Lz+XvjtdwT2BIwlCN2PJOEkby61sxhls47 lfdcIW+dYDB2+QdC+DQMlmCiqfFOg+SzvTPBc1w+XdCOQtpR79DZdd6Y0wUxK1938Bt1Su2ef +zkKGVHkr/cgiCvVrOTFxNHTabOZaP5TpoPrP2SMBMyhrJMIFEaTprKkNoiLxNJD2O/xwT2ks d2Zm8vGfqYaBG3rROFiRS+s1K/pdMU7NVGCSpkk02WXnh1EFEFh0GBZKg4PopUqfUC0rbA12K KP9EIHdNIylHto0WCkCToyfWA0oztKiTOSiqqrW5cxAENMfG8xxPjz+fWwqghk5XGItYSRXPy Y+ferFi5qAw0klhzLCAru1sXVbxw/fGjUbVqUQ== List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is a multi-part message in MIME format. --------------E2BBD25C6263F6E8A87C7BD6 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit 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 --------------E2BBD25C6263F6E8A87C7BD6 Content-Type: text/x-patch; name="firstSvg_5.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="firstSvg_5.patch" 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 @@ - <acronym>SQL</acronym> 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 potential problem. There are several possible methods: - Use compressed dumps. + Compress dumps. You can use your favorite compression program, for example gzip: @@ -268,7 +272,7 @@ cat filename.gz | gunzip | psql - Use <command>split</command>. + Split dumps. The split command allows you to split the output into smaller files that are @@ -287,22 +291,57 @@ cat filename* | psql - - Use <application>pg_dump</application>'s custom dump format. + + Use binary formats. + + In addition to the above mentioned plain-text SQL script format pg_dump + can create its output files in denser, binary formats: custom, + directory, and tar. + Dumps in such binary formats are restored using the utility program + instead of psql. + + + + +
+ <command>pg_dump</command>, <command>psql</command>, and <command>pg_restore</command>: + Dump Formats and Restore Proceedings + pg_dump + Dump Formats and Restore Proceedings (Figure) + + pg_restore + Dump Formats and Restore Proceedings (Figure) + + backup + Dump Formats and Restore Proceedings (Figure) + + + + + + + + + +
+ + If PostgreSQL was built on a system with the - zlib compression library installed, the custom dump + zlib compression library installed, the + custom dump format will compress data as it writes it to the output file. This will produce dump file sizes similar to using gzip, but it has the added advantage that tables can be restored selectively. The - following command dumps a database using the custom dump format: + following command dumps a database using the custom dump format: pg_dump -Fc dbname > filename - A custom-format dump is not a script for psql, but - instead must be restored with pg_restore, for example: + As mentioned above dumps in custom format are binary + and not plain-text SQL scripts, they must be restored with pg_restore + instead of psql, for example: pg_restore -d dbname filename @@ -311,11 +350,10 @@ pg_restore -d dbname and reference pages for details. - For very large databases, you might need to combine split - with one of the other two approaches. + with one of the other approaches. @@ -325,15 +363,16 @@ pg_restore -d dbname pg_dump's parallel mode. This will dump multiple tables at the same time. You can control the degree of parallelism with the -j parameter. Parallel dumps - are only supported for the "directory" archive format. + are only supported for the directory format. pg_dump -j num -F d -f out.dir dbname You can use pg_restore -j to restore a dump in parallel. - This will work for any archive of either the "custom" or the "directory" - archive mode, whether or not it has been created with pg_dump -j. + This will work for any dump output of either the custom + or the directory + format, whether or not it has been created with pg_dump -j. diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 0608b8c612..5ccc24833e 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -389,21 +389,21 @@ ADDITIONAL_FLAGS='-Xmx1500m' Documentation Authoring - The documentation sources are most conveniently modified with an editor - that has a mode for editing XML, and even more so if it has some awareness - of XML schema languages so that it can know about - DocBook syntax specifically. - - - - Note that for historical reasons the documentation source files are named + Note that for historical reasons most of the documentation source files are named with an extension .sgml even though they are now XML files. So you might need to adjust your editor configuration to set the correct mode. - Emacs + Textual Parts and Emacs + + + The documentation's textual parts are most conveniently modified with an editor + that has a mode for editing XML, and even more so if it has some awareness + of XML schema languages so that it can know about + DocBook syntax specifically. + nXML Mode, which ships with @@ -422,6 +422,43 @@ ADDITIONAL_FLAGS='-Xmx1500m' + + Graphic Elements + + + Graphics - which are a figure in Docbook speach + - visualize complex situations or behaviour. They provide an + additional way for easy understanding what is described in the + text parts. Authors create them in SVG format + with any SVG tool of their choice. + + + + Such tools show two disadvantages: They tend to use their own, + unportable enhancements and they produce extremely verbose, + unreadable source files. To overcome such drawbacks authors + shall create two files for every single graphic: one in + Optimized SVG format and another one in the + tool-specific SVG format. Both files + render to the same graphic. This enables 'diff-ability' (on the + Optimized SVG file) as well as the use of the + powerful tool-specific variant in any future. Both files are + stored in the repository, but only the Optimized SVG + variant is the liable one and included into the + PostgreSQL documentation. + + + + This approach as well as the overall directory structure is + explained in more detail in doc/src/sgml/svg/README. + In addition, there are many more hints in + PostgreSQL's wiki within the + + category SVG. + + + + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 86ff4e5c9e..ef299dd7f3 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -11228,17 +11228,18 @@ table2-mapping As an example of using the output produced by these functions, - shows an XSLT stylesheet that - converts the output of + the following shows + an XSLT stylesheet that converts the output of table_to_xml_and_xmlschema to an HTML document containing a tabular rendition of the table data. In a similar manner, the results from these functions can be converted into other XML-based formats. -
+ XSLT Stylesheet for Converting SQL/XML Output to HTML - + ]]> -
+ + diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index cc7cd1ed2c..7e49254afe 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -453,6 +453,23 @@ key values for different columns can be of different types. +
+ GIN Overview + + index + GIN + GIN (Figure) + + + + + + + + + +
+ GIN Fast Update Technique diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index cbdad0c3fb..d630366a9a 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -776,6 +776,19 @@ data. Empty in ordinary tables. +
+ Overall Page Layout + Page Layout (Figure) + + + + + + + + +
+ The first 24 bytes of each page consists of a page header diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl index ffd2012e91..9e756708f5 100644 --- a/doc/src/sgml/stylesheet-html-nochunk.xsl +++ b/doc/src/sgml/stylesheet-html-nochunk.xsl @@ -9,4 +9,27 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/doc/src/sgml/svg/README b/doc/src/sgml/svg/README new file mode 100644 index 0000000000..c4bd61151d --- /dev/null +++ b/doc/src/sgml/svg/README @@ -0,0 +1,93 @@ + + +Graphics in PG ('figure' in Docbook speach) use the SVG +format. PG stores two different SVG files per graphic in +the repository: a simple, more generic one to create the +documentation and a tool-specific one for future modifications +of the graphic. The reason for this approach and the directory +layout are explained here. + +A more detailed description concerning the creation of graphics +(compatibility rules, fonts, sizes, colors, general hints, +tool-specific hints, ...) are listed in the wiki under the +category 'SVG': + + https://wiki.postgresql.org/wiki/Category:SVG + + +Two files per graphic +===================== + +An author can use any SVG tool of his choice to create SVG graphics. +However, these tools create tool-specific SVG files which suffer +from some major disadvantages: + - they are tool-specific + - they tend to use the tool's own, unportable enhancements and + - they produce extremely verbose, unreadable source files. +To overcome such disadvantages authors shall store two different +files per graphic after they have finished their work: one in the +original tool-specific format and another one in a simple, +less powerful but portable and short format, which is mostly +called the 'Optimized SVG' format. This format typically misses +enhanced features like 'connectors' or 'groups'. + +Both files render to the same graphic. Both are stored in the +repository, but only the 'Optimized SVG' variant is the liable +one and included into the generated PostgreSQL documentation. + +For future versions of the graphic the tool-specific file +can be used as the basis of enhancements. The 'Optimized SVG' +file serves for diffs. + +The 'Optimized SVG' file is mandatory, the tool-specific +one is optional. + + +Directory Structure +=================== + +The text files, which include the graphics, reside - as usual - +in doc/src/sgml. The SVG files, which are included by the text +files and used for the documentation generation, reside in +doc/src/sgml/, their tool-specific counterpart in subdirectories, +which reflect the name of the tool: + +doc/src/sgml/ # usual text files with extension .sgml +doc/src/sgml/svg # SVG files in 'Optimized SVG' format +doc/src/sgml/svg/inkscape # SVG files in Inkscape specific format +doc/src/sgml/svg/ # SVG files in the format of another tool + ... + ... + + +Limitation +========== + +Man pages are created out of files in the sgml/ref/ subdirectory. +If such a file contains a graphic, the generated man page looks +a little ugly. Please avoid such situations and include graphics +only into files of the sgml/ directory. + + +Include graphics in text +======================== + +Graphics (
element) can be included in and in many other +Docbook elements, e.g.: + + + lorem ipsum ... +
+ Overall Page Layout + Page Layout (Figure) + + + + + + + + +
+ lorem ipsum ... + diff --git a/doc/src/sgml/svg/gin.svg b/doc/src/sgml/svg/gin.svg new file mode 100644 index 0000000000..9ea11f8b1f --- /dev/null +++ b/doc/src/sgml/svg/gin.svg @@ -0,0 +1,123 @@ + + + + + + + + + + + + + + Meta page + + + + Entry tree + + + + + + + + + + + + + + + + + + + + + + + + + + + + Posting tree + + + + + + + + + + + Posting tree + + + + + + Posting tree + + + + + + + + + + + Pending list + + + + + + + + + + + + Pointers to Posting tree + + Heap pointers (in Posting list or Posting tree) + + diff --git a/doc/src/sgml/svg/inkscape/gin_inkscape.svg b/doc/src/sgml/svg/inkscape/gin_inkscape.svg new file mode 100644 index 0000000000..be9a9b4c73 --- /dev/null +++ b/doc/src/sgml/svg/inkscape/gin_inkscape.svg @@ -0,0 +1,124 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + Meta page + + + Entry tree + + + + + + + + + + + + + + + + + + + + + + + + + + + Posting tree + + + + + + + + + + Posting tree + + + + + Posting tree + + + + + + + + + + Pending list + + + + + + + + + + + Pointers to Posting tree + + Heap pointers (in Posting list or Posting tree) + diff --git a/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg b/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg new file mode 100644 index 0000000000..5803077781 --- /dev/null +++ b/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg @@ -0,0 +1,81 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + Page Layout + 8 k B + Free space + + + Header + + ItemId + + ItemId + + + + + + + + Item + + + Item + + Special + + Content grows from start to center and from end to center. + diff --git a/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg b/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg new file mode 100644 index 0000000000..967ca9966a --- /dev/null +++ b/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg @@ -0,0 +1,102 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Original + Database + + pg_dump, plain-text format + + pg_dump, other formats + + + + + SQL INSERT + commands + + psql + + + + + Binary + File(s) + + pg_restore + + + + + Restored + Database + + diff --git a/doc/src/sgml/svg/pagelayout.svg b/doc/src/sgml/svg/pagelayout.svg new file mode 100644 index 0000000000..223fcaf749 --- /dev/null +++ b/doc/src/sgml/svg/pagelayout.svg @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + Page Layout + 8 k B + Free space + + + + Header + + ItemId + + ItemId + + + + + + + + Item + + Item + + Special + + + Content grows from start to center and from end to center. + + diff --git a/doc/src/sgml/svg/pgdump.svg b/doc/src/sgml/svg/pgdump.svg new file mode 100644 index 0000000000..c327136de4 --- /dev/null +++ b/doc/src/sgml/svg/pgdump.svg @@ -0,0 +1,95 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Original + Database + + pg_dump, plain-text format + + pg_dump, other formats + + + + + + SQL INSERT + commands + + psql + + + + + + Binary + File(s) + + pg_restore + + + + + + Restored + Database + + + --------------E2BBD25C6263F6E8A87C7BD6--