Thread

Getting rid of "Unresolved ID reference" in PDF builds

Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-10T23:45:58Z

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