database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-08-28 18:48:04 +03:00
Code Activity

Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs.

Browse Source 
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:
Tom Lane
2020-05-11 14:15:49 -04:00
parent 624686abcf
commit 60c90c16c1
26 changed files with 167 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/sgml/ref/declare.sgml
View File

@@ -99,8 +99,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
<literal>NO SCROLL</literal> specifies that the cursor cannot be
used to retrieve rows in a nonsequential fashion. The default is to
allow scrolling in some cases; this is not the same as specifying
<literal>SCROLL</literal>. See <xref linkend="sql-declare-notes"
endterm="sql-declare-notes-title"/> for details.
<literal>SCROLL</literal>. See <xref linkend="sql-declare-notes"/>
below for details.
</para>
</listitem>
</varlistentry>
@@ -139,8 +139,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
</para>
</refsect1>
<refsect1 id="sql-declare-notes">
<title id="sql-declare-notes-title">Notes</title>
<refsect1 id="sql-declare-notes" xreflabel="Notes">
<title>Notes</title>
<para>
Normal cursors return data in text format, the same as a