rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc: reformat catalog/view description tables. 

This changes our catalog and view descriptions to use a style inspired
by the new format for function/operator tables: each table entry is
formatted roughly like a <varlistentry>, with the column name and type
on the first line and then an indented description.  This provides much
more room for expansive descriptions than we had before, and thereby
eliminates a passel of PDF build warnings.

Discussion: https://postgr.es/m/12984.1588643549@sss.pgh.pa.us
This commit is contained in:
Tom Lane 2020-05-13 23:03:39 -04:00
parent 7fd89f4d7a
commit a042750646
7 changed files with 12748 additions and 8422 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9810
doc/src/sgml/catalogs.sgml
View File

File diff suppressed because it is too large Load Diff

6541
doc/src/sgml/information_schema.sgml
View File

File diff suppressed because it is too large Load Diff

4313
doc/src/sgml/monitoring.sgml
View File

File diff suppressed because it is too large Load Diff

111
doc/src/sgml/pgbuffercache.sgml
View File

@ -38,82 +38,103 @@
<table id="pgbuffercache-columns">
<title><structname>pg_buffercache</structname> Columns</title>
<tgroup cols="4">
<tgroup cols="1">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
<entry role="catalog_table_entry"><para role="column_definition">
Column Type
</para>
<para>
Description
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><structfield>bufferid</structfield></entry>
<entry><type>integer</type></entry>
<entry></entry>
<entry>ID, in the range 1..<varname>shared_buffers</varname></entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>bufferid</structfield> <type>integer</type>
</para>
<para>
ID, in the range 1..<varname>shared_buffers</varname>
</para></entry>
</row>
<row>
<entry><structfield>relfilenode</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal>pg_class.relfilenode</literal></entry>
<entry>Filenode number of the relation</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>relfilenode</structfield> <type>oid</type>
(references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>relfilenode</structfield>)
</para>
<para>
Filenode number of the relation
</para></entry>
</row>
<row>
<entry><structfield>reltablespace</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal>pg_tablespace.oid</literal></entry>
<entry>Tablespace OID of the relation</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>reltablespace</structfield> <type>oid</type>
(references <link linkend="catalog-pg-tablespace"><structname>pg_tablespace</structname></link>.<structfield>oid</structfield>)
</para>
<para>
Tablespace OID of the relation
</para></entry>
</row>
<row>
<entry><structfield>reldatabase</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal>pg_database.oid</literal></entry>
<entry>Database OID of the relation</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>reldatabase</structfield> <type>oid</type>
(references <link linkend="catalog-pg-database"><structname>pg_database</structname></link>.<structfield>oid</structfield>)
</para>
<para>
Database OID of the relation
</para></entry>
</row>
<row>
<entry><structfield>relforknumber</structfield></entry>
<entry><type>smallint</type></entry>
<entry></entry>
<entry>Fork number within the relation; see
<filename>include/common/relpath.h</filename></entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>relforknumber</structfield> <type>smallint</type>
</para>
<para>
Fork number within the relation; see
<filename>include/common/relpath.h</filename>
</para></entry>
</row>
<row>
<entry><structfield>relblocknumber</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Page number within the relation</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>relblocknumber</structfield> <type>bigint</type>
</para>
<para>
Page number within the relation
</para></entry>
</row>
<row>
<entry><structfield>isdirty</structfield></entry>
<entry><type>boolean</type></entry>
<entry></entry>
<entry>Is the page dirty?</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>isdirty</structfield> <type>boolean</type>
</para>
<para>
Is the page dirty?
</para></entry>
</row>
<row>
<entry><structfield>usagecount</structfield></entry>
<entry><type>smallint</type></entry>
<entry></entry>
<entry>Clock-sweep access count</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>usagecount</structfield> <type>smallint</type>
</para>
<para>
Clock-sweep access count
</para></entry>
</row>
<row>
<entry><structfield>pinning_backends</structfield></entry>
<entry><type>integer</type></entry>
<entry></entry>
<entry>Number of backends pinning this buffer</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>pinning_backends</structfield> <type>integer</type>
</para>
<para>
Number of backends pinning this buffer
</para></entry>
</row>
</tbody>
</tgroup>
</table>

351
doc/src/sgml/pgstatstatements.sgml
View File

