4.11.4 Debugging Failed Automatic Link Generation

If automatic link generation produces a bad link, document processing produces with messages such as these during the document-preparation stage:

idremap.pl: ERROR: Cannot find reference for id=[lock-table]
idremap.pl: ERROR: Cannot find reference for id=[unlock-tables]

During output production, the messages look like this:

Error: no ID for constraint linkend: lock-table.
Error: no ID for constraint linkend: unlock-tables.

The problems can be caused by incorrect content within the autolinked element, or failure to provide a condition attribute that helps the autolinking transform produce a correct link. The cases just shown resulted from the following input:

<literal role="stmt">LOCK TABLE</literal>
<literal role="stmt">UNLOCK TABLES</literal>

Both statements are described in the Reference Manual in a section that has an ID of lock-tables. The fix for the first is to change TABLE to TABLES. The fix for the second is to add a condition attribute:

<literal role="stmt">LOCK TABLES</literal>
<literal role="stmt" condition="lock-tables">UNLOCK TABLES</literal>

It is often easy to find offending references, for example, by using grep on the manual source files. It is less easy when the original reference is part of input that produces a dynamically generated file. One way to track down these problems is to produce the -prepped.xml file from which document output is produced. For example, if output generation for refman-5.5 produces autolink failures, execute this command in the refman-5.5 directory:

shell> make manual-prepped.xml

Then look through manual-prepped.xml for these links:

<link linkend="lock-table">
<link linkend="unlock-tables">

That should give you enough context to figure out where the original input came from.