mirror of
https://github.com/postgres/postgres.git
synced 2025-08-28 18:48:04 +03:00
Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs.
Use xreflabel attributes instead of endterm attributes to control the appearance of links to subsections of SQL command reference pages. This is simpler, it matches what we do elsewhere (e.g. for GUC variables), and it doesn't draw "Unresolved ID reference" warnings from the PDF toolchain. Fix some places where the text was absolutely dependent on an <xref> rendering exactly so, by using a <link> around the required text instead. At least one of those spots had already been turned into bad grammar by subsequent changes, and the whole idea is just too fragile for my taste. <xref> does NOT have fixed output, don't write as if it does. Consistently include a page-level link in cross-man-page references, because otherwise they are useless/nonsensical in man-page output. Likewise, be consistent about mentioning "below" or "above" in same-page references; we were doing that in about 90% of the cases, but now it's 100%. Also get rid of another nonfunctional-in-PDF idea, of making cross-references to functions by sticking ID tags on <row> constructs. We can put the IDs on <indexterm>s instead --- which is probably not any more sensible in abstract terms, but it works where the other doesn't. (There is talk of attaching cross-reference IDs to most or all of the docs' function descriptions, but for now I just fixed the two that exist.) Discussion: https://postgr.es/m/14480.1589154358@sss.pgh.pa.us
This commit is contained in:
@@ -126,8 +126,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
|
||||
updates, or deletes on the table; whereas a standard index build
|
||||
locks out writes (but not reads) on the table until it's done.
|
||||
There are several caveats to be aware of when using this option
|
||||
— see <xref linkend="sql-createindex-concurrently"
|
||||
endterm="sql-createindex-concurrently-title"/>.
|
||||
— see <xref linkend="sql-createindex-concurrently"/> below.
|
||||
</para>
|
||||
<para>
|
||||
For temporary tables, <command>CREATE INDEX</command> is always
|
||||
@@ -337,7 +336,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
|
||||
<listitem>
|
||||
<para>
|
||||
The name of an index-method-specific storage parameter. See
|
||||
<xref linkend="sql-createindex-storage-parameters" endterm="sql-createindex-storage-parameters-title"/>
|
||||
<xref linkend="sql-createindex-storage-parameters"/> below
|
||||
for details.
|
||||
</para>
|
||||
</listitem>
|
||||
@@ -366,8 +365,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
|
||||
|
||||
</variablelist>
|
||||
|
||||
<refsect2 id="sql-createindex-storage-parameters">
|
||||
<title id="sql-createindex-storage-parameters-title">Index Storage Parameters</title>
|
||||
<refsect2 id="sql-createindex-storage-parameters" xreflabel="Index Storage Parameters">
|
||||
<title>Index Storage Parameters</title>
|
||||
|
||||
<para>
|
||||
The optional <literal>WITH</literal> clause specifies <firstterm>storage
|
||||
@@ -559,8 +558,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
|
||||
<refsect2 id="sql-createindex-concurrently">
|
||||
<title id="sql-createindex-concurrently-title">Building Indexes Concurrently</title>
|
||||
<refsect2 id="sql-createindex-concurrently" xreflabel="Building Indexes Concurrently">
|
||||
<title>Building Indexes Concurrently</title>
|
||||
|
||||
<indexterm zone="sql-createindex-concurrently">
|
||||
<primary>index</primary>
|
||||
@@ -688,7 +687,7 @@ Indexes:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An <firstterm>operator class</firstterm> with its optional parameters
|
||||
An <firstterm>operator class</firstterm> with optional parameters
|
||||
can be specified for each column of an index.
|
||||
The operator class identifies the operators to be
|
||||
used by the index for that column. For example, a B-tree index on
|
||||
|
Reference in New Issue
Block a user