Subject: 8.1 PDF Documentation.

From: Kris Jurka <[email-masked]>
Date: Mon, 7 Nov 2005 16:35:26 -0500 (EST)

I've built the PDF docs for the past two releases, but my recent attempts 
to build the 8.1 docs have failed.  I previously used Jade 1.2.1, SP 
1.3.4, and docbook-dsssl 1.76, but trying that now results in:

! pdfTeX error (ext4): \pdfendlink ended up in different nesting level 
than \pdfstartlink.

when running pdfjadetex.  I've not been able to find out much about this 
error.  Newer versions of the tools either crash or take days to run. 
I've begun the days long processing, so it will be sometime (if at all) 
before I can generate pdfs for the 8.1 release.

Kris Jurka

---

From: Kris Jurka <[email-masked]>
Date: Thu, 10 Nov 2005 18:01:42 -0500 (EST)

8.1 pdfs are finished.  These versions actually got the correct pdf 
bookmarks and table of contents.  I can probably rebuild the 7.4 and 8.0 
versions in this format if there is sufficient interest.

http://www.ejurka.com/pgsql/docs/

Also the website isn't listing the 8.0 US version here:
http://www.postgresql.org/docs/manuals/

But it is in the cvs repository here:
http://gborg.postgresql.org/cgi-bin/cvsweb.cgi/portal/files/documentation/pdf/8.0/?cvsroot=pgweb

Kris Jurka

---

From: David Fetter <[email-masked]>
Date: Thu, 10 Nov 2005 22:59:27 -0800

On Thu, Nov 10, 2005 at 06:01:42PM -0500, Kris Jurka wrote:
> bookmarks and table of contents.  I can probably rebuild the 7.4 and
> 8.0 versions in this format if there is sufficient interest.

Way cool.  Is producing these PDFs something that could be
distributed?  What tools actually work for this?

Cheers,
D
-- 
David Fetter [email-masked] http://fetter.org/
phone: +1 510 893 6100   mobile: +1 415 235 3778

Remember to vote!

---

From: Kris Jurka <[email-masked]>
Date: Fri, 11 Nov 2005 02:57:26 -0500 (EST)

> distributed?  What tools actually work for this?

Distributed?  Not really.  It can't be done in parts, and there's only two 
sizes (US and A4).  It also really only needs to be done once per release 
(although I suppose it would be nice to do for point releases.)

It took about two days each (run serially) on a 2xOpteron 246 using debian 
unstable's:

openjade: 1.3.2-8
opensp: 1.5.1/0-4
docbook-dsssl: 1.79-3

Kris Jurka

---

From: Tom Lane <[email-masked]>
Date: Fri, 11 Nov 2005 09:43:49 -0500

> It took about two days each (run serially) on a 2xOpteron 246 using debian 

BTW, the -US file sends my (rather old) copy of acroread into what may
be an infinite loop ... I gave up waiting for it to redisplay after
trying to scroll down the bookmarks window.  Even just displaying
successive pages is painfully slow.

I suspect there's something wrong with the toolset you're using.

			regards, tom lane

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 11 Nov 2005 18:07:32 +0100

Tom Lane wrote:
> BTW, the -US file sends my (rather old) copy of acroread into what
> may be an infinite loop ... I gave up waiting for it to redisplay
> after trying to scroll down the bookmarks window.  Even just
> displaying successive pages is painfully slow.

Works like a charm with a more recent acroread.  I suggest yours is 
indeed too old.

-- 
Peter Eisentraut
http://developer.postgresql.org/~petere/

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 15 Nov 2005 00:13:01 -0500 (EST)

> I suspect there's something wrong with the toolset you're using.

I am using Acrobat 5.0 on XP and BSD/OS and it worked fine for me,
including bookmarks.  It was very fast.

I am still unclear why there is no more reliable SGML toolchain for PDF
output after all these years.  Seems things have improved because we now
have bookmarks, but still, why is this functionality not more mainstream.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: David Fetter <[email-masked]>
Date: Mon, 14 Nov 2005 21:20:37 -0800

> including bookmarks.  It was very fast.

Acrobat works beautifully for me, too. :)

> I am still unclear why there is no more reliable SGML toolchain for
> PDF output after all these years.  Seems things have improved
> because we now have bookmarks, but still, why is this functionality
> not more mainstream.

See, there are these tuits, and they're round, and they're a precious
resource usually spent on writing and testing C code rather than on
improving (and helping transition adoption of) the SGML toolchain.

Maybe we can get some kind soul(s) to donate some tuits and/or pay
somebody a wage for awhile to fix the toolchain etc. :)

Cheers,
D

Remember to vote!

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 15 Nov 2005 08:23:41 -0300

> have bookmarks, but still, why is this functionality not more mainstream.

There is no SGML toolchain because SGML has been abandoned as the
DocBook markup language.  The toolchain that everybody else uses is
based on XML DocBook.  It has been proposed that we abandon SGML and
jump to XML, but the idea has been shot down.  And it's possible to
convert our SGML to XML automatically and process it with the newer
toolchain.

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

---

From: Michael Glaesemann <[email-masked]>
Date: Tue, 15 Nov 2005 20:42:18 +0900

> convert our SGML to XML automatically and process it with the newer

It's my understanding that it hasn't been shot down as much as no one  
has shown that it will serve our needs. IIRC, there are two issues:

> Marked sections: SGML DocBook (which is currently used) supports  
> parameter entities to be used to include or exclude certain  
> sections of material depending on the desired output. Profiling in  
> XML DocBook may be able to accomplish the same task.
>
> XML DocBook toolchain: making sure the tools to produce the  
> documentation in its myriad forms (e.g., html, manpages, PDF) works.

(Just for history repeating itself, this was brought up Aug 2004 as  
well :) )

I don't think anyone's standing in the way. It's just that no one's  
shown that the XML toolchain can do the work for us.

Michael Glaesemann
grzm myrealbox com

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 15 Nov 2005 12:53:00 +0100

> convert our SGML to XML automatically and process it with the newer

Oh, what is this stable and mature DocBook XML to print output conversion tool 
that you seem to be referring to?

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 15 Nov 2005 12:54:49 +0100

> have bookmarks, but still, why is this functionality not more mainstream.

I don't understand how you get from "ancient Acrobat can't display large PDF 
file" to "SGML toolchain is unreliable".

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 15 Nov 2005 09:04:04 -0500 (EST)

> convert our SGML to XML automatically and process it with the newer

OK, that makes sense.  We went from LaTeX to SGML long ago with the idea
that we could easily generate any output format, but that promise has
never been fully realized.

Could the SGML be automatically converted to XML during the print
process and then converted to PDF?

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 15 Nov 2005 09:43:24 -0500 (EST)

> file" to "SGML toolchain is unreliable".

Well, historically we have had trouble generating PDF (particuarly
bookmarks), and it took _days_ to generate the output, which certainly
seems strange.

In fact, this is the first verion that has bookmarks, and that is 1/2
the value of a PDF file for me, so I see this release as a great leap
forward for us.  What I do not understand is why it has taken >5 years
for this to happen.

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 15 Nov 2005 16:08:08 +0100

> process and then converted to PDF?

Certainly.

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 15 Nov 2005 12:30:12 -0300

> that you seem to be referring to?

I'm not saying there's any -- I'm just saying nobody else uses SGML.

That said, I just looked at a Gnome book that is published as PDF and
written using XML DocBook, and they seem to use "docbook2pdf" which in
turns appears to be this:

http://sourceware.org/docbook-tools/

One drawback that I can see in that book is that the HTML pages do not
have the nice names our current docs have.  Not sure if that's an
inherent property of the XML tools.

That said, I don't have much interest in messing with all this.
Personally I'm pretty happy using the HTML docs (I even read the SGML
directly at times.)

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.