Re: Documentation and explanatory diagrams

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  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + None of us is going to be here forever. +
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 ----
    </orderedlist>
     </para>

+     <para>
+     <figure>
+       <title>
+         PITR - Base Backup
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="pitr.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>PITR - Base Backup</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
     <para>
      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 ----
   </para>

   <para>
+     <figure>
+       <title>
+         Lines of code
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="pg_lines_code.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>Lines of code</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
+
+  <para>
    Our Wiki, <ulink
    url="http://wiki.postgresql.org/wiki/Working_with_CVS"></ulink> and
    <ulink url="http://wiki.postgresql.org/wiki/Working_with_Git"></ulink>,
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 ----
      </para>
     </note>

+     <para>
+     <figure>
+       <title>
+         File-based log shipping
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="file_based_log_shipping.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>File-based log shipping</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
     <para>
       If you want to use streaming replication, fill in
       <varname>primary_conninfo</> with a libpq connection string, including
***************
*** 746,751 ****
--- 760,779 ----
      window.
     </para>

+     <para>
+     <figure>
+       <title>
+         Streaming replication - Record-based log shipping
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="streaming_replication.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>Streaming replication (Record-based log shipping)</phrase></textobject>
+       </mediaobject>
+     </figure>
+    </para>
+
     <para>
      If you use streaming replication without file-based continuous
      archiving, you have to set <varname>wal_keep_segments</> in the master
***************
*** 949,954 ****
--- 977,997 ----
     </para>

     <para>
+     <figure>
+       <title>
+         File-based log shipping with pg_standby
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="pg_standby.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>File-based log shipping with pg_standby</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
+
+    <para>
      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.
     </para>

+    <para>
+     <figure>
+       <title>
+         Hot-Standby
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="hot_standby.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>File-based log shipping with pg_standby</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
+
    <sect2 id="hot-standby-users">
     <title>User's Overview</title>

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 <productname>PostgreSQL</> since
     then can be found in <xref linkend="release">.
    </para>
+
+   <para>
+     <figure>
+       <title>
+         PostgreSQL history timeline
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="postgresql_hist.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>PostgreSQL history timeline</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
   </sect2>
  </sect1>
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 ----
     </para>

     <para>
+     <figure>
+       <title>
+         Standard vacuum
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="vacuum.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>Standard vacuum</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
+    <para>
      The usual goal of routine vacuuming is to do standard <command>VACUUM</>s
      often enough to avoid needing <command>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 ----
    </para>

    <para>
+     <figure>
+       <title>
+         Tablespaces
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="tablespaces.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>Tablespaces</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
+   <para>
     Tables, indexes, and entire databases can be assigned to
     particular tablespaces. To do so, a user with the <literal>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.)
     </para>
+
+    <figure>
+      <title>
+        PostgreSQL system architecture overview
+      </title>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="pgclient_server.png" align="center" format="PNG">
+        </imageobject>
+        <textobject><phrase>PostgreSQL system architecture overview</phrase></textobject>
+      </mediaobject>
+    </figure>
+
    </sect1>


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 ----
  </table>

  <para>
+     <figure>
+       <title>
+         PostgreSQL File Layout
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="pg_dir_layout.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>PostgreSQL File Layout</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
+ <para>
  For each database in the cluster there is a subdirectory within
  <varname>PGDATA</><filename>/base</>, named after the database's OID in
  <structname>pg_database</>.  This subdirectory is the default location
***************
*** 559,564 ****
--- 573,592 ----
  </tgroup>
  </table>

+ <para>
+     <figure>
+       <title>
+         PostgreSQL Page Layout
+       </title>
+       <mediaobject>
+         <imageobject>
+           <imagedata fileref="page_layout.png" align="center" format="PNG">
+         </imageobject>
+         <textobject><phrase>PostgreSQL Page Layout</phrase></textobject>
+       </mediaobject>
+     </figure>
+   </para>
+
   <para>

    The first 24 bytes of each page consists of a page header