public inbox for [email protected]  

help / color / mirror / Atom feed

From: Tom Lane <[email protected]>
To: Josh Kupershmidt <[email protected]>
Cc: pgsql-docs <[email protected]>
Subject: Re: Building PDFs error: \pdfendlink ended up in different nesting level than \pd
Date: Thu, 27 Jan 2011 18:57:27 -0500
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>

Josh Kupershmidt <[email protected]> writes:
> On Wed, Jan 26, 2011 at 11:27 AM, Tom Lane <[email protected]> wrote:
>> Josh Kupershmidt <[email protected]> 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

view thread (26+ messages)  latest in thread

reply

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: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: Building PDFs error: \pdfendlink ended up in different nesting level than \pd
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox