Describe each contrib module in its SGML section title

The original titles only had the module name, which is not very useful
when scanning the list.  By adding a very brief description to each
title, the table of contents becomes friendlier.

Also amend the introduction in the "additional modules" appendix, using
the word "Extension" more extensively.  Nowadays, almost all contrib
modules are extensions, so this is also helpful.

Author: Karl O. Pinc <kop@karlpinc.com>
Reviewed-by: Brar Piening <brar@gmx.de>
Discussion: https://postgr.es/m/20230102180015.372995a9@slate.karlpinc.com
This commit is contained in:
Alvaro Herrera 2023-01-20 20:01:59 +01:00
parent d137cb52cb
commit e86c8b728f
No known key found for this signature in database
GPG Key ID: 1C20ACB9D5C564AE
51 changed files with 83 additions and 72 deletions

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/amcheck.sgml -->
<sect1 id="amcheck" xreflabel="amcheck">
<title>amcheck</title>
<title>amcheck &mdash; tools to verify table and index consistency</title>
<indexterm zone="amcheck">
<primary>amcheck</primary>

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -1,14 +1,14 @@
<!-- doc/src/sgml/btree-gin.sgml -->
<sect1 id="btree-gin" xreflabel="btree_gin">
<title>btree_gin</title>
<title>btree_gin &mdash; GIN operator classes with B-tree behavior</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>,

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/btree-gist.sgml -->
<sect1 id="btree-gist" xreflabel="btree_gist">
<title>btree_gist</title>
<title>btree_gist &mdash; GiST operator classes with B-tree behavior</title>
<indexterm zone="btree-gist">
<primary>btree_gist</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/citext.sgml -->
<sect1 id="citext" xreflabel="citext">
<title>citext</title>
<title>citext &mdash; a case-insensitive character string type</title>
<indexterm zone="citext">
<primary>citext</primary>

View File

@ -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>

View File

@ -1,27 +1,31 @@
<!-- doc/src/sgml/contrib.sgml -->
<appendix id="contrib">
<title>Additional Supplied Modules</title>
<title>Additional Supplied Modules and Extensions</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:
@ -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
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> 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,11 +93,11 @@ 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>
&adminpack;

View File

@ -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</title>
<indexterm zone="cube">
<primary>cube (extension)</primary>

View File

@ -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>

View File

@ -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</title>
<indexterm zone="dict-int">
<primary>dict_int</primary>

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/fuzzystrmatch.sgml -->
<sect1 id="fuzzystrmatch" xreflabel="fuzzystrmatch">
<title>fuzzystrmatch</title>
<title>fuzzystrmatch &mdash; determine string similarities and distance</title>
<indexterm zone="fuzzystrmatch">
<primary>fuzzystrmatch</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/hstore.sgml -->
<sect1 id="hstore" xreflabel="hstore">
<title>hstore</title>
<title>hstore &mdash; hstore key/value datatype</title>
<indexterm zone="hstore">
<primary>hstore</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/intagg.sgml -->
<sect1 id="intagg" xreflabel="intagg">
<title>intagg</title>
<title>intagg &mdash; integer aggregator and enumerator</title>
<indexterm zone="intagg">
<primary>intagg</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/intarray.sgml -->
<sect1 id="intarray" xreflabel="intarray">
<title>intarray</title>
<title>intarray &mdash; manipulate arrays of integers</title>
<indexterm zone="intarray">
<primary>intarray</primary>

View File

@ -1,7 +1,7 @@
<!-- 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.)</title>
<indexterm zone="isn">
<primary>isn</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/lo.sgml -->
<sect1 id="lo" xreflabel="lo">
<title>lo</title>
<title>lo &mdash; manage large objects</title>
<indexterm zone="lo">
<primary>lo</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/ltree.sgml -->
<sect1 id="ltree" xreflabel="ltree">
<title>ltree</title>
<title>ltree &mdash; hierarchical tree-like data type</title>
<indexterm zone="ltree">
<primary>ltree</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/oldsnapshot.sgml -->
<sect1 id="oldsnapshot" xreflabel="old_snapshot">
<title>old_snapshot</title>
<title>old_snapshot &mdash; inspect <literal>old_snapshot_threshold</literal> state</title>
<indexterm zone="oldsnapshot">
<primary>old_snapshot</primary>

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/pgcrypto.sgml -->
<sect1 id="pgcrypto" xreflabel="pgcrypto">
<title>pgcrypto</title>
<title>pgcrypto &mdash; cryptographic functions</title>
<indexterm zone="pgcrypto">
<primary>pgcrypto</primary>

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/pgprewarm.sgml -->
<sect1 id="pgprewarm" xreflabel="pg_prewarm">
<title>pg_prewarm</title>
<title>pg_prewarm &mdash; preload relation data into buffer caches</title>
<indexterm zone="pgprewarm">
<primary>pg_prewarm</primary>

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- 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>

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/pgsurgery.sgml -->
<sect1 id="pgsurgery" xreflabel="pg_surgery">
<title>pg_surgery</title>
<title>pg_surgery &mdash; perform low-level surgery on relation data</title>
<indexterm zone="pgsurgery">
<primary>pg_surgery</primary>

View File

@ -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</title>
<indexterm zone="pgtrgm">
<primary>pg_trgm</primary>

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/seg.sgml -->
<sect1 id="seg" xreflabel="seg">
<title>seg</title>
<title>seg &mdash; a datatype for line segments or floating point intervals</title>
<indexterm zone="seg">
<primary>seg</primary>

View File

@ -1,7 +1,8 @@
<!-- doc/src/sgml/sepgsql.sgml -->
<sect1 id="sepgsql" xreflabel="sepgsql">
<title>sepgsql</title>
<title>sepgsql &mdash;
SELinux-, label-based mandatory access control (MAC) security module</title>
<indexterm zone="sepgsql">
<primary>sepgsql</primary>

View File

@ -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>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/tablefunc.sgml -->
<sect1 id="tablefunc" xreflabel="tablefunc">
<title>tablefunc</title>
<title>tablefunc &mdash; functions that return tables (<function>crosstab</function> and others)</title>
<indexterm zone="tablefunc">
<primary>tablefunc</primary>

View File

@ -1,7 +1,7 @@
<!-- 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</title>
<indexterm zone="tcn">
<primary>tcn</primary>

View File

@ -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; SQL-based test/example module for WAL logical decoding</title>
<indexterm zone="test-decoding">
<primary>test_decoding</primary>

View File

@ -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;
the <literal>SYSTEM_ROWS</literal> sampling method for <literal>TABLESAMPLE</literal></title>
<indexterm zone="tsm-system-rows">
<primary>tsm_system_rows</primary>

View File

@ -1,7 +1,8 @@
<!-- 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;
the <literal>SYSTEM_TIME</literal> sampling method for <literal>TABLESAMPLE</literal></title>
<indexterm zone="tsm-system-time">
<primary>tsm_system_time</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/unaccent.sgml -->
<sect1 id="unaccent" xreflabel="unaccent">
<title>unaccent</title>
<title>unaccent &mdash; a text search dictionary which removes diacritics</title>
<indexterm zone="unaccent">
<primary>unaccent</primary>

View File

@ -1,7 +1,7 @@
<!-- doc/src/sgml/uuid-ossp.sgml -->
<sect1 id="uuid-ossp" xreflabel="uuid-ossp">
<title>uuid-ossp</title>
<title>uuid-ossp &mdash; a UUID generator</title>
<indexterm zone="uuid-ossp">
<primary>uuid-ossp</primary>

View File

@ -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</title>
<indexterm zone="xml2">
<primary>xml2</primary>