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

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

Excerpts from Tom Lane's message of jue ene 27 20:57:27 -0300 2011:

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.

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.

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

Maybe mark it .PRECIOUS?

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera <alvherre@commandprompt.com> writes:

Excerpts from Tom Lane's message of jue ene 27 20:57:27 -0300 2011:

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

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

On Thu, Jan 27, 2011 at 6:57 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Josh Kupershmidt <schmiddy@gmail.com> writes:

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

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
! pdfTeX error (ext4): \pdfendlink ended up in different nesting level than \pd
fstartlink.

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

Josh Kupershmidt <schmiddy@gmail.com> writes:

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.

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.

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)

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

I wrote:
Josh Kupershmidt <schmiddy@gmail.com> writes:

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)

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.

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.

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

Excerpts from Tom Lane's message of vie ene 28 14:11:51 -0300 2011:

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.

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?

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.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On fre, 2011-01-28 at 12:11 -0500, Tom Lane wrote:

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?

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.

Excerpts from Peter Eisentraut's message of sáb feb 12 04:44:10 -0300 2011:

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

+1 to this idea.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Peter, any news on this?

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

Peter Eisentraut wrote:

On fre, 2011-01-28 at 12:11 -0500, Tom Lane wrote:

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?

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.

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

On fre, 2011-03-11 at 08:41 -0500, Bruce Momjian wrote:

Peter, any news on this?

I wasn't planning to work on it.

Peter Eisentraut wrote:

On fre, 2011-03-11 at 08:41 -0500, Bruce Momjian wrote:

Peter, any news on this?

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?

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

Peter Eisentraut wrote:

On fre, 2011-01-28 at 12:11 -0500, Tom Lane wrote:

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?

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.

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

On lör, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote:

Peter Eisentraut wrote:

On fre, 2011-03-11 at 08:41 -0500, Bruce Momjian wrote:

Peter, any news on this?

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?

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

Peter Eisentraut <peter_e@gmx.net> writes:

On lör, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote:

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?

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

On Fri, Jan 28, 2011 at 10:11 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Josh Kupershmidt <schmiddy@gmail.com> writes:

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.

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.

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)

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.

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

Tom Lane wrote:

Peter Eisentraut <peter_e@gmx.net> writes:

On l��r, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote:

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?

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.

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.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

Excerpts from Bruce Momjian's message of mar abr 26 12:15:50 -0300 2011:

Tom Lane wrote:

Peter Eisentraut <peter_e@gmx.net> writes:

On lr, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote:

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?

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.

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.

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?

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:

Excerpts from Bruce Momjian's message of mar abr 26 12:15:50 -0300 2011:

Tom Lane wrote:

Peter Eisentraut <peter_e@gmx.net> writes:

On lr, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote:

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?

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.

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.

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?

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.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

Excerpts from Bruce Momjian's message of mar abr 26 12:44:39 -0300 2011:

Alvaro Herrera 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?

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.

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.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support