Horton

Thread

  1. Uppercase SGML entity declarations

    Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> — 2011-04-04T09:11:37Z

    Hi,

   I have made very small modifications to a few files in the 
documentation directory, which involve SGML entity declarations. 
Currently they are all written lowercase, the patch makes them 
uppercase. This won't affect SGML parsing, as SGML is case insensitive - 
even though it is a good practice to write SGML declarations in uppercase.

    An example is:

<!entity abort              system "abort.sgml">

    written

<!ENTITY abort              SYSTEM "abort.sgml">


    This patch makes also every single directive of them XML compliant.

    The list of files that have been changed is:

doc/src/sgml/Makefile
doc/src/sgml/filelist.sgml
doc/src/sgml/postgres.sgml
doc/src/sgml/ref/allfiles.sgml
doc/src/sgml/standalone-install.sgml

    Thanks.

Cheers,
Gabriele

-- 
  Gabriele Bartolini - 2ndQuadrant Italia
  PostgreSQL Training, Services and Support
  gabriele.bartolini@2ndQuadrant.it | www.2ndQuadrant.it

  2. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-04T14:57:55Z

    On Mon, Apr 4, 2011 at 5:11 AM, Gabriele Bartolini
<gabriele.bartolini@2ndquadrant.it> wrote:
>  I have made very small modifications to a few files in the documentation
> directory, which involve SGML entity declarations. Currently they are all
> written lowercase, the patch makes them uppercase. This won't affect SGML
> parsing, as SGML is case insensitive - even though it is a good practice to
> write SGML declarations in uppercase.
>
>   An example is:
>
> <!entity abort              system "abort.sgml">
>
>   written
>
> <!ENTITY abort              SYSTEM "abort.sgml">
>
>
>   This patch makes also every single directive of them XML compliant.

Forgive me for asking what may seem like a stupid question, but what's
not XML compliant about them now, and why do we care?  The text is
only ever going to parse as SGML (not XML) so I guess I don't see why
it matters.  I don't really object to the proposed patch but I guess
I'm not sure what it accomplishes.

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

  3. Re: [HACKERS] Uppercase SGML entity declarations

    Tom Lane <tgl@sss.pgh.pa.us> — 2011-04-04T15:15:30Z

    Gabriele Bartolini <gabriele.bartolini@2ndQuadrant.it> writes:
>    I have made very small modifications to a few files in the 
> documentation directory, which involve SGML entity declarations. 
> Currently they are all written lowercase, the patch makes them 
> uppercase. This won't affect SGML parsing, as SGML is case insensitive - 
> even though it is a good practice to write SGML declarations in uppercase.

What's the point of this exactly?  I don't think we'd accept changing
every tag in the documentation to upper case, so why should we change
a small subset of them?

			regards, tom lane

  4. Re: [HACKERS] Uppercase SGML entity declarations

    Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> — 2011-04-04T16:23:57Z

    Hi Robert (and Tom),

Il 04/04/11 16:57, Robert Haas ha scritto:
> Forgive me for asking what may seem like a stupid question, but what's
> not XML compliant about them now, and why do we care?  The text is
> only ever going to parse as SGML (not XML) so I guess I don't see why
> it matters.  I don't really object to the proposed patch but I guess
> I'm not sure what it accomplishes.

My apologies, I should have explained it better and at once.

Here is the context. I am coordinating the Italian translation of the 
documentation and we are about to create a branch for 9.1. The 
publishing mechanism is based on DocBook XML (as well as the French 
one), as we are facing extreme difficulties publishing using SGML tools.

My intention was to start and change some simple documentation files in 
order to make our conversion process from SGML to XML smoother, while 
keeping the SGML compatibility of the original documentation intact. 
Also I was trying to make the ENTITY declarations consistent throughout 
the documents.

I hope I gave you a more clear explanation.

Cheers,
Gabriele

-- 
  Gabriele Bartolini - 2ndQuadrant Italia
  PostgreSQL Training, Services and Support
  gabriele.bartolini@2ndQuadrant.it | www.2ndQuadrant.it

  5. Re: [HACKERS] Uppercase SGML entity declarations

    Tom Lane <tgl@sss.pgh.pa.us> — 2011-04-04T16:37:24Z

    Gabriele Bartolini <gabriele.bartolini@2ndQuadrant.it> writes:
> My intention was to start and change some simple documentation files in 
> order to make our conversion process from SGML to XML smoother, while 
> keeping the SGML compatibility of the original documentation intact. 

AFAIK, the main stumbling block for that is that XML doesn't allow
abbreviated close tags (ie, <foo>whatever</>).  Which is something that
we are not likely to give up.  So I'm not sure of the point of changing
something as trivial as entity declaration casing.  You're going to end
up having to fork the documentation anyway, or at least feed it through
an SGML to XML converter.  So why not fix the entity casing then?

			regards, tom lane

  6. Re: [HACKERS] Uppercase SGML entity declarations

    Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> — 2011-04-04T17:18:21Z

    Il 04/04/11 18:37, Tom Lane ha scritto:
> AFAIK, the main stumbling block for that is that XML doesn't allow
> abbreviated close tags (ie,<foo>whatever</>).  Which is something that
> we are not likely to give up.  So I'm not sure of the point of changing
> something as trivial as entity declaration casing.  You're going to end
> up having to fork the documentation anyway, or at least feed it through
> an SGML to XML converter.  So why not fix the entity casing then?
We do it. However, given that the files that have been changed are 
edited very rarely, the scope of the patch is limited and compatibility 
with SGML is kept, I thought changing this at source level would be 
something to propose and submit.

Ciao,
Gabriele

-- 
  Gabriele Bartolini - 2ndQuadrant Italia
  PostgreSQL Training, Services and Support
  gabriele.bartolini@2ndQuadrant.it | www.2ndQuadrant.it

  7. Re: [HACKERS] Uppercase SGML entity declarations

    Susanne Ebrecht <susanne@2ndquadrant.com> — 2011-04-04T17:26:45Z

    On 04.04.2011 18:37, Tom Lane wrote:
> AFAIK, the main stumbling block for that is that XML doesn't allow
> abbreviated close tags (ie,<foo>whatever</>).  Which is something that
> we are not likely to give up.  So I'm not sure of the point of changing
> something as trivial as entity declaration casing.  You're going to end
> up having to fork the documentation anyway, or at least feed it through
> an SGML to XML converter.  So why not fix the entity casing then?

Tom,

Honestly, for German I don't mind yet if it is XML or SGML. XML might
be better in future for maintenance tools.

Anyway, I figured out there is another argument for XML:

My information is that DocBook 5.0 won't support SGML anymore.

Which means - sooner or later a reaction is needed.

Susanne
P.S.:
Btw. I change <foo>whatever</> into <foo>whatever</foo> when it
is in the parts which I am translating because my emacs indent don't 
like </>.

-- 
Susanne Ebrecht - 2ndQuadrant
PostgreSQL Development, 24x7 Support, Training and Services
www.2ndQuadrant.com

  8. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-04T17:28:47Z

    On Mon, Apr 4, 2011 at 1:26 PM, Susanne Ebrecht <susanne@2ndquadrant.com> wrote:
> My information is that DocBook 5.0 won't support SGML anymore.
>
> Which means - sooner or later a reaction is needed.

Ouch.

Even if that doesn't turn out to be the case, this is pretty harmless,
so maybe we should just apply it and move on.

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

  9. Re: [HACKERS] Uppercase SGML entity declarations

    Tom Lane <tgl@sss.pgh.pa.us> — 2011-04-04T18:42:07Z

    Robert Haas <robertmhaas@gmail.com> writes:
> Even if that doesn't turn out to be the case, this is pretty harmless,
> so maybe we should just apply it and move on.

I have no great objection to the patch as such; just wondering what the
roadmap is.

			regards, tom lane

  10. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-04T18:48:49Z

    On Mon, Apr 4, 2011 at 2:42 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Robert Haas <robertmhaas@gmail.com> writes:
>> Even if that doesn't turn out to be the case, this is pretty harmless,
>> so maybe we should just apply it and move on.
>
> I have no great objection to the patch as such; just wondering what the
> roadmap is.

Me, too.

On a practical level, if we're going to do this, shouldn't we also do
!entity -> !ENTITY in Solution.pm?

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

  11. Re: [HACKERS] Uppercase SGML entity declarations

    Christopher Browne <cbbrowne@gmail.com> — 2011-04-04T18:50:13Z

    On Mon, Apr 4, 2011 at 1:26 PM, Susanne Ebrecht <susanne@2ndquadrant.com> wrote:
> Anyway, I figured out there is another argument for XML:
>
> My information is that DocBook 5.0 won't support SGML anymore.
>
> Which means - sooner or later a reaction is needed.

Yes, indeed.

I don't think that during the 9.1 alpha phase is the right time to
think about this, but this certainly seems appropriate to consider as
a 9.2 "ToDo" item.

There are arguments as to why to switch to version 5, which is,
indeed, XML-only.
http://www.docbook.org/tdg5/en/html/ch01.html#introduction-why-to-switch

They argue that version 5
- Is what will get fixes.  Which may not matter to us, as I don't
think we have been getting bitten by "horrible DocBook problems."
- Has new functionality.  Which may not matter, as we're doubtless not
using all of the functionality of elder versions of DocBook either.
- Is more extensible.  Which I imagine doesn't matter, as we weren't
extending earlier versions.
- Is easier to customize.  Almost anything would be better than
DSSSL... (http://www.biglist.com/lists/dssslist/archives/200005/msg00120.html
is my little contribution that apparently got used a fair bit by
people)

There is also a possible counter-position to be taken, namely that the
existing tooling works, is mature, and isn't too likely to disappear
in any sort of short term.

In any case, the ToDo shouldn't be about how to convert the SGML to
XML - that's merely one of the tasks.  There is already a ToDo item,
which points here:
<http://archives.postgresql.org/pgsql-docs/2006-12/msg00152.php>

It needs to cover making sure such things as that:
a) The output forms presently used (e.g. - PDF, man pages, perhaps
.chm/.rtf) continue to be available
b) We can clearly document what new toolchain is needed to process the
various output forms, and validate that it's sufficiently free,
sufficiently robust, sufficiently portable, and so forth.
c) Integrating the toolchain into the Postgres build process.

This represents a fair bit of work, so it's a bit of a presumption
that it's a wise move to do this in 9.2.  I don't think the benefits
that the DocBook folk present for moving to v5 are necessarily
compelling to the Postgres community.

BTW, I wear most of the "DocBook hat" for the Slony project, and I
don't see it being valuable to us ("Slony project") to migrate to v5.
It would require quite a bit of work, and I don't see any of the
claimed benefits being helpful to the "Slony us."
-- 
http://linuxfinances.info/info/linuxdistributions.html

  12. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-04T19:02:39Z

    On Mon, Apr 4, 2011 at 2:50 PM, Christopher Browne <cbbrowne@gmail.com> wrote:
> On Mon, Apr 4, 2011 at 1:26 PM, Susanne Ebrecht <susanne@2ndquadrant.com> wrote:
>> Anyway, I figured out there is another argument for XML:
>>
>> My information is that DocBook 5.0 won't support SGML anymore.
>>
>> Which means - sooner or later a reaction is needed.
>
> Yes, indeed.
>
> I don't think that during the 9.1 alpha phase is the right time to
> think about this, but this certainly seems appropriate to consider as
> a 9.2 "ToDo" item.
>
> There are arguments as to why to switch to version 5, which is,
> indeed, XML-only.
> http://www.docbook.org/tdg5/en/html/ch01.html#introduction-why-to-switch

AFAICT, the biggest problem with our existing toolchain is that it's
hard for some people to get it working.  In theory, we have
documentation that explains this:

http://www.postgresql.org/docs/current/static/docguide-toolsets.html

