Subject: Building PDFs error: \pdfendlink ended up in different nesting level than \pd

From: Josh Kupershmidt <[email-masked]>
Date: Wed, 26 Jan 2011 22:36:23 -0500

[Moving thread[1] from openjade-devel to pgsql-docs, since the PDF
build is now blowing up in pdfTeX]

On Wed, Jan 26, 2011 at 11:27 AM, Tom Lane <[email-masked]> wrote:
> Josh Kupershmidt <[email-masked]> writes:
>> though after a few minutes, I get problems from pdfTeX:
>> [snip]
>> ! pdfTeX error (ext4): \pdfendlink ended up in different nesting level than \pd
>> fstartlink.
>
> 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.

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.

> FWIW, the issue mentioned at
> http://archives.postgresql.org/pgsql-docs/2010-04/msg00022.php
> is overflow of the TeX string table, which I doubt has anything
> to do with the "flow object not accepted by port" problem.  We've
> seen that one happening off and on for years, and nobody really
> has the faintest idea what makes it come or go.

Yeah, I didn't think that was related to the problems I saw, but I
thought it was worth trying to tweak texmf.cnf anyway.

What versions of pdftex are folks who can build these PDFs using? And
is anyone able to build either postgres-A4.pdf or postgres-US.pdf on
Ubuntu or Debian-ish distros using the standard packages? pdftex
--version says for me:

pdfTeX 3.1415926-1.40.10-2.2 (TeX Live 2009/Debian)
kpathsea version 5.0.0
...
Compiled with libpng 1.2.44; using libpng 1.2.44
Compiled with zlib 1.2.3.4; using zlib 1.2.3.4
Compiled with poppler version 0.14.2

Josh

-- 
[1] original thread on openjade-devel:
http://sourceforge.net/mailarchive/message.php?msg_id=26959520

---

From: Tom Lane <[email-masked]>
Date: Thu, 27 Jan 2011 18:57:27 -0500

Josh Kupershmidt <[email-masked]> writes:
>>> ! pdfTeX error (ext4): \pdfendlink ended up in different nesting level than \pdfstartlink.

> 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.

> 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

---

From: Alvaro Herrera <[email-masked]>
Date: Fri, 28 Jan 2011 00:07:31 -0300

> you sometimes see it only in US or only in A4 output.

Wow, that sucks.  One wonders why it doesn't go to the trouble of moving
the entire para to the next page, or some such.

> tweak the makefile to make this less inconvenient.)

Maybe mark it .PRECIOUS?

-- 
Álvaro Herrera <[email-masked]>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

---

From: Tom Lane <[email-masked]>
Date: Thu, 27 Jan 2011 22:36:12 -0500

> Maybe mark it .PRECIOUS?

Well, it is only an intermediate file, so not sure we want that.
I was wondering more about a behavior where the file would be thrown
away on successful completion but *not* if pdftex fails.  I think we
could have that if the sequence were folded into just one make rule
... is there a good reason for .tex-pdf to be a separate target?

			regards, tom lane

---

From: Josh Kupershmidt <[email-masked]>
Date: Thu, 27 Jan 2011 23:38:13 -0500

> tweak the makefile to make this less inconvenient.)

Thanks for looking into this further. Both the -US and -A4 PDFs are
still failing for me on a recent git checkout including your change to
catalog.sgml.

I tried the two-step make process you suggested. The second step of
building postgres-US.pdf failed like so:

Overfull \hbox (1.19998pt too wide) in alignment at lines 1390237--1390679
 [] []

Package longtable Warning: Column widths have changed
(longtable)                in table 287 on input line 1390679.

[3987.0.6

I looked around line 1390679 of postgres-US.tex-pdf, where I saw this
snippet from seg.sgml:

       (spaces around the range operator are ignored)

so I'm guessing some link around that spot is to blame. Perhaps trying
to hack up all these problem spots in the SGML source is a lost cause,
at least for my build environment. I might try pestering folks on the
pdftex mailing list next.

Josh

---

From: Tom Lane <[email-masked]>
Date: Fri, 28 Jan 2011 10:11:16 -0500

> still failing for me on a recent git checkout including your change to

Hmph.  HEAD does build both US and A4 sizes for me, using current Fedora
13 docs toolchain.  But given what we now know, it could be sensitive to
fairly small deltas in the toolchain, since any small change in spacing
decisions might create or remove a problem.

>        (spaces around the range operator are ignored)

Well, you're getting a lot further anyway ;-).  But it's real curious
that you seem to be hitting these more easily than anyone else ever has.
I wonder if there's something about your toolchain that makes the issue
more probable.

Something we might consider doing to try to make this more stable is to
see if we can force more page breaks in the PDF output.  That would
isolate each chapter or section from changes in others.

			regards, tom lane

---

From: Tom Lane <[email-masked]>
Date: Fri, 28 Jan 2011 12:11:51 -0500

I wrote:
>> (spaces around the range operator are ignored)

The nearest preceding candidate for a split link seems to be the
reference to table F-25 in the opening paragraph of section F.36.2
(attached PNG shows what it looks like when I build HEAD in US page
size).  Since that sentence is rather badly in need of copy-editing
anyway, I'll go see if I can fix it.  However, it's rather disturbing
that in my build the problem seems to be more than half a dozen lines
away from a page boundary.  I could believe a line or two discrepancy
between different toolchains, but this seems like a lot.

> isolate each chapter or section from changes in others.

In my build, the entire contrib manual is potentially interdependent,
because the sub-sections of Appendix F don't start new pages.  This
seems bad.  What is even more curious is that it looks like the function
"man pages" within the dblink section *do* get forced page breaks.
That is inconsistent to say the least.  How much control do we have over
this type of formatting decision?

			regards, tom lane

---

From: Alvaro Herrera <[email-masked]>
Date: Fri, 11 Feb 2011 19:40:43 -0300

> this type of formatting decision?

I think this is relative, because it seems we can control it if we're
able to hack the stylesheet.dsl file -- which I know I can't quite
follow.  Peter is the person to ask, I think.

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 12 Feb 2011 09:44:10 +0200

> this type of formatting decision?

There is a parameter that controls whether a references page starts on a
new page.  But that's it.  It's not impossible to hack the stylesheet to
add more page breaks, but that would affect the whole book, not just one
particular chapter.

With the promotion of the contrib stuff, perhaps they should each get
their own chapter in a new part.

---

From: Alvaro Herrera <[email-masked]>
Date: Mon, 14 Feb 2011 12:34:56 -0300

> their own chapter in a new part.

+1 to this idea.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 11 Mar 2011 08:41:19 -0500 (EST)

Peter, any news on this?

---------------------------------------------------------------------------

Peter Eisentraut wrote:
> Sent via pgsql-docs mailing list ([email-masked])
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 12 Mar 2011 09:31:30 +0200

> Peter, any news on this?

I wasn't planning to work on it.

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 12 Mar 2011 09:13:34 -0500 (EST)

> I wasn't planning to work on it.

OK, it is not something worthwhile, or just something you don't have
time for.  If the later, can you give us a hint on how to fix it?

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 12 Mar 2011 22:29:55 +0200

> time for.  If the later, can you give us a hint on how to fix it?

I'm not even sure what the actual action item is supposed to be.

---

From: Tom Lane <[email-masked]>
Date: Sat, 12 Mar 2011 15:57:34 -0500

> I'm not even sure what the actual action item is supposed to be.

The last suggestion in the thread was to move the contrib docs up one
level in the hierarchy, ie each contrib module would get a chapter not a
sect1.

			regards, tom lane

---

From: Josh Kupershmidt <[email-masked]>
Date: Tue, 5 Apr 2011 22:15:46 -0400

> I wonder if there's something about your toolchain that makes the issue

As a belated followup, I'm now able to get at least postgres-A4.pdf to
build successfully on this Ubuntu 10.10 machine (I haven't tried
postgres-US.pdf yet.). There have been a fair number of system updates
in the past few months, including some recent ones related to texlive
I noticed the other day. Hopefully the stars will stay aligned, but
I'll keep an eye out against this stuff breaking again.

Here's a summary of the Ubuntu packages I have installed now, with
version numbers from 'apt-cache show packagename':
 * docbook 4.5-4
 * docbook-dsssl 1.79-6
 * docbook-xsl 1.75.2+dfsg-5
 * openjade1.3 1.3.2-10
 * xsltproc 1.1.26-6

Thanks for all the help, Tom.
Josh

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 26 Apr 2011 11:15:50 -0400 (EDT)

> level in the hierarchy, ie each contrib module would get a chapter not a

I think we would have to move "Additional Supplied Modules" up into its
own book, and then list each module.  The problem is that there are 42
modules so that list is going to be pretty long in the table of
contents.

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 26 Apr 2011 12:43:06 -0300

Excerpts from Bruce Momjian's message of mar abr 26 12:15:50 -0300 2011:
> > > On lr, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote:

Also, most of the sections are pretty short.  Making each of them a
chapter seems a waste.  I think some of them deserve a full chapter
(dblink, citext?, hstore, intarray, ltree, pgbench, pgcrypto, pgtrgm?,
pg_upgrade, tablefunc), but most don't.  (Some of the others could,
perhaps, get moved under "Reference").

