pg.ddx.io  pgsql-www@postgresql.org mailing list archive  

help / color / mirror / Atom feed

From: Karl O. Pinc <kop@karlpinc.com>
To: Alvaro Herrera <alvherre@alvh.no-ip.org>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
Date: Thu, 19 Jan 2023 11:03:53 -0600
Message-ID: <20230119110353.78ba5217@slate.karlpinc.com> (raw)
In-Reply-To: <20230119123517.ionjlknrrd6n6lrg@alvherre.pgsql>
References: <20230118130605.44172b66@slate.karlpinc.com>
	<20230119123517.ionjlknrrd6n6lrg@alvherre.pgsql>

On Thu, 19 Jan 2023 13:35:17 +0100
Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

> On 2023-Jan-18, Karl O. Pinc wrote:
> 
> > Oops.  Already sent a revised patch that includes starting each
> > module on a new page, for PDF output.  I'll wait to rip that
> > out after review and start a new thread if necessary.

(I have not removed the PDF page breaks from the latest patch.)

> Here's my review in the form of a delta patch.

Love it.

> I didn't find that a thing called "ISN" actually exists.  Is there a
> reference to that?

Maybe.  I came across it somewhere and it seemed useful.  It's
an initialism for International Standard Number.
https://en.wikipedia.org/wiki/International_Standard_Number
It's the same ISN as in the file name, "isn.sgml".

I've frobbed the ISN related text in my response patch.
(And added a line break to btree-gin.)

Attached are 2 patches, a regular and a delta from your v4 review:

contrib_v5-delta.patch.txt
contrib_v5.patch.txt

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Attachments:

contrib_v5-delta.patch.txt (text/plain, 1007B) download
diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml
index c9efe1cccf..f0cda0e32a 100644
--- a/doc/src/sgml/btree-gin.sgml
+++ b/doc/src/sgml/btree-gin.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/btree-gin.sgml -->
 
 <sect1 id="btree-gin" xreflabel="btree_gin">
- <title>btree_gin &mdash; GIN B-tree equivalent operator classes [trusted]</title>
+ <title>btree_gin &mdash;
+   GIN B-tree equivalent operator classes [trusted]</title>
 
  <indexterm zone="btree-gin">
   <primary>btree_gin</primary>
diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml
index 27abdc8c66..8008c84fe4 100644
--- a/doc/src/sgml/isn.sgml
+++ b/doc/src/sgml/isn.sgml
@@ -1,8 +1,8 @@
 <!-- doc/src/sgml/isn.sgml -->
 
 <sect1 id="isn" xreflabel="isn">
- <title>isn &mdash;
-   data types for item numbers (ISBN, EAN, UPC, etc.) [trusted]</title>
+ <title>isn &mdash; data types for international standard numbers
+   (ISBN, EAN, UPC, etc.) [trusted]</title>
 
  <indexterm zone="isn">
   <primary>isn</primary>

contrib_v5.patch.txt (text/plain, 30.1K) download
diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml
index 184e96d7a0..04f3b52379 100644
--- a/doc/src/sgml/adminpack.sgml
+++ b/doc/src/sgml/adminpack.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/adminpack.sgml -->
 
 <sect1 id="adminpack" xreflabel="adminpack">
- <title>adminpack</title>
+ <title>adminpack &mdash; pgAdmin support toolpack</title>
 
  <indexterm zone="adminpack">
   <primary>adminpack</primary>
diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml
index 923cbde9dd..4006c75cdf 100644
--- a/doc/src/sgml/amcheck.sgml
+++ b/doc/src/sgml/amcheck.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/amcheck.sgml -->
 
 <sect1 id="amcheck" xreflabel="amcheck">
- <title>amcheck</title>
+ <title>amcheck &mdash; tools to verify index consistency</title>
 
  <indexterm zone="amcheck">
   <primary>amcheck</primary>
diff --git a/doc/src/sgml/auth-delay.sgml b/doc/src/sgml/auth-delay.sgml
index 40629311b1..0571f2a99d 100644
--- a/doc/src/sgml/auth-delay.sgml
+++ b/doc/src/sgml/auth-delay.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/auth-delay.sgml -->
 
 <sect1 id="auth-delay" xreflabel="auth_delay">
- <title>auth_delay</title>
+ <title>auth_delay &mdash; pause on authentication failure</title>
 
  <indexterm zone="auth-delay">
   <primary>auth_delay</primary>
diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml
index bb7342b120..0c4656ee30 100644
--- a/doc/src/sgml/auto-explain.sgml
+++ b/doc/src/sgml/auto-explain.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/auto-explain.sgml -->
 
 <sect1 id="auto-explain" xreflabel="auto_explain">
- <title>auto_explain</title>
+ <title>auto_explain &mdash; log execution plans of slow queries</title>
 
  <indexterm zone="auto-explain">
   <primary>auto_explain</primary>
diff --git a/doc/src/sgml/basebackup-to-shell.sgml b/doc/src/sgml/basebackup-to-shell.sgml
index 491368eb8f..b6a3b39541 100644
--- a/doc/src/sgml/basebackup-to-shell.sgml
+++ b/doc/src/sgml/basebackup-to-shell.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/basebackup-to-shell.sgml -->
 
 <sect1 id="basebackup-to-shell" xreflabel="basebackup_to_shell">
- <title>basebackup_to_shell</title>
+ <title>basebackup_to_shell &mdash; example "shell" pg_basebackup module</title>
 
  <indexterm zone="basebackup-to-shell">
   <primary>basebackup_to_shell</primary>
diff --git a/doc/src/sgml/basic-archive.sgml b/doc/src/sgml/basic-archive.sgml
index 60f23d2855..b4d43ced20 100644
--- a/doc/src/sgml/basic-archive.sgml
+++ b/doc/src/sgml/basic-archive.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/basic-archive.sgml -->
 
 <sect1 id="basic-archive" xreflabel="basic_archive">
- <title>basic_archive</title>
+ <title>basic_archive &mdash; an example WAL archive module</title>
 
  <indexterm zone="basic-archive">
   <primary>basic_archive</primary>
diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml
index 98d0316175..19f2b172cc 100644
--- a/doc/src/sgml/bloom.sgml
+++ b/doc/src/sgml/bloom.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/bloom.sgml -->
 
 <sect1 id="bloom" xreflabel="bloom">
- <title>bloom</title>
+ <title>bloom &mdash; bloom filter index access method</title>
 
  <indexterm zone="bloom">
   <primary>bloom</primary>
diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml
index 870c25559e..f0cda0e32a 100644
--- a/doc/src/sgml/btree-gin.sgml
+++ b/doc/src/sgml/btree-gin.sgml
@@ -1,14 +1,15 @@
 <!-- doc/src/sgml/btree-gin.sgml -->
 
 <sect1 id="btree-gin" xreflabel="btree_gin">
- <title>btree_gin</title>
+ <title>btree_gin &mdash;
+   GIN B-tree equivalent operator classes [trusted]</title>
 
  <indexterm zone="btree-gin">
   <primary>btree_gin</primary>
  </indexterm>
 
  <para>
-  <filename>btree_gin</filename> provides sample GIN operator classes that
+  <filename>btree_gin</filename> provides GIN operator classes that
   implement B-tree equivalent behavior for the data types
   <type>int2</type>, <type>int4</type>, <type>int8</type>, <type>float4</type>,
   <type>float8</type>, <type>timestamp with time zone</type>,
diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml
index 92aa8e277e..c08d1fdfc3 100644
--- a/doc/src/sgml/btree-gist.sgml
+++ b/doc/src/sgml/btree-gist.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/btree-gist.sgml -->
 
 <sect1 id="btree-gist" xreflabel="btree_gist">
- <title>btree_gist</title>
+ <title>btree_gist &mdash;
+   B-tree equivalent GiST index operators [trusted]</title>
 
  <indexterm zone="btree-gist">
   <primary>btree_gist</primary>
diff --git a/doc/src/sgml/citext.sgml b/doc/src/sgml/citext.sgml
index 3df2825592..710fbdddf2 100644
--- a/doc/src/sgml/citext.sgml
+++ b/doc/src/sgml/citext.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/citext.sgml -->
 
 <sect1 id="citext" xreflabel="citext">
- <title>citext</title>
+ <title>citext &mdash;
+   a case-insensitive character string type [trusted]</title>
 
  <indexterm zone="citext">
   <primary>citext</primary>
diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml
index 77328ae6e8..e7cae4e38d 100644
--- a/doc/src/sgml/contrib-spi.sgml
+++ b/doc/src/sgml/contrib-spi.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/contrib-spi.sgml -->
 
 <sect1 id="contrib-spi" xreflabel="spi">
- <title>spi</title>
+ <title>spi &mdash; Server Programming Interface features/examples</title>
 
  <indexterm zone="contrib-spi">
   <primary>SPI</primary>
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 4e7b87a42f..e412680e46 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -1,27 +1,31 @@
 <!-- doc/src/sgml/contrib.sgml -->
 
 <appendix id="contrib">
- <title>Additional Supplied Modules</title>
+ <title>Additional Supplied Extensions and Modules</title>
 
  <para>
-  This appendix and the next one contain information regarding the modules that
-  can be found in the <literal>contrib</literal> directory of the
+  This appendix and the next one contain information on the
+  optional components
+  found in the <literal>contrib</literal> directory of the
   <productname>PostgreSQL</productname> distribution.
   These include porting tools, analysis utilities,
-  and plug-in features that are not part of the core PostgreSQL system,
-  mainly because they address a limited audience or are too experimental
+  and plug-in features that are not part of the core PostgreSQL system.
+  They are separate mainly
+  because they address a limited audience or are too experimental
   to be part of the main source tree.  This does not preclude their
   usefulness.
  </para>
 
  <para>
-  This appendix covers extensions and other server plug-in modules found in
+  This appendix covers extensions and other server plug-in module
+  libraries found in
   <literal>contrib</literal>.  <xref linkend="contrib-prog"/> covers utility
   programs.
  </para>
 
  <para>
-  When building from the source distribution, these components are not built
+  When building from the source distribution, these optional
+  components are not built
   automatically, unless you build the "world" target
   (see <xref linkend="build"/>).
   You can build and install all of them by running:
@@ -31,8 +35,8 @@
 </screen>
   in the <literal>contrib</literal> directory of a configured source tree;
   or to build and install
-  just one selected module, do the same in that module's subdirectory.
-  Many of the modules have regression tests, which can be executed by
+  just one selection, do the same in that selection's subdirectory.
+  Many have regression tests, which can be executed by
   running:
 <screen>
 <userinput>make check</userinput>
@@ -46,41 +50,42 @@
 
  <para>
   If you are using a pre-packaged version of <productname>PostgreSQL</productname>,
-  these modules are typically made available as a separate subpackage,
+  these components are typically made available as a separate subpackage,
   such as <literal>postgresql-contrib</literal>.
  </para>
 
  <para>
-  Many modules supply new user-defined functions, operators, or types.
-  To make use of one of these modules, after you have installed the code
+  Many components supply new user-defined functions, operators, or types,
+  packaged as <firstterm>extensions</firstterm>.
+  To make use of one of these extensions, after you have installed the code
   you need to register the new SQL objects in the database system.
   This is done by executing
   a <xref linkend="sql-createextension"/> command.  In a fresh database,
   you can simply do
 
 <programlisting>
-CREATE EXTENSION <replaceable>module_name</replaceable>;
+CREATE EXTENSION <replaceable>extension_name</replaceable>;
 </programlisting>
 
-  This command registers the new SQL objects in the current database only,
-  so you need to run it in each database that you want
-  the module's facilities to be available in.  Alternatively, run it in
+  This command only registers the new SQL objects in the current database,
+  so you need to run it in every database in which you want
+  the extension's facilities to be available.  Alternatively, run it in
   database <literal>template1</literal> so that the extension will be copied into
   subsequently-created databases by default.
  </para>
 
  <para>
-  For all these modules, <command>CREATE EXTENSION</command> must be run
-  by a database superuser, unless the module is
-  considered <quote>trusted</quote>, in which case it can be run by any
+  For all extensions the <command>CREATE EXTENSION</command> must be run
+  by a database superuser, unless the extension is
+  considered <quote>trusted</quote>.  Trusted extensions can be run by any
   user who has <literal>CREATE</literal> privilege on the current
-  database.  Modules that are trusted are identified as such in the
-  sections that follow.  Generally, trusted modules are ones that cannot
+  database.  Extensions that are trusted are identified as such in the
+  sections that follow.  Generally, trusted extensions are ones that cannot
   provide access to outside-the-database functionality.
  </para>
 
  <para>
-  Many modules allow you to install their objects in a schema of your
+  Many extensions allow you to install their objects in a schema of your
   choice.  To do that, add <literal>SCHEMA
   <replaceable>schema_name</replaceable></literal> to the <command>CREATE EXTENSION</command>
   command.  By default, the objects will be placed in your current creation
@@ -88,62 +93,112 @@ CREATE EXTENSION <replaceable>module_name</replaceable>;
  </para>
 
  <para>
-  Note, however, that some of these modules are not <quote>extensions</quote>
+  Note, however, that some of these components are not <quote>extensions</quote>
   in this sense, but are loaded into the server in some other way, for instance
   by way of
   <xref linkend="guc-shared-preload-libraries"/>.  See the documentation of each
-  module for details.
+  component for details.
  </para>
 
+ <?hard-pagebreak?>
  &adminpack;
+ <?hard-pagebreak?>
  &amcheck;
+ <?hard-pagebreak?>
  &auth-delay;
+ <?hard-pagebreak?>
  &auto-explain;
+ <?hard-pagebreak?>
  &basebackup-to-shell;
+ <?hard-pagebreak?>
  &basic-archive;
+ <?hard-pagebreak?>
  &bloom;
+ <?hard-pagebreak?>
  &btree-gin;
+ <?hard-pagebreak?>
  &btree-gist;
+ <?hard-pagebreak?>
  &citext;