However, in contrast to the vast majority of our documentation, it stinks.

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

  13. Re: [HACKERS] Uppercase SGML entity declarations

    Tom Lane <tgl@sss.pgh.pa.us> — 2011-04-04T19:08:20Z

    Robert Haas <robertmhaas@gmail.com> writes:
> On Mon, Apr 4, 2011 at 2:50 PM, Christopher Browne <cbbrowne@gmail.com> wrote:
>> There are arguments as to why to switch to version 5, which is,
>> indeed, XML-only.
>> http://www.docbook.org/tdg5/en/html/ch01.html#introduction-why-to-switch

> AFAICT, the biggest problem with our existing toolchain is that it's
> hard for some people to get it working.

Indeed.  One thing I'd like to know is whether docbook v5 is any more
portable/easier to install.

			regards, tom lane

  14. Re: [HACKERS] Uppercase SGML entity declarations

    Dave Page <dpage@pgadmin.org> — 2011-04-04T19:14:36Z

    On 4/4/11, Robert Haas <robertmhaas@gmail.com> wrote:
> On Mon, Apr 4, 2011 at 2:50 PM, Christopher Browne <cbbrowne@gmail.com>
> wrote:
>> On Mon, Apr 4, 2011 at 1:26 PM, Susanne Ebrecht <susanne@2ndquadrant.com>
>> wrote:
>>> Anyway, I figured out there is another argument for XML:
>>>
>>> My information is that DocBook 5.0 won't support SGML anymore.
>>>
>>> Which means - sooner or later a reaction is needed.
>>
>> Yes, indeed.
>>
>> I don't think that during the 9.1 alpha phase is the right time to
>> think about this, but this certainly seems appropriate to consider as
>> a 9.2 "ToDo" item.
>>
>> There are arguments as to why to switch to version 5, which is,
>> indeed, XML-only.
>> http://www.docbook.org/tdg5/en/html/ch01.html#introduction-why-to-switch
>
> AFAICT, the biggest problem with our existing toolchain is that it's
> hard for some people to get it working.  In theory, we have
> documentation that explains this:
>
> http://www.postgresql.org/docs/current/static/docguide-toolsets.html
>
> However, in contrast to the vast majority of our documentation, it stinks.
>

I've certainly wasted non-trivial amounts of time trying to get it to
work on some platforms. I'd be *very* glad to see us using a
simplified toolchain if possible.

Another point to note is that whilst it will still be possible to
install older versions of docbook for a while, presumably that'll
become more and more of a pain, as distros update to 5.x, requiring
users to start building manually, and having to deal with parallel
installations of two versions.


-- 
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

  15. Re: [HACKERS] Uppercase SGML entity declarations

    Susanne Ebrecht <susanne@2ndquadrant.com> — 2011-04-04T19:20:57Z

    On 04.04.2011 21:08, Tom Lane wrote:
> Indeed.  One thing I'd like to know is whether docbook v5 is any more
> portable/easier to install

Unfortunately, as far as I know - there isn't a huge difference.

regards,

Susanne

-- 
Susanne Ebrecht - 2ndQuadrant
PostgreSQL Development, 24x7 Support, Training and Services
www.2ndQuadrant.com

  16. Re: [HACKERS] Uppercase SGML entity declarations

    Alvaro Herrera <alvherre@commandprompt.com> — 2011-04-04T20:15:46Z

    Excerpts from Gabriele Bartolini's message of lun abr 04 13:18:21 -0400 2011:
> Il 04/04/11 18:37, Tom Lane ha scritto:
> > AFAIK, the main stumbling block for that is that XML doesn't allow
> > abbreviated close tags (ie,<foo>whatever</>).  Which is something that
> > we are not likely to give up.  So I'm not sure of the point of changing
> > something as trivial as entity declaration casing.  You're going to end
> > up having to fork the documentation anyway, or at least feed it through
> > an SGML to XML converter.  So why not fix the entity casing then?
> We do it. However, given that the files that have been changed are 
> edited very rarely, the scope of the patch is limited and compatibility 
> with SGML is kept, I thought changing this at source level would be 
> something to propose and submit.

