From: Tom Lane <tgl@sss.pgh.pa.us>
To: pgsql-docs@lists.postgresql.org
Subject: Getting rid of "Unresolved ID reference" in PDF builds
Date: Sun, 10 May 2020 19:45:58 -0400
Message-ID: <14480.1589154358@sss.pgh.pa.us> (raw)
Our PDF docs build has a couple of dozen complaints like
WARNING: Destination: Unresolved ID reference "sql-altercollation-notes-title" found.
These are due to cross-reference links like this:
See <xref linkend="sql-altercollation-notes"
endterm="sql-altercollation-notes-title"/> below.
They seem to render as desired, so it's not clear why we're getting the
warnings, but nonetheless we are. I experimented and found that it seems
to work just as well, with no warnings, if we use xreflabels instead;
that is,
@@ -93,16 +93,15 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche
<listitem>
<para>
Update the collation's version.
- See <xref linkend="sql-altercollation-notes"
- endterm="sql-altercollation-notes-title"/> below.
+ See <xref linkend="sql-altercollation-notes"/> below.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
- <refsect1 id="sql-altercollation-notes">
- <title id="sql-altercollation-notes-title">Notes</title>
+ <refsect1 id="sql-altercollation-notes" xreflabel="Notes">
+ <title>Notes</title>
<para>
When using collations provided by the ICU library, the ICU-specific version
Since the xreflabel method is already used in our docs, in many more
places than the id-on-a-title method is, I propose we just get rid
of all of these in favor of xreflabels. Does anyone know a reason
to keep these?
There are also a couple of similar warnings
WARNING: Page 230: Unresolved ID reference "function-decode" found.
WARNING: Page 230: Unresolved ID reference "function-encode" found.
that stem from trying to use an "id" on a table <row>. While that
seems to work and produce a live link in the HTML build, it fails
to work at all in the PDF build. We'd previously discovered that
it works in both builds if you stick the "id" on an <indexentry>
instead:
@@ -4355,9 +4355,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
</para></entry>
</row>
- <row id="function-encode">
+ <row>
<entry role="func_table_entry"><para role="func_signature">
- <indexterm>
+ <indexterm id="function-encode">
<primary>encode</primary>
</indexterm>
<function>encode</function> ( <parameter>bytes</parameter> <type>bytea</type>,
so I propose doing that.
regards, tom lane
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-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, pgsql-docs@lists.postgresql.org
Subject: Re: Getting rid of "Unresolved ID reference" in PDF builds
In-Reply-To: <14480.1589154358@sss.pgh.pa.us>
* 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