+ <?hard-pagebreak?>
  &cube;
+ <?hard-pagebreak?>
  &dblink;
+ <?hard-pagebreak?>
  &dict-int;
+ <?hard-pagebreak?>
  &dict-xsyn;
+ <?hard-pagebreak?>
  &earthdistance;
+ <?hard-pagebreak?>
  &file-fdw;
+ <?hard-pagebreak?>
  &fuzzystrmatch;
+ <?hard-pagebreak?>
  &hstore;
+ <?hard-pagebreak?>
  &intagg;
+ <?hard-pagebreak?>
  &intarray;
+ <?hard-pagebreak?>
  &isn;
+ <?hard-pagebreak?>
  &lo;
+ <?hard-pagebreak?>
  &ltree;
+ <?hard-pagebreak?>
  &oldsnapshot;
+ <?hard-pagebreak?>
  &pageinspect;
+ <?hard-pagebreak?>
  &passwordcheck;
+ <?hard-pagebreak?>
  &pgbuffercache;
+ <?hard-pagebreak?>
  &pgcrypto;
+ <?hard-pagebreak?>
  &pgfreespacemap;
+ <?hard-pagebreak?>
  &pgprewarm;
+ <?hard-pagebreak?>
  &pgrowlocks;
+ <?hard-pagebreak?>
  &pgstatstatements;
+ <?hard-pagebreak?>
  &pgstattuple;
+ <?hard-pagebreak?>
  &pgsurgery;
+ <?hard-pagebreak?>
  &pgtrgm;
+ <?hard-pagebreak?>
  &pgvisibility;
+ <?hard-pagebreak?>
  &pgwalinspect;
+ <?hard-pagebreak?>
  &postgres-fdw;
+ <?hard-pagebreak?>
  &seg;
+ <?hard-pagebreak?>
  &sepgsql;
+ <?hard-pagebreak?>
  &contrib-spi;
+ <?hard-pagebreak?>
  &sslinfo;
+ <?hard-pagebreak?>
  &tablefunc;
+ <?hard-pagebreak?>
  &tcn;
+ <?hard-pagebreak?>
  &test-decoding;
+ <?hard-pagebreak?>
  &tsm-system-rows;
+ <?hard-pagebreak?>
  &tsm-system-time;
+ <?hard-pagebreak?>
  &unaccent;
+ <?hard-pagebreak?>
  &uuid-ossp;
+ <?hard-pagebreak?>
  &xml2;
 
 </appendix>
diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml
index 0744816e7c..1998e6d81a 100644
--- a/doc/src/sgml/cube.sgml
+++ b/doc/src/sgml/cube.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/cube.sgml -->
 
 <sect1 id="cube" xreflabel="cube">
- <title>cube</title>
+ <title>cube &mdash; a multi-dimensional cube data type [trusted]</title>
 
  <indexterm zone="cube">
   <primary>cube (extension)</primary>
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 50c49f533b..17f9d99b1c 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/dblink.sgml -->
 
 <sect1 id="dblink" xreflabel="dblink">
- <title>dblink</title>
+ <title>dblink &mdash; connect to other PostgreSQL databases</title>
 
  <indexterm zone="dblink">
   <primary>dblink</primary>
diff --git a/doc/src/sgml/dict-int.sgml b/doc/src/sgml/dict-int.sgml
index 53ae8b6637..293ba83ce6 100644
--- a/doc/src/sgml/dict-int.sgml
+++ b/doc/src/sgml/dict-int.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/dict-int.sgml -->
 
 <sect1 id="dict-int" xreflabel="dict_int">
- <title>dict_int</title>
+ <title>dict_int &mdash;
+   example full-text search dictionary for integers [trusted]</title>
 
  <indexterm zone="dict-int">
   <primary>dict_int</primary>
diff --git a/doc/src/sgml/dict-xsyn.sgml b/doc/src/sgml/dict-xsyn.sgml
index 27b24628d4..a94c6430ed 100644
--- a/doc/src/sgml/dict-xsyn.sgml
+++ b/doc/src/sgml/dict-xsyn.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/dict-xsyn.sgml -->
 
 <sect1 id="dict-xsyn" xreflabel="dict_xsyn">
- <title>dict_xsyn</title>
+ <title>dict_xsyn &mdash; example synonym full-text search dictionary</title>
 
  <indexterm zone="dict-xsyn">
   <primary>dict_xsyn</primary>
diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml
index f15dde3a66..5a709e3d47 100644
--- a/doc/src/sgml/earthdistance.sgml
+++ b/doc/src/sgml/earthdistance.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/earthdistance.sgml -->
 
 <sect1 id="earthdistance" xreflabel="earthdistance">
- <title>earthdistance</title>
+ <title>earthdistance &mdash; calculate great-circle distances</title>
 
  <indexterm zone="earthdistance">
   <primary>earthdistance</primary>
diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml
index 5b98782064..56d696c323 100644
--- a/doc/src/sgml/file-fdw.sgml
+++ b/doc/src/sgml/file-fdw.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/file-fdw.sgml -->
 
 <sect1 id="file-fdw" xreflabel="file_fdw">
- <title>file_fdw</title>
+ <title>file_fdw &mdash; access data files in the server's file system</title>
 
  <indexterm zone="file-fdw">
   <primary>file_fdw</primary>
diff --git a/doc/src/sgml/fuzzystrmatch.sgml b/doc/src/sgml/fuzzystrmatch.sgml
index 5dedbd8f7a..2c6a666da8 100644
--- a/doc/src/sgml/fuzzystrmatch.sgml
+++ b/doc/src/sgml/fuzzystrmatch.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/fuzzystrmatch.sgml -->
 
 <sect1 id="fuzzystrmatch" xreflabel="fuzzystrmatch">
- <title>fuzzystrmatch</title>
+ <title>fuzzystrmatch &mdash;
+   determine string similarities and distance [trusted]</title>
 
  <indexterm zone="fuzzystrmatch">
   <primary>fuzzystrmatch</primary>
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 815ef641a0..b75c63f348 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/hstore.sgml -->
 
 <sect1 id="hstore" xreflabel="hstore">
- <title>hstore</title>
+ <title>hstore &mdash; hstore key/value datatype [trusted]</title>
 
  <indexterm zone="hstore">
   <primary>hstore</primary>
diff --git a/doc/src/sgml/intagg.sgml b/doc/src/sgml/intagg.sgml
index 34562a66c8..ce7b929a34 100644
--- a/doc/src/sgml/intagg.sgml
+++ b/doc/src/sgml/intagg.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/intagg.sgml -->
 
 <sect1 id="intagg" xreflabel="intagg">
- <title>intagg</title>
+ <title>intagg &mdash; integer aggregator and enumerator [obsolete]</title>
 
  <indexterm zone="intagg">
   <primary>intagg</primary>
diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml
index c861f50497..9194e94c28 100644
--- a/doc/src/sgml/intarray.sgml
+++ b/doc/src/sgml/intarray.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/intarray.sgml -->
 
 <sect1 id="intarray" xreflabel="intarray">
- <title>intarray</title>
+ <title>intarray &mdash; manipulate arrays of integers [trusted]</title>
 
  <indexterm zone="intarray">
   <primary>intarray</primary>
diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml
index 14bf2d14aa..8008c84fe4 100644
--- a/doc/src/sgml/isn.sgml
+++ b/doc/src/sgml/isn.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/isn.sgml -->
 
 <sect1 id="isn" xreflabel="isn">
- <title>isn</title>
+ <title>isn &mdash; data types for international standard numbers
+   (ISBN, EAN, UPC, etc.) [trusted]</title>
 
  <indexterm zone="isn">
   <primary>isn</primary>
diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml
index d6076aeb7f..511e576cac 100644
--- a/doc/src/sgml/lo.sgml
+++ b/doc/src/sgml/lo.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/lo.sgml -->
 
 <sect1 id="lo" xreflabel="lo">
- <title>lo</title>
+ <title>lo &mdash; manage large objects [trusted]</title>
 
  <indexterm zone="lo">
   <primary>lo</primary>
diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml
index 45a86188cb..92264251cd 100644
--- a/doc/src/sgml/ltree.sgml
+++ b/doc/src/sgml/ltree.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/ltree.sgml -->
 
 <sect1 id="ltree" xreflabel="ltree">
- <title>ltree</title>
+ <title>ltree &mdash; label tree (ltree) data type [trusted]</title>
 
  <indexterm zone="ltree">
   <primary>ltree</primary>
diff --git a/doc/src/sgml/oldsnapshot.sgml b/doc/src/sgml/oldsnapshot.sgml
index 0e03084562..a6e40043d1 100644
--- a/doc/src/sgml/oldsnapshot.sgml
+++ b/doc/src/sgml/oldsnapshot.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/oldsnapshot.sgml -->
 
 <sect1 id="oldsnapshot" xreflabel="old_snapshot">
- <title>old_snapshot</title>
+ <title>old_snapshot &mdash; inspect guc-old-snapshot-threshold state</title>
 
  <indexterm zone="oldsnapshot">
   <primary>old_snapshot</primary>
diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml
index 8674872e8b..01f1e96204 100644
--- a/doc/src/sgml/pageinspect.sgml
+++ b/doc/src/sgml/pageinspect.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pageinspect.sgml -->
 
 <sect1 id="pageinspect" xreflabel="pageinspect">