Given the lack of objections, I have pushed this patch.  Thanks.

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

  17. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-04T20:26:07Z

    On Mon, Apr 4, 2011 at 4:15 PM, Alvaro Herrera
<alvherre@commandprompt.com> wrote:
> Excerpts from Gabriele Bartolini's message of lun abr 04 13:18:21 -0400 2011:
>> Il 04/04/11 18:37, Tom Lane ha scritto:
>> > AFAIK, the main stumbling block for that is that XML doesn't allow
>> > abbreviated close tags (ie,<foo>whatever</>).  Which is something that
>> > we are not likely to give up.  So I'm not sure of the point of changing
>> > something as trivial as entity declaration casing.  You're going to end
>> > up having to fork the documentation anyway, or at least feed it through
>> > an SGML to XML converter.  So why not fix the entity casing then?
>> We do it. However, given that the files that have been changed are
>> edited very rarely, the scope of the patch is limited and compatibility
>> with SGML is kept, I thought changing this at source level would be
>> something to propose and submit.
>
> Given the lack of objections, I have pushed this patch.  Thanks.

I think you still need to update Solution.pm to match.

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

  18. Re: [HACKERS] Uppercase SGML entity declarations

    Alvaro Herrera <alvherre@commandprompt.com> — 2011-04-04T20:44:57Z

    Excerpts from Robert Haas's message of lun abr 04 16:26:07 -0400 2011:
> On Mon, Apr 4, 2011 at 4:15 PM, Alvaro Herrera
> <alvherre@commandprompt.com> wrote:
> > Excerpts from Gabriele Bartolini's message of lun abr 04 13:18:21 -0400 2011:
> >> Il 04/04/11 18:37, Tom Lane ha scritto:
> >> > AFAIK, the main stumbling block for that is that XML doesn't allow
> >> > abbreviated close tags (ie,<foo>whatever</>).  Which is something that
> >> > we are not likely to give up.  So I'm not sure of the point of changing
> >> > something as trivial as entity declaration casing.  You're going to end
> >> > up having to fork the documentation anyway, or at least feed it through
> >> > an SGML to XML converter.  So why not fix the entity casing then?
> >> We do it. However, given that the files that have been changed are
> >> edited very rarely, the scope of the patch is limited and compatibility
> >> with SGML is kept, I thought changing this at source level would be
> >> something to propose and submit.
> >
> > Given the lack of objections, I have pushed this patch.  Thanks.
> 
> I think you still need to update Solution.pm to match.

Oops, sorry, done.

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

  19. Re: [HACKERS] Uppercase SGML entity declarations

    Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it> — 2011-04-04T20:47:26Z

    Il 04/04/11 22:26, Robert Haas ha scritto:
> I think you still need to update Solution.pm to match.
>
Here it is, including change of 3 'Id' attributes (I made them lowercase).

Thanks,
Gabriele

-- 
  Gabriele Bartolini - 2ndQuadrant Italia
  PostgreSQL Training, Services and Support
  gabriele.bartolini@2ndQuadrant.it | www.2ndQuadrant.it

  20. Re: [HACKERS] Uppercase SGML entity declarations

    Peter Eisentraut <peter_e@gmx.net> — 2011-04-05T18:18:04Z

    On mån, 2011-04-04 at 15:02 -0400, Robert Haas wrote:
> AFAICT, the biggest problem with our existing toolchain is that it's
> hard for some people to get it working.  In theory, we have
> documentation that explains this:
> 
> http://www.postgresql.org/docs/current/static/docguide-toolsets.html
> 
> However, in contrast to the vast majority of our documentation, it
> stinks.

Umm, if you look under "Debian Packages", there is a one-line command to
execute, which, as far as I can tell, is pretty much guaranteed to get
you going.  If that doesn't apply to the OS you are working, then either

a) You haven't contributed better installation documentation, or

b) The makers of your OS haven't bothered to package it properly.