Would it work to move only some?

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 26 Apr 2011 11:44:39 -0400 (EDT)

> Would it work to move only some?

I think moving some would be even worse than what we have now, unless
you can propose some logic about why they would be split.

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 26 Apr 2011 12:56:23 -0300

> you can propose some logic about why they would be split.

Remember that this thread is about someone being unable to build a PDF
from our docs (and the proposed workaround being "insert more page
breaks"), not about how logical the documentation is.

In any case, the ones I listed are the ones that have more structure
documentation-wise (which also are the ones that have received more
attention and thus are of more interest to users), so there is some
logic behind it.

Am I saying that not all contrib modules are created equal?  Yes, I am.
So sue me.

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 26 Apr 2011 12:00:14 -0400 (EDT)

> Am I saying that not all contrib modules are created equal?  Yes, I am.

It is hard to see how a user is going to guess which ones are better
than others when trying to find something in the docs.  I think we are
going to need logical categories if we want to split them up.

---

From: Tom Lane <[email-masked]>
Date: Tue, 26 Apr 2011 12:10:11 -0400

> going to need logical categories if we want to split them up.

I don't think this works.  Aside from the illogicality, what will you do
when somebody works a bit harder on one of the modules that have "short"
documentation?  Push it over into the other appendix in the next
release?  Ugh.

Unlike Bruce, I don't have any problem with pushing them all up to
chapter level.  One point of such a change is to make them more visible,
so I do not see it as a "disadvantage" that they'd all be visible in the
TOC --- more the opposite.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 26 Apr 2011 13:32:31 -0400 (EDT)

> TOC --- more the opposite.

Well, that was the original thread idea, and I don't have a major
problem with it;  I was just pointing out that it will bloat the table
of contents.  FYI, we don't currently have any headings on the table of
contents that are dynamic in that they specify items that could grow
over time.

What do you think about moving the release notes up a bit, so we have a
8.1 release notes, 8.2 release notes, and all the subreleases are under
that section?  Not sure I like that but I am throwing out the idea.

---

From: Tom Lane <[email-masked]>
Date: Tue, 26 Apr 2011 13:52:50 -0400

> that section?  Not sure I like that but I am throwing out the idea.

Haven't heard any particular demand to make the release notes more
visible, so I don't feel any attraction to that idea.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 5 Sep 2011 12:50:24 -0400 (EDT)

> their own chapter in a new part.

Is this a TODO?  Did we ever decide on this?

---

From: Robert Haas <[email-masked]>
Date: Thu, 15 Sep 2011 06:46:29 -0500

> Is this a TODO?  Did we ever decide on this?

Well, some of the contrib modules are such little stupid things that
giving them their own chapter seems excessive.  sepgsql might merit
its own chapter, but dummy_seclabel surely doesn't.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company