Обсуждение: Building PDFs error: \pdfendlink ended up in different nesting level than \pd

[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 <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 \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

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

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

Alvaro Herrera wrote:
> 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.

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.

--
  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> writes:
> Alvaro Herrera wrote:
>> Excerpts from Bruce Momjian's message of mar abr 26 12:44:39 -0300 2011:
>>> Alvaro Herrera wrote:
>>>> 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.

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

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

Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Alvaro Herrera wrote:
> >> Excerpts from Bruce Momjian's message of mar abr 26 12:44:39 -0300 2011:
> >>> Alvaro Herrera wrote:
> >>>> 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.
>
> > 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.
>
> 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.

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.

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

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

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.

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

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

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

On Mon, Sep 5, 2011 at 11:50 AM, Bruce Momjian <bruce@momjian.us> wrote:
> 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.
>
> 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