@ -44,253 +44,310 @@
<table id="pgstatstatements-columns">
<title><structname>pg_stat_statements</structname> Columns</title>
<tgroup cols="4">
<tgroup cols="1">
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
<entry role="catalog_table_entry"><para role="column_definition">
Column Type
</para>
<para>
Description
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><structfield>userid</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry>
<entry>OID of user who executed the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>userid</structfield> <type>oid</type>
(references <link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.<structfield>oid</structfield>)
</para>
<para>
OID of user who executed the statement
</para></entry>
</row>
<row>
<entry><structfield>dbid</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry>
<entry>OID of database in which the statement was executed</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>dbid</structfield> <type>oid</type>
(references <link linkend="catalog-pg-database"><structname>pg_database</structname></link>.<structfield>oid</structfield>)
</para>
<para>
OID of database in which the statement was executed
</para></entry>
</row>
<row>
<entry><structfield>queryid</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Internal hash code, computed from the statement's parse tree</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>queryid</structfield> <type>bigint</type>
</para>
<para>
Internal hash code, computed from the statement's parse tree
</para></entry>
</row>
<row>
<entry><structfield>query</structfield></entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>Text of a representative statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>query</structfield> <type>text</type>
</para>
<para>
Text of a representative statement
</para></entry>
</row>
<row>
<entry><structfield>plans</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Number of times the statement was planned</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>plans</structfield> <type>bigint</type>
</para>
<para>
Number of times the statement was planned
</para></entry>
</row>
<row>
<entry><structfield>total_plan_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Total time spent planning the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>total_plan_time</structfield> <type>double precision</type>
</para>
<para>
Total time spent planning the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>min_plan_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Minimum time spent planning the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>min_plan_time</structfield> <type>double precision</type>
</para>
<para>
Minimum time spent planning the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>max_plan_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Maximum time spent planning the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>max_plan_time</structfield> <type>double precision</type>
</para>
<para>
Maximum time spent planning the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>mean_plan_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Mean time spent planning the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>mean_plan_time</structfield> <type>double precision</type>
</para>
<para>
Mean time spent planning the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>stddev_plan_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Population standard deviation of time spent planning the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>stddev_plan_time</structfield> <type>double precision</type>
</para>
<para>
Population standard deviation of time spent planning the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>calls</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Number of times the statement was executed</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>calls</structfield> <type>bigint</type>
</para>
<para>
Number of times the statement was executed
</para></entry>
</row>
<row>
<entry><structfield>total_exec_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Total time spent executing the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>total_exec_time</structfield> <type>double precision</type>
</para>
<para>
Total time spent executing the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>min_exec_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Minimum time spent executing the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>min_exec_time</structfield> <type>double precision</type>
</para>
<para>
Minimum time spent executing the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>max_exec_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Maximum time spent executing the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>max_exec_time</structfield> <type>double precision</type>
</para>
<para>
Maximum time spent executing the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>mean_exec_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Mean time spent executing the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>mean_exec_time</structfield> <type>double precision</type>
</para>
<para>
Mean time spent executing the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>stddev_exec_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>Population standard deviation of time spent executing the statement, in milliseconds</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>stddev_exec_time</structfield> <type>double precision</type>
</para>
<para>
Population standard deviation of time spent executing the statement, in milliseconds
</para></entry>
</row>
<row>
<entry><structfield>rows</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of rows retrieved or affected by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>rows</structfield> <type>bigint</type>
</para>
<para>
Total number of rows retrieved or affected by the statement
</para></entry>
</row>
<row>
<entry><structfield>shared_blks_hit</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of shared block cache hits by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>shared_blks_hit</structfield> <type>bigint</type>
</para>
<para>
Total number of shared block cache hits by the statement
</para></entry>
</row>
<row>
<entry><structfield>shared_blks_read</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of shared blocks read by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>shared_blks_read</structfield> <type>bigint</type>
</para>
<para>
Total number of shared blocks read by the statement
</para></entry>
</row>
<row>
<entry><structfield>shared_blks_dirtied</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of shared blocks dirtied by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>shared_blks_dirtied</structfield> <type>bigint</type>
</para>
<para>
Total number of shared blocks dirtied by the statement
</para></entry>
</row>
<row>
<entry><structfield>shared_blks_written</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of shared blocks written by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>shared_blks_written</structfield> <type>bigint</type>
</para>
<para>
Total number of shared blocks written by the statement
</para></entry>
</row>
<row>
<entry><structfield>local_blks_hit</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of local block cache hits by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>local_blks_hit</structfield> <type>bigint</type>
</para>
<para>
Total number of local block cache hits by the statement
</para></entry>
</row>
<row>
<entry><structfield>local_blks_read</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of local blocks read by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>local_blks_read</structfield> <type>bigint</type>
</para>
<para>
Total number of local blocks read by the statement
</para></entry>
</row>
<row>
<entry><structfield>local_blks_dirtied</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of local blocks dirtied by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>local_blks_dirtied</structfield> <type>bigint</type>
</para>
<para>
Total number of local blocks dirtied by the statement
</para></entry>
</row>
<row>
<entry><structfield>local_blks_written</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of local blocks written by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>local_blks_written</structfield> <type>bigint</type>
</para>
<para>
Total number of local blocks written by the statement
</para></entry>
</row>
<row>
<entry><structfield>temp_blks_read</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of temp blocks read by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>temp_blks_read</structfield> <type>bigint</type>
</para>
<para>
Total number of temp blocks read by the statement
</para></entry>
</row>
<row>
<entry><structfield>temp_blks_written</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>Total number of temp blocks written by the statement</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>temp_blks_written</structfield> <type>bigint</type>
</para>
<para>
Total number of temp blocks written by the statement
</para></entry>
</row>
<row>
<entry><structfield>blk_read_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>
Total time the statement spent reading blocks, in milliseconds
(if <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>blk_read_time</structfield> <type>double precision</type>
</para>
<para>
Total time the statement spent reading blocks, in milliseconds
(if <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
</para></entry>
</row>
<row>
<entry><structfield>blk_write_time</structfield></entry>
<entry><type>double precision</type></entry>
<entry></entry>
<entry>
Total time the statement spent writing blocks, in milliseconds
(if <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>blk_write_time</structfield> <type>double precision</type>
</para>
<para>
Total time the statement spent writing blocks, in milliseconds
(if <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
</para></entry>
</row>
<row>
<entry><structfield>wal_bytes</structfield></entry>
<entry><type>numeric</type></entry>
<entry></entry>
<entry>
Total amount of WAL bytes generated by the statement
</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>wal_records</structfield> <type>bigint</type>
</para>
<para>
Total number of WAL records generated by the statement
</para></entry>
</row>
<row>
<entry><structfield>wal_records</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>
Total number of WAL records generated by the statement
</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>wal_fpi</structfield> <type>bigint</type>
</para>
<para>
Total number of WAL full page images generated by the statement
</para></entry>
</row>
<row>
<entry><structfield>wal_fpi</structfield></entry>
<entry><type>bigint</type></entry>
<entry></entry>
<entry>
Total number of WAL full page images generated by the statement
</entry>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>wal_bytes</structfield> <type>numeric</type>
</para>
<para>
Total amount of WAL bytes generated by the statement
</para></entry>
</row>
</tbody>
</tgroup>
</table>

10
doc/src/sgml/stylesheet-fo.xsl
View File

@ -79,6 +79,16 @@
</fo:block>
</xsl:template>
<!-- formatting for entries in tables of catalog/view columns -->
<xsl:template match="entry[@role='catalog_table_entry']/para">
<fo:block margin-left="4em" text-align="left">
<xsl:if test="self::para[@role='column_definition']">
<xsl:attribute name="text-indent">-3.5em</xsl:attribute>
</xsl:if>
<xsl:apply-templates/>
</fo:block>
</xsl:template>
<!-- overrides stylesheet-common.xsl -->
<!-- FOP needs us to be explicit about the font to use for right arrow -->
<xsl:template match="returnvalue">

34
doc/src/sgml/stylesheet.css
View File

@ -96,6 +96,36 @@ td.func_table_entry pre.programlisting {
padding-left: 4em;
}
/* formatting for entries in tables of catalog/view columns */
th.catalog_table_entry p,
td.catalog_table_entry p {
margin-top: 0.1em;
margin-bottom: 0.1em;
padding-left: 4em;
text-align: left;
}
th.catalog_table_entry p.column_definition {
text-indent: -3.5em;
word-spacing: 0.25em;
}
td.catalog_table_entry p.column_definition {
text-indent: -3.5em;
}
p.column_definition code.type {
padding-left: 0.25em;
padding-right: 0.25em;
}
td.catalog_table_entry pre.programlisting {
margin-top: 0.1em;
margin-bottom: 0.1em;
padding-left: 4em;
}
/* Put these here instead of inside the HTML (see unsetting of
admon.style in XSL) so that the web site stylesheet can set its own
style. */
@ -115,6 +145,10 @@ pre.literallayout, .screen, .synopsis, .programlisting {
margin-left: 4ex;
}
ul.itemizedlist {
margin-left: 2.5rem;
}
.comment { color: red; }
var { font-family: monospace; font-style: italic; }