Make an editorial pass over the newly SGML-ified contrib documentation.

Fix lots of bad markup, bad English, bad explanations.

This commit covers only about half the contrib modules, but I grow weary...

Author: tglsfdc

doc/src/sgml/adminpack.sgml

@@ -1,36 +1,40 @@
+<!-- $PostgreSQL: pgsql/doc/src/sgml/adminpack.sgml,v 1.3 2007/12/06 04:12:09 tgl Exp $ -->
+
 <sect1 id="adminpack">
  <title>adminpack</title>
- 
+
  <indexterm zone="adminpack">
   <primary>adminpack</primary>
  </indexterm>
 
  <para>
-  adminpack is a PostgreSQL standard module that implements a number of
-  support functions which pgAdmin and other administration and management tools
-  can use to provide additional functionality if installed on a server.
+  <filename>adminpack</> provides a number of support functions which
+  <application>pgAdmin</> and other administration and management tools can
+  use to provide additional functionality, such as remote management
+  of server log files.
  </para>
 
  <sect2>
   <title>Functions implemented</title>
+
   <para>
-   Functions implemented by adminpack can only be run by a superuser. Here's a 
-   list of these functions:
-  </para>
-  <para>
-   <programlisting>
-    int8 pg_catalog.pg_file_write(fname text, data text, append bool)
-    bool pg_catalog.pg_file_rename(oldname text, newname text, archivname text)
-    bool pg_catalog.pg_file_rename(oldname text, newname text)
-    bool pg_catalog.pg_file_unlink(fname text)
-    setof record pg_catalog.pg_logdir_ls()
-
-    /* Renaming of existing backend functions for pgAdmin compatibility */
-    int8 pg_catalog.pg_file_read(fname text, data text, append bool)
-    bigint pg_catalog.pg_file_length(text)
-    int4 pg_catalog.pg_logfile_rotate()
-   </programlisting>
+   The functions implemented by <filename>adminpack</> can only be run by a
+   superuser. Here's a list of these functions:
+
+<programlisting>
+int8 pg_catalog.pg_file_write(fname text, data text, append bool)
+bool pg_catalog.pg_file_rename(oldname text, newname text, archivename text)
+bool pg_catalog.pg_file_rename(oldname text, newname text)
+bool pg_catalog.pg_file_unlink(fname text)
+setof record pg_catalog.pg_logdir_ls()
+
+/* Renaming of existing backend functions for pgAdmin compatibility */
+int8 pg_catalog.pg_file_read(fname text, data text, append bool)
+bigint pg_catalog.pg_file_length(text)
+int4 pg_catalog.pg_logfile_rotate()
+</programlisting>
   </para>
+
  </sect2>
 
 </sect1>

doc/src/sgml/btree-gist.sgml

@@ -1,37 +1,56 @@
+<!-- $PostgreSQL: pgsql/doc/src/sgml/btree-gist.sgml,v 1.4 2007/12/06 04:12:09 tgl Exp $ -->
+
 <sect1 id="btree-gist">
  <title>btree_gist</title>
- 
+
  <indexterm zone="btree-gist">
   <primary>btree_gist</primary>
  </indexterm>
 
  <para>
-  btree_gist is a B-Tree implementation using GiST that supports the int2, int4,
-  int8, float4, float8 timestamp with/without time zone, time
-  with/without time zone, date, interval, oid, money, macaddr, char,
-  varchar/text, bytea, numeric, bit, varbit and inet/cidr types.
+  <filename>btree_gist</> provides sample GiST operator classes that
+  implement B-Tree equivalent behavior for the data types
+  <type>int2</>, <type>int4</>, <type>int8</>, <type>float4</>,
+  <type>float8</>, <type>numeric</>, <type>timestamp with time zone</>,
+  <type>timestamp without time zone</>, <type>time with time zone</>,
+  <type>time without time zone</>, <type>date</>, <type>interval</>,
+  <type>oid</>, <type>money</>, <type>char</>,
+  <type>varchar</>, <type>text</>, <type>bytea</>, <type>bit</>,
+  <type>varbit</>, <type>macaddr</>, <type>inet</>, and <type>cidr</>.
+ </para>
+
+ <para>
+  In general, these operator classes will not outperform the equivalent
+  standard btree index methods, and they lack one major feature of the
+  standard btree code: the ability to enforce uniqueness.  However,
+  they are useful for GiST testing and as a base for developing other
+  GiST operator classes.
  </para>
 
  <sect2>
   <title>Example usage</title>
-  <programlisting>
-   CREATE TABLE test (a int4);
-   -- create index
-   CREATE INDEX testidx ON test USING gist (a);
-   -- query
-   SELECT * FROM test WHERE a &lt; 10;
-  </programlisting>
+
+<programlisting>
+CREATE TABLE test (a int4);
+-- create index
+CREATE INDEX testidx ON test USING gist (a);
+-- query
+SELECT * FROM test WHERE a &lt; 10;
+</programlisting>
+
  </sect2>
- 
+
  <sect2>
   <title>Authors</title>
+
   <para>
-   All work was done by Teodor Sigaev (<email>teodor@stack.net</email>) , 
-   Oleg Bartunov (<email>oleg@sai.msu.su</email>), Janko Richter 
-   (<email>jankorichter@yahoo.de</email>).  See 
-   <ulink url="http://www.sai.msu.su/~megera/postgres/gist"></ulink> for additional 
-   information.
+   Teodor Sigaev (<email>teodor@stack.net</email>) ,
+   Oleg Bartunov (<email>oleg@sai.msu.su</email>), and
+   Janko Richter (<email>jankorichter@yahoo.de</email>).  See
+   <ulink url="http://www.sai.msu.su/~megera/postgres/gist"></ulink>
+   for additional information.
   </para>
+
  </sect2>
 
 </sect1>

doc/src/sgml/chkpass.sgml

@@ -1,50 +1,60 @@
+<!-- $PostgreSQL: pgsql/doc/src/sgml/chkpass.sgml,v 1.2 2007/12/06 04:12:09 tgl Exp $ -->
+
 <sect1 id="chkpass">
- <title>chkpass</title> 
- 
- <!--
+ <title>chkpass</title>
+
  <indexterm zone="chkpass">
   <primary>chkpass</primary>
  </indexterm>
- -->
+
  <para>
-  chkpass is a password type that is automatically checked and converted upon
-  entry.  It is stored encrypted.  To compare, simply compare against a clear
+  This module implements a data type <type>chkpass</> that is
+  designed for storing encrypted passwords.
+  Each password is automatically converted to encrypted form upon entry,
+  and is always stored encrypted.  To compare, simply compare against a clear
   text password and the comparison function will encrypt it before comparing.
-  It also returns an error if the code determines that the password is easily
-  crackable.  This is currently a stub that does nothing.
  </para>
 
  <para>
-  Note that the chkpass data type is not indexable.
-  <!--
-  I haven't worried about making this type indexable.  I doubt that anyone
-  would ever need to sort a file in order of encrypted password.
-  -->
+  There are provisions in the code to report an error if the password is
+  determined to be easily crackable.  However, this is currently just
+  a stub that does nothing.
  </para>
 
  <para>
-  If you precede the string with a colon, the encryption and checking are
-  skipped so that you can enter existing passwords into the field.
+  If you precede an input string with a colon, it is assumed to be an
+  already-encrypted password, and is stored without further encryption.
+  This allows entry of previously-encrypted passwords.
  </para>
 
  <para>
   On output, a colon is prepended.  This makes it possible to dump and reload
-  passwords without re-encrypting them.  If you want the password (encrypted)
-  without the colon then use the raw() function.  This allows you to use the
+  passwords without re-encrypting them.  If you want the encrypted password
+  without the colon then use the <function>raw()</> function.
+  This allows you to use the
   type with things like Apache's Auth_PostgreSQL module.
  </para>
 
  <para>
-  The encryption uses the standard Unix function crypt(), and so it suffers
+  The encryption uses the standard Unix function <function>crypt()</>,
+  and so it suffers
   from all the usual limitations of that function; notably that only the
   first eight characters of a password are considered.
  </para>
 
  <para>
-  Here is some sample usage:
+  Note that the chkpass data type is not indexable.
+  <!--
+  I haven't worried about making this type indexable.  I doubt that anyone
+  would ever need to sort a file in order of encrypted password.
+  -->
  </para>
 
- <programlisting>
+ <para>
+  Sample usage:
+ </para>
+
+<programlisting>
 test=# create table test (p chkpass);
 CREATE TABLE
 test=# insert into test values ('hello');
@@ -72,13 +82,14 @@ test=# select p = 'goodbye' from test;
 ----------
  f
 (1 row)
- </programlisting>
+</programlisting>
 
  <sect2>
   <title>Author</title>
+
   <para>
-   D'Arcy J.M. Cain <email>darcy@druid.net</email>
+   D'Arcy J.M. Cain (<email>darcy@druid.net</email>)
   </para>
  </sect2>
-</sect1>
 
+</sect1>