No other toolchain will make that principle easier.

  21. Re: [HACKERS] Uppercase SGML entity declarations

    Peter Eisentraut <peter_e@gmx.net> — 2011-04-05T18:26:42Z

    On mån, 2011-04-04 at 15:08 -0400, Tom Lane wrote:
> One thing I'd like to know is whether docbook v5 is any more
> portable/easier to install.

I don't see why.  It's just a newer version of the same thing.

If you change the sources to XML and switch to the XSL toolchain, you
don't have to install the DTD or other schema as such, which would
simplify the installation.  But that could already be had with DocBook
4.

The drawback of not having the schema is that you can't verify the
correct structure of the document, and the XSLT processor will just
produce garbage.

  22. Re: [HACKERS] Uppercase SGML entity declarations

    Alvaro Herrera <alvherre@commandprompt.com> — 2011-04-05T18:34:54Z

    Excerpts from Gabriele Bartolini's message of lun abr 04 16:47:26 -0400 2011:
> Il 04/04/11 22:26, Robert Haas ha scritto:
> > I think you still need to update Solution.pm to match.
> >
> Here it is, including change of 3 'Id' attributes (I made them lowercase).

Pushed this one also.


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

  23. Re: [HACKERS] Uppercase SGML entity declarations

    Peter Eisentraut <peter_e@gmx.net> — 2011-04-05T18:48:55Z

    On mån, 2011-04-04 at 19:26 +0200, Susanne Ebrecht wrote:
> Honestly, for German I don't mind yet if it is XML or SGML. XML might
> be better in future for maintenance tools.
> 
> Anyway, I figured out there is another argument for XML:
> 
> My information is that DocBook 5.0 won't support SGML anymore.
> 
> Which means - sooner or later a reaction is needed.

In the spirit of CVS_to_Git, I have started this page now:

http://wiki.postgresql.org/wiki/Switching_PostgreSQL_documentation_from_SGML_to_XML

Edit away.

  24. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-05T18:55:00Z

    On Tue, Apr 5, 2011 at 2:18 PM, Peter Eisentraut <peter_e@gmx.net> wrote:
> On mån, 2011-04-04 at 15:02 -0400, Robert Haas wrote:
>> AFAICT, the biggest problem with our existing toolchain is that it's
>> hard for some people to get it working.  In theory, we have
>> documentation that explains this:
>>
>> http://www.postgresql.org/docs/current/static/docguide-toolsets.html
>>
>> However, in contrast to the vast majority of our documentation, it
>> stinks.
>
> Umm, if you look under "Debian Packages", there is a one-line command to
> execute, which, as far as I can tell, is pretty much guaranteed to get
> you going.  If that doesn't apply to the OS you are working, then either
>
> a) You haven't contributed better installation documentation, or
>
> b) The makers of your OS haven't bothered to package it properly.
>
> No other toolchain will make that principle easier.

I don't know whether some other toolchain would be easier or not.  I
believe that the directions for RPM installation aren't completely
up-to-date; I think you need docbook-style-dsssl at least on newer
Fedoras, and there isn't any stylesheet package on such systems.
There are also no directions for MacOS X at all.  My biggest gripe is
that when things fail, it's often not obvious what the problem is.
I've had failures due to missing packages (but the package that's
missing is far from obvious) and I've also had failures, I believe,
from not being connected to the Internet, which is surprising because
it's not at all obvious that building the docs should require an
Internet connection.  At least if you are missing something like zlib
it says "checking for zlib... not found".  And while it may be that
you have zlib and are missing zlib-devel, it at least gets you pointed
in the right direction, whereas the docbook stuff tends to spew out 50
pages of error messages that I at least don't find terribly intuitive.

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

  25. Re: [HACKERS] Uppercase SGML entity declarations

    Dave Page <dpage@pgadmin.org> — 2011-04-05T18:59:47Z

    On Tue, Apr 5, 2011 at 7:55 PM, Robert Haas <robertmhaas@gmail.com> wrote:
>
> I've also had failures, I believe,
> from not being connected to the Internet, which is surprising because
> it's not at all obvious that building the docs should require an
> Internet connection.

Oh, I've run into that and had it cause delays when I've been building
release installers before now (sourceforge were having issues iirc) -
not good.


-- 
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

  26. Re: [HACKERS] Uppercase SGML entity declarations

    Peter Eisentraut <peter_e@gmx.net> — 2011-04-05T20:59:36Z

    On tis, 2011-04-05 at 14:55 -0400, Robert Haas wrote:
> and I've also had failures, I believe,
> from not being connected to the Internet, which is surprising because
> it's not at all obvious that building the docs should require an
> Internet connection.

I understand this problem, but just to clarify, this is supposed to
help, because then you don't need to install anything, as whatever is
necessary will be downloaded automatically.  This is a feature of the
XSLT processor.  In the case of xsltproc, it can be turned off with the
--nonet option.

On the other hand, if you have a proper local installation, then it
should map the Internet URIs to the local installation. -- "should"

  27. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-05T22:39:29Z

    On Tue, Apr 5, 2011 at 4:59 PM, Peter Eisentraut <peter_e@gmx.net> wrote:
> On tis, 2011-04-05 at 14:55 -0400, Robert Haas wrote:
>> and I've also had failures, I believe,
>> from not being connected to the Internet, which is surprising because
>> it's not at all obvious that building the docs should require an
>> Internet connection.
>
> I understand this problem, but just to clarify, this is supposed to
> help, because then you don't need to install anything, as whatever is
> necessary will be downloaded automatically.  This is a feature of the
> XSLT processor.  In the case of xsltproc, it can be turned off with the
> --nonet option.
>
> On the other hand, if you have a proper local installation, then it
> should map the Internet URIs to the local installation. -- "should"

Well, that explains why it worked without a network connection on some
systems but not others.  I don't really object to the toolchain we're
using; it works OK for me, and switching would be a pain in the neck.
But I find it's not as easy to use as some things.

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

  28. Re: [HACKERS] Uppercase SGML entity declarations

    Josh Kupershmidt <schmiddy@gmail.com> — 2011-04-06T01:55:31Z

    On Mon, Apr 4, 2011 at 3:02 PM, Robert Haas <robertmhaas@gmail.com> wrote:
> In theory, we have
> documentation that explains this:
>
> http://www.postgresql.org/docs/current/static/docguide-toolsets.html

While we're on the subject..

Attached is a patch against that page suggesting using openjade 1.3,
not 1.4devel as part of the doc build toolset. Source of this
recommendation:
<http://old.nabble.com/openjade-segfault-on-Postgres-PDF%3A-flow-object-not-accepted-by-port-to30764268.html>

I just double checked, and with the latest openjade package (1.4devel)
on Ubuntu 10.10, I still see the same segfault; downgrading to package
"openjade1.3" allows me to make postgres-A4.pdf successfully.

Josh

  29. Re: [HACKERS] Uppercase SGML entity declarations

    Robert Haas <robertmhaas@gmail.com> — 2011-04-14T18:37:26Z

    On Tue, Apr 5, 2011 at 6:55 PM, Josh Kupershmidt <schmiddy@gmail.com> wrote:
> On Mon, Apr 4, 2011 at 3:02 PM, Robert Haas <robertmhaas@gmail.com> wrote:
>> In theory, we have
>> documentation that explains this:
>>
>> http://www.postgresql.org/docs/current/static/docguide-toolsets.html
>
> While we're on the subject..
>
> Attached is a patch against that page suggesting using openjade 1.3,
> not 1.4devel as part of the doc build toolset. Source of this
> recommendation:
> <http://old.nabble.com/openjade-segfault-on-Postgres-PDF%3A-flow-object-not-accepted-by-port-to30764268.html>
>
> I just double checked, and with the latest openjade package (1.4devel)
> on Ubuntu 10.10, I still see the same segfault; downgrading to package
> "openjade1.3" allows me to make postgres-A4.pdf successfully.

OK, committed.

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