To: Josh Kupershmidt <schmiddy@gmail.com>
cc: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Re: Building PDFs error: \pdfendlink ended up in different nesting
	level than \pd
In-reply-to: <AANLkTim7y4cUFxoMcmC-o_SLAiM7va=3DLtQxa2znh_Q@mail.gmail.com> 
References: <AANLkTim7y4cUFxoMcmC-o_SLAiM7va=3DLtQxa2znh_Q@mail.gmail.com>
Comments: In-reply-to Josh Kupershmidt <schmiddy@gmail.com>
	message dated "Wed, 26 Jan 2011 22:36:23 -0500"
Date: Thu, 27 Jan 2011 18:57:27 -0500
Message-ID: <9473.1296172647@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Josh Kupershmidt <schmiddy@gmail.com> writes:
> On Wed, Jan 26, 2011 at 11:27 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Josh Kupershmidt <schmiddy@gmail.com> writes:
>>> though after a few minutes, I get problems from pdfTeX:
>>> [snip]
>>> ! pdfTeX error (ext4): \pdfendlink ended up in different nesting level than \pdfstartlink.

>> We've seen cases of that before too:
>> http://archives.postgresql.org/pgsql-docs/2010-07/msg00083.php
>> 
>> although you might be seeing a different cause since the context looks a
>> bit different.

> Looks like the same type of error alright. Though I'm building from a
> recent git master checkout, and I see the hack was put in place a few
> months ago in installation.sgml to convert a troublesome table into a
> list. Also, I get the same error on both the -A4 and -US pdf builds.

I finally solved this after a bit of googling.

http://tug.org/errors.html
explains that this error message occurs when a hyperlink would get split
across a page boundary in the PDF output.  The recommended solution is
to adjust your text to prevent the link from being split, which is
probably sensible from a usability standpoint even if it's a PITA for
development.  So that explains why we get the error from perfectly valid
SGML, why it comes and goes after seemingly-unrelated changes, and why
you sometimes see it only in US or only in A4 output.

> How did you figure out that the problem was coming from that spot in
> installation.sgml? I'd be interested to see whether another hack would
> work in lieu of an actual fix in pdftex.

If you look at the mentioned line number in the tex-pdf file, you can
figure out where you are in the document, assuming your eyes don't glaze
over from the incredibly verbose TeX macros first.

(Note: if you just do "make postgres-A4.pdf", make will unhelpfully
throw away the tex-pdf intermediate file upon error.  What I have done
when I needed to look is to explicitly "make postgres-A4.tex-pdf" and
then "make postgres-A4.pdf", which keeps make from discarding the
tex-pdf file when the second step fails.  I wonder though if we could
tweak the makefile to make this less inconvenient.)

In this case it turned out the culprit was the first paragraph of
description for pg_conversion in catalogs.sgml.  That looked like this
in the PDF output:

	The catalog pg_conversion describes the available encoding conversion procedures. See CREATE
	CONVERSION for more information.

where "CREATE CONVERSION" is a hyperlink to the appropriate man page.
That works until the day that the two lines happen to split across a
page boundary, and then it doesn't.

I reworded so that "CREATE CONVERSION" fits all on the first line of the
para, which will prevent this particular case from troubling us in
future.  But I guess we can expect to see this error again.  I would say
that most of the time it's not worth fixing this during a development
cycle, only when we are approaching a release point and need to be able
to build PDFs.  Otherwise, unrelated edits are likely to make any
specific problem go away anyway.

			regards, tom lane