Received: from maia.hub.org (maia-5.hub.org [200.46.204.29]) by mail.postgresql.org (Postfix) with ESMTP id 835CF63296A for ; Wed, 30 Jun 2010 19:18:20 -0300 (ADT) Received: from mail.postgresql.org ([200.46.204.86]) by maia.hub.org (mx1.hub.org [200.46.204.29]) (amavisd-maia, port 10024) with ESMTP id 82385-09 for ; Wed, 30 Jun 2010 22:18:09 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from momjian.us (momjian.us [70.90.9.53]) by mail.postgresql.org (Postfix) with ESMTP id 47B28632868 for ; Wed, 30 Jun 2010 19:18:09 -0300 (ADT) Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id o5UMI7Y20379; Wed, 30 Jun 2010 18:18:07 -0400 (EDT) From: Bruce Momjian Message-Id: <201006302218.o5UMI7Y20379@momjian.us> Subject: Re: Documentation and explanatory diagrams In-Reply-To: <4C1564DD.8050405@usit.uio.no> To: Rafael Martinez Date: Wed, 30 Jun 2010 18:18:07 -0400 (EDT) CC: pgsql-docs@postgresql.org X-Mailer: ELM [version 2.4ME+ PL124 (25)] MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="ELM1277936287-24636-1_" Content-Transfer-Encoding: 7bit X-Virus-Scanned: Maia Mailguard 1.0.1 X-Spam-Status: No, hits=0.79 tagged_above=-5 required=5 tests=BAYES_50=0.8, T_RP_MATCHES_RCVD=-0.01 X-Spam-Level: X-Archive-Number: 201006/85 X-Sequence-Number: 5653 --ELM1277936287-24636-1_ Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="US-ASCII" Rafael Martinez wrote: > Sorry for the delay, I got finally some extra time to work on this. > > I am sending you a proposal with 13 diagrams to include in the manual so > we can get an idea of how it will be. If it gets approved I will spend > more time creating and including other diagrams and improving the build > process for including figures into the manual. Great! > I have done this: > > - - Create/convert 13 images with/to DIA (v.0.96.1) and generate a PNG > version of them. > - - Patch the sgml files that will include the images under doc/src/sgml/. > - - Patch the Makefile under doc/src/sgml/ so the images get move to > doc/src/sgml/html/ under the generation of the html manual. I have built an HTML version using your patch: http://momjian.us/expire/pgsql-docs/ Here is a sample doc image: http://momjian.us/expire/pgsql-docs/log-shipping-alternative.html and all images appear here: http://momjian.us/expire/pgsql-docs/img/ > I could test only the generation of the HTML version of the manual. I > have had problems with the generation of the PDF version and I do not > know at the moment if we have to ajust some of the images for the PDF > version. I think PDF will be fine. I can't generate PDF either but once it committed to CVS I will have someone check and make adjustments. > If this proposal gets accepted we should work with: > > - - Automatic generation of PNG files from DIA source under the build > process of the manual. I don't think we want to require dia to build the docs, so we are going to keep the dia and png files in CVS. > - - Testing of the PDF build process with images. > - - Update the text some places to reference the figures. > - - Automatic generation of a Table of Figures > - - Create/convert more figures to include them in the manual. Great. > If you want to generate the html manual with these figures yourself, you > have to do this in a 9.0beta2 source tree.: > > - - Untar the attached file pg_manual_figures.tar.gz under doc/src/sgml/. > This will create an img/ directory with the DIA and PNG files versions > of the figures. > > - - Patch the 9.0beta2 source tree with the attached file > 9.0beta2_pg_manual_figures.patch (patch -p0 -i > 9.0beta2_pg_manual_figures.patch) > > - - Delete the file doc/src/sgml/html-stamp and run make in doc/src/sgml/ > > Well, I will await for your feedback before spending more time on this > just in case I am in the wrong path. I did adjust the file paths sightly and modified the makefile; new patch attached. I did remove the vacuum_full image because the 9.0 vacuum full rewrites the table, rather than modifying it in place. Also, there are two images that need to be updated for every major release; is that something we want to commit to doing? -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + None of us is going to be here forever. + --ELM1277936287-24636-1_ Content-Transfer-Encoding: 7bit Content-Type: text/x-diff Content-Disposition: inline; filename="/pgpatches/doc_figs" Index: doc/src/sgml/Makefile =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/Makefile,v retrieving revision 1.148 diff -c -c -r1.148 Makefile *** doc/src/sgml/Makefile 12 Jun 2010 21:40:31 -0000 1.148 --- doc/src/sgml/Makefile 30 Jun 2010 19:06:22 -0000 *************** *** 93,107 **** --- 93,111 ---- # The draft target creates HTML output in draft mode, without index (for faster build). draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl $(MKDIR_P) html + $(MKDIR_P) html/img $(JADE.html.call) -V draft-mode $< cp $(srcdir)/stylesheet.css html/ + cp $(srcdir)/img/png/*.png html/img/ html: html-stamp html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl $(MKDIR_P) html + $(MKDIR_P) html/img $(JADE.html.call) -i include-index $< cp $(srcdir)/stylesheet.css html/ + cp $(srcdir)/img/png/*.png html/img/ touch $@ # single-page HTML Index: doc/src/sgml/backup.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v retrieving revision 2.156 diff -c -c -r2.156 backup.sgml *** doc/src/sgml/backup.sgml 7 Jun 2010 02:01:08 -0000 2.156 --- doc/src/sgml/backup.sgml 30 Jun 2010 19:06:22 -0000 *************** *** 798,803 **** --- 798,817 ---- + +
+ + PITR - Base Backup + + + + + + PITR - Base Backup + +
+ + Some file system backup tools emit warnings or errors if the files they are trying to copy change while the copy proceeds. Index: doc/src/sgml/cvs.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/cvs.sgml,v retrieving revision 1.52 diff -c -c -r1.52 cvs.sgml *** doc/src/sgml/cvs.sgml 7 Dec 2009 19:19:56 -0000 1.52 --- doc/src/sgml/cvs.sgml 30 Jun 2010 19:06:22 -0000 *************** *** 42,47 **** --- 42,62 ---- +
+ + Lines of code + + + + + + Lines of code + +
+ + + + Our Wiki, and , Index: doc/src/sgml/high-availability.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/high-availability.sgml,v retrieving revision 1.76 diff -c -c -r1.76 high-availability.sgml *** doc/src/sgml/high-availability.sgml 28 Jun 2010 12:30:32 -0000 1.76 --- doc/src/sgml/high-availability.sgml 30 Jun 2010 19:06:22 -0000 *************** *** 671,676 **** --- 671,690 ---- + +
+ + File-based log shipping + + + + + + File-based log shipping + +
+ + If you want to use streaming replication, fill in primary_conninfo with a libpq connection string, including *************** *** 746,751 **** --- 760,779 ---- window. + +
+ + Streaming replication - Record-based log shipping + + + + + + Streaming replication (Record-based log shipping) + +
+ + If you use streaming replication without file-based continuous archiving, you have to set wal_keep_segments in the master *************** *** 949,954 **** --- 977,997 ---- +
+ + File-based log shipping with pg_standby + + + + + + File-based log shipping with pg_standby + +
+ + + + Note that in this mode, the server will apply WAL one file at a time, so if you use the standby server for queries (see Hot Standby), there is a delay between an action in the master and when the *************** *** 1146,1151 **** --- 1189,1209 ---- noted below. + +
+ + Hot-Standby + + + + + + File-based log shipping with pg_standby + +
+ + + User's Overview Index: doc/src/sgml/history.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/history.sgml,v retrieving revision 1.31 diff -c -c -r1.31 history.sgml *** doc/src/sgml/history.sgml 27 Apr 2009 16:27:35 -0000 1.31 --- doc/src/sgml/history.sgml 30 Jun 2010 19:06:22 -0000 *************** *** 216,220 **** --- 216,235 ---- Details about what has happened in PostgreSQL since then can be found in . + + +
+ + PostgreSQL history timeline + + + + + + PostgreSQL history timeline + +
+ + Index: doc/src/sgml/maintenance.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v retrieving revision 1.105 diff -c -c -r1.105 maintenance.sgml *** doc/src/sgml/maintenance.sgml 26 May 2010 23:55:51 -0000 1.105 --- doc/src/sgml/maintenance.sgml 30 Jun 2010 19:06:22 -0000 *************** *** 171,176 **** --- 171,190 ---- +
+ + Standard vacuum + + + + + + Standard vacuum + +
+ + + The usual goal of routine vacuuming is to do standard VACUUMs often enough to avoid needing VACUUM FULL. The autovacuum daemon attempts to work this way, and in fact will Index: doc/src/sgml/manage-ag.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v retrieving revision 2.62 diff -c -c -r2.62 manage-ag.sgml *** doc/src/sgml/manage-ag.sgml 3 Apr 2010 07:22:55 -0000 2.62 --- doc/src/sgml/manage-ag.sgml 30 Jun 2010 19:06:23 -0000 *************** *** 409,414 **** --- 409,428 ---- +
+ + Tablespaces + + + + + + Tablespaces + +
+ + + Tables, indexes, and entire databases can be assigned to particular tablespaces. To do so, a user with the CREATE privilege on a given tablespace must pass the tablespace name as a Index: doc/src/sgml/start.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/start.sgml,v retrieving revision 1.51 diff -c -c -r1.51 start.sgml *** doc/src/sgml/start.sgml 19 Dec 2009 02:34:17 -0000 1.51 --- doc/src/sgml/start.sgml 30 Jun 2010 19:06:23 -0000 *************** *** 118,123 **** --- 118,136 ---- come and go. (All of this is of course invisible to the user. We only mention it here for completeness.) + +
+ + PostgreSQL system architecture overview + + + + + + PostgreSQL system architecture overview + +
+ Index: doc/src/sgml/storage.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/storage.sgml,v retrieving revision 1.32 diff -c -c -r1.32 storage.sgml *** doc/src/sgml/storage.sgml 16 Feb 2010 22:34:43 -0000 1.32 --- doc/src/sgml/storage.sgml 30 Jun 2010 19:06:24 -0000 *************** *** 125,130 **** --- 125,144 ---- +
+ + PostgreSQL File Layout + + + + + + PostgreSQL File Layout + +
+ + + For each database in the cluster there is a subdirectory within PGDATA/base, named after the database's OID in pg_database. This subdirectory is the default location *************** *** 559,564 **** --- 573,592 ---- + +
+ + PostgreSQL Page Layout + + + + + + PostgreSQL Page Layout + +
+ + The first 24 bytes of each page consists of a page header --ELM1277936287-24636-1_--