- <title>pageinspect</title>
+ <title>pageinspect &mdash; low-level inspection of database pages</title>
 
  <indexterm zone="pageinspect">
   <primary>pageinspect</primary>
diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml
index 0d89bb95b9..601f489227 100644
--- a/doc/src/sgml/passwordcheck.sgml
+++ b/doc/src/sgml/passwordcheck.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/passwordcheck.sgml -->
 
 <sect1 id="passwordcheck" xreflabel="passwordcheck">
- <title>passwordcheck</title>
+ <title>passwordcheck &mdash; verify password strength</title>
 
  <indexterm zone="passwordcheck">
   <primary>passwordcheck</primary>
diff --git a/doc/src/sgml/pgbuffercache.sgml b/doc/src/sgml/pgbuffercache.sgml
index 7b118f2030..f5d1901af2 100644
--- a/doc/src/sgml/pgbuffercache.sgml
+++ b/doc/src/sgml/pgbuffercache.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgbuffercache.sgml -->
 
 <sect1 id="pgbuffercache" xreflabel="pg_buffercache">
- <title>pg_buffercache</title>
+ <title>pg_buffercache &mdash; inspect Postgres buffer cache state</title>
 
  <indexterm zone="pgbuffercache">
   <primary>pg_buffercache</primary>
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index bde3071923..2231a65dde 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgcrypto.sgml -->
 
 <sect1 id="pgcrypto" xreflabel="pgcrypto">
- <title>pgcrypto</title>
+ <title>pgcrypto &mdash; cryptographic functions [trusted]</title>
 
  <indexterm zone="pgcrypto">
   <primary>pgcrypto</primary>
diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
index 9d93fb5a72..829ad60f32 100644
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgfreespacemap.sgml -->
 
 <sect1 id="pgfreespacemap" xreflabel="pg_freespacemap">
- <title>pg_freespacemap</title>
+ <title>pg_freespacemap &mdash; examine the free space map</title>
 
  <indexterm zone="pgfreespacemap">
   <primary>pg_freespacemap</primary>
diff --git a/doc/src/sgml/pgprewarm.sgml b/doc/src/sgml/pgprewarm.sgml
index e103a2746d..6e1de21303 100644
--- a/doc/src/sgml/pgprewarm.sgml
+++ b/doc/src/sgml/pgprewarm.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/pgprewarm.sgml -->
 
 <sect1 id="pgprewarm" xreflabel="pg_prewarm">
- <title>pg_prewarm</title>
+ <title>pg_prewarm &mdash;
+   preload relation data into O/S or PG buffer caches</title>
 
  <indexterm zone="pgprewarm">
   <primary>pg_prewarm</primary>
diff --git a/doc/src/sgml/pgrowlocks.sgml b/doc/src/sgml/pgrowlocks.sgml
index 91dfd452ee..b5e655735a 100644
--- a/doc/src/sgml/pgrowlocks.sgml
+++ b/doc/src/sgml/pgrowlocks.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgrowlocks.sgml -->
 
 <sect1 id="pgrowlocks" xreflabel="pgrowlocks">
- <title>pgrowlocks</title>
+ <title>pgrowlocks &mdash; show a table's row locking information</title>
 
  <indexterm zone="pgrowlocks">
   <primary>pgrowlocks</primary>
diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml
index ded33acd18..abdee744ac 100644
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/pgstatstatements.sgml -->
 
 <sect1 id="pgstatstatements" xreflabel="pg_stat_statements">
- <title>pg_stat_statements</title>
+ <title>pg_stat_statements &mdash;
+   track statistics of SQL planning and execution</title>
 
  <indexterm zone="pgstatstatements">
   <primary>pg_stat_statements</primary>
diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml
index 581bea2788..4071da4ed9 100644
--- a/doc/src/sgml/pgstattuple.sgml
+++ b/doc/src/sgml/pgstattuple.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgstattuple.sgml -->
 
 <sect1 id="pgstattuple" xreflabel="pgstattuple">
- <title>pgstattuple</title>
+ <title>pgstattuple &mdash; obtain tuple-level statistics</title>
 
  <indexterm zone="pgstattuple">
   <primary>pgstattuple</primary>
diff --git a/doc/src/sgml/pgsurgery.sgml b/doc/src/sgml/pgsurgery.sgml
index 6c6be70c24..caadc10309 100644
--- a/doc/src/sgml/pgsurgery.sgml
+++ b/doc/src/sgml/pgsurgery.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgsurgery.sgml -->
 
 <sect1 id="pgsurgery" xreflabel="pg_surgery">
- <title>pg_surgery</title>
+ <title>pg_surgery &mdash; perform surgery on damaged relations</title>
 
  <indexterm zone="pgsurgery">
   <primary>pg_surgery</primary>
diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml
index f0344590dd..1497172762 100644
--- a/doc/src/sgml/pgtrgm.sgml
+++ b/doc/src/sgml/pgtrgm.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/pgtrgm.sgml -->
 
 <sect1 id="pgtrgm" xreflabel="pg_trgm">
- <title>pg_trgm</title>
+ <title>pg_trgm &mdash;
+   support for similarity of text using trigram matching [trusted]</title>
 
  <indexterm zone="pgtrgm">
   <primary>pg_trgm</primary>
diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml
index 68c43b7f39..097f7e0566 100644
--- a/doc/src/sgml/pgvisibility.sgml
+++ b/doc/src/sgml/pgvisibility.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgvisibility.sgml -->
 
 <sect1 id="pgvisibility" xreflabel="pg_visibility">
- <title>pg_visibility</title>
+ <title>pg_visibility &mdash; visibility map information and utilities</title>
 
  <indexterm zone="pgvisibility">
   <primary>pg_visibility</primary>
diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml
index 08eedab071..119e162e60 100644
--- a/doc/src/sgml/pgwalinspect.sgml
+++ b/doc/src/sgml/pgwalinspect.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/pgwalinspect.sgml -->
 
 <sect1 id="pgwalinspect" xreflabel="pg_walinspect">
- <title>pg_walinspect</title>
+ <title>pg_walinspect &mdash; low-level WAL inspection</title>
 
  <indexterm zone="pgwalinspect">
   <primary>pg_walinspect</primary>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 78f2d7d8d5..644f51835b 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/postgres-fdw.sgml -->
 
 <sect1 id="postgres-fdw" xreflabel="postgres_fdw">
- <title>postgres_fdw</title>
+ <title>postgres_fdw &mdash;
+   access data stored in external Postgres servers</title>
 
  <indexterm zone="postgres-fdw">
   <primary>postgres_fdw</primary>
diff --git a/doc/src/sgml/seg.sgml b/doc/src/sgml/seg.sgml
index 72387c7d45..e1d20b4a0e 100644
--- a/doc/src/sgml/seg.sgml
+++ b/doc/src/sgml/seg.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/seg.sgml -->
 
 <sect1 id="seg" xreflabel="seg">
- <title>seg</title>
+ <title>seg &mdash;
+   line segment/floating point interval data type [trusted]</title>
 
  <indexterm zone="seg">
   <primary>seg</primary>
diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml
index fd4bb83cbf..786fdbbc26 100644
--- a/doc/src/sgml/sepgsql.sgml
+++ b/doc/src/sgml/sepgsql.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/sepgsql.sgml -->
 
 <sect1 id="sepgsql" xreflabel="sepgsql">
- <title>sepgsql</title>
+ <title>sepgsql &mdash;
+   SELinux-based row-level security mandatory access control</title>
 
  <indexterm zone="sepgsql">
   <primary>sepgsql</primary>
diff --git a/doc/src/sgml/sslinfo.sgml b/doc/src/sgml/sslinfo.sgml
index 786f113072..85d49f6653 100644
--- a/doc/src/sgml/sslinfo.sgml
+++ b/doc/src/sgml/sslinfo.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/sslinfo.sgml -->
 
 <sect1 id="sslinfo" xreflabel="sslinfo">
- <title>sslinfo</title>
+ <title>sslinfo &mdash; obtain client SSL information</title>
 
  <indexterm zone="sslinfo">
   <primary>sslinfo</primary>
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 0c4dff92c4..9dde0a89dd 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -132,4 +132,10 @@
   </fo:bookmark>
 </xsl:template>
 
+<!-- Provide a hard page break processing instruction
+     http://www.sagehill.net/docbookxsl/PageBreaking.html#HardPageBreaks -->
+<xsl:template match="processing-instruction('hard-pagebreak')">
+   <fo:block break-after='page'/>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml
index c1b70953f0..77e0178902 100644
--- a/doc/src/sgml/tablefunc.sgml
+++ b/doc/src/sgml/tablefunc.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/tablefunc.sgml -->
 
 <sect1 id="tablefunc" xreflabel="tablefunc">
- <title>tablefunc</title>
+ <title>tablefunc &mdash;
+   useful/example functions which return tables [trusted]</title>
 
  <indexterm zone="tablefunc">
   <primary>tablefunc</primary>
diff --git a/doc/src/sgml/tcn.sgml b/doc/src/sgml/tcn.sgml
index 82afe9ada4..60f8ebb80f 100644
--- a/doc/src/sgml/tcn.sgml
+++ b/doc/src/sgml/tcn.sgml
@@ -1,7 +1,9 @@
 <!-- doc/src/sgml/tcn.sgml -->
 
 <sect1 id="tcn" xreflabel="tcn">
- <title>tcn</title>
+  <title>tcn &mdash;
+    a trigger function to notify listeners of changes to table content
+    [trusted]</title>
 
  <indexterm zone="tcn">
   <primary>tcn</primary>
diff --git a/doc/src/sgml/test-decoding.sgml b/doc/src/sgml/test-decoding.sgml
index 9b07195427..88f72c204e 100644
--- a/doc/src/sgml/test-decoding.sgml
+++ b/doc/src/sgml/test-decoding.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/test-decoding.sgml -->
 
 <sect1 id="test-decoding" xreflabel="test_decoding">
- <title>test_decoding</title>
+ <title>test_decoding &mdash; example of WAL logical decoding in SQL</title>
 
  <indexterm zone="test-decoding">
   <primary>test_decoding</primary>
diff --git a/doc/src/sgml/tsm-system-rows.sgml b/doc/src/sgml/tsm-system-rows.sgml
index f5357791c0..2c8ef6a7d4 100644
--- a/doc/src/sgml/tsm-system-rows.sgml
+++ b/doc/src/sgml/tsm-system-rows.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/tsm-system-rows.sgml -->
 
 <sect1 id="tsm-system-rows" xreflabel="tsm_system_rows">
- <title>tsm_system_rows</title>
+ <title>tsm_system_rows &mdash;
+   a table row sampling method for TABLESAMPLE clauses [trusted]</title>
 
  <indexterm zone="tsm-system-rows">
   <primary>tsm_system_rows</primary>
diff --git a/doc/src/sgml/tsm-system-time.sgml b/doc/src/sgml/tsm-system-time.sgml
index 0de15ae7e8..e532174eab 100644
--- a/doc/src/sgml/tsm-system-time.sgml
+++ b/doc/src/sgml/tsm-system-time.sgml
@@ -1,7 +1,9 @@
 <!-- doc/src/sgml/tsm-system-time.sgml -->
 
 <sect1 id="tsm-system-time" xreflabel="tsm_system_time">
- <title>tsm_system_time</title>
+ <title>tsm_system_time &mdash;
+   a SYSTEM_TIME table sampling method for the TABLESAMPLE clauses
+   [trusted]</title>
 
  <indexterm zone="tsm-system-time">
   <primary>tsm_system_time</primary>
diff --git a/doc/src/sgml/unaccent.sgml b/doc/src/sgml/unaccent.sgml
index 139a87d4ff..38df3be27d 100644
--- a/doc/src/sgml/unaccent.sgml
+++ b/doc/src/sgml/unaccent.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/unaccent.sgml -->
 
 <sect1 id="unaccent" xreflabel="unaccent">
- <title>unaccent</title>
+ <title>unaccent &mdash;
+   a full-text search dictionary which removes diacritics [trusted]</title>
 
  <indexterm zone="unaccent">
   <primary>unaccent</primary>
diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml
index 0a42d516e8..7cc68cdd92 100644
--- a/doc/src/sgml/uuid-ossp.sgml
+++ b/doc/src/sgml/uuid-ossp.sgml
@@ -1,7 +1,8 @@
 <!-- doc/src/sgml/uuid-ossp.sgml -->
 
 <sect1 id="uuid-ossp" xreflabel="uuid-ossp">
- <title>uuid-ossp</title>
+ <title>uuid-ossp &mdash;
+   generate UUIDs when there are special requirements [trusted]</title>
 
  <indexterm zone="uuid-ossp">
   <primary>uuid-ossp</primary>
diff --git a/doc/src/sgml/xml2.sgml b/doc/src/sgml/xml2.sgml
index e9a223ca5b..2bd4a3fd3a 100644
--- a/doc/src/sgml/xml2.sgml
+++ b/doc/src/sgml/xml2.sgml
@@ -1,7 +1,7 @@
 <!-- doc/src/sgml/xml2.sgml -->
 
 <sect1 id="xml2" xreflabel="xml2">
- <title>xml2</title>
+ <title>xml2 &mdash; XPath querying and XSLT functionality [obsolete]</title>
 
  <indexterm zone="xml2">
   <primary>xml2</primary>

view thread (48+ messages)  latest in thread

Message-ID: <20230119110353.78ba5217@slate.karlpinc.com>
Permalink:  ../20230119110353.78ba5217@slate.karlpinc.com/
Also on:    postgresql.org/message-id/20230119110353.78ba5217@slate.karlpinc.com

copy link · copy postgr.es

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: pgsql-www@postgresql.org
  Cc: kop@karlpinc.com, alvherre@alvh.no-ip.org, pgsql-hackers@lists.postgresql.org
  Subject: Re: Doc: Rework contrib appendix -- informative titles, tweaked sentences
  In-Reply-To: <20230119110353.78ba5217@slate.karlpinc.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox