Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jXve4-0008My-G3
	for pgsql-docs@arkaria.postgresql.org; Sun, 10 May 2020 23:46:08 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jXve3-0007t9-4H
	for pgsql-docs@arkaria.postgresql.org; Sun, 10 May 2020 23:46:07 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jXve2-0007t1-Uc
	for pgsql-docs@lists.postgresql.org; Sun, 10 May 2020 23:46:06 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jXvdw-0005FK-2P
	for pgsql-docs@lists.postgresql.org; Sun, 10 May 2020 23:46:05 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id 04ANjwYL014481
	for <pgsql-docs@lists.postgresql.org>; Sun, 10 May 2020 19:45:59 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: pgsql-docs@lists.postgresql.org
Subject: Getting rid of "Unresolved ID reference" in PDF builds
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <14479.1589154358.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Sun, 10 May 2020 19:45:58 -0400
Message-ID: <14480.1589154358@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk

Our PDF docs build has a couple of dozen complaints like

WARNING: Destination: Unresolved ID reference "sql-altercollation-notes-ti=
tle" found.

These are due to cross-reference links like this:

      See <xref linkend=3D"sql-altercollation-notes"
      endterm=3D"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 SC=
HEMA <replaceable>new_sche
     <listitem>
      <para>
       Update the collation's version.
-      See <xref linkend=3D"sql-altercollation-notes"
-      endterm=3D"sql-altercollation-notes-title"/> below.
+      See <xref linkend=3D"sql-altercollation-notes"/> below.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>
 =

- <refsect1 id=3D"sql-altercollation-notes">
-  <title id=3D"sql-altercollation-notes-title">Notes</title>
+ <refsect1 id=3D"sql-altercollation-notes" xreflabel=3D"Notes">
+  <title>Notes</title>
 =

   <para>
    When using collations provided by the ICU library, the ICU-specific ve=
rsion

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=3D"function-encode">
+     <row>
       <entry role=3D"func_table_entry"><para role=3D"func_signature">
-       <indexterm>
+       <indexterm id=3D"function-encode">
         <primary>encode</primary>
        </indexterm>
        <function>encode</function> ( <parameter>bytes</parameter> <type>b=
ytea</type>,

so I propose doing that.

			regards, tom lane