Placement of contrib modules in SGML documentation

Tom Lane wrote:

I am still desperately unhappy with the choice to put the contrib docs
where they were put. They are by no stretch of the imagination part of
the "SQL Language", and there is no defense for having inserted them
into the middle of the part, in front of substantially more widely
interesting information such as concurrency control.

I think we need to decide where they will go; they are easy to move.

Furthermore, labeling them "Standard Modules" is somebody's flight of
wishful thinking --- if they were installed by default, they'd deserve
such a title, but that's not happening any time soon.

That name needs adjustment too.

I think there's a case for putting these pages under Part V Server
Programming (though a few are not in fact server-side code), or under
Part VI Reference (ignoring the fact that most of the text isn't in a
uniform reference-page style ... though maybe we could plan to work
towards that) or under Appendixes (though I'm sure there are people
who will complain about that because their private agenda is to make
these things as prominent as possible). Or we could make them a new
top-level Part, probably just after Reference.

I think appendix is the right place myself.

As for the title, how about "Available Add-On Modules", or something
like that?

Yea, that is better. Someone didn't want "contrib" mentioned in the
title. The problem with "Available" is that it doesn't include
pgfoundry stuff which is _available_ too, just not shipped.

BTW, why are neither contrib/dblink nor contrib/spi included in the
conversion?

I see dblink:

http://momjian.us/main/writings/pgsql/sgml/dblink.html

I assume spi wasn't done because it is just examples of SPI usage.

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

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian <bruce@momjian.us> writes:

BTW, why are neither contrib/dblink nor contrib/spi included in the
conversion?

I see dblink:
http://momjian.us/main/writings/pgsql/sgml/dblink.html

Oh, in that case the question is why the contrib/db/doc/ files are
still there.

I assume spi wasn't done because it is just examples of SPI usage.

The .example files are fine, but what about the two README files?

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

BTW, why are neither contrib/dblink nor contrib/spi included in the
conversion?

I see dblink:
http://momjian.us/main/writings/pgsql/sgml/dblink.html

Oh, in that case the question is why the contrib/db/doc/ files are
still there.

Because I thought only READMEs were converted. Removed now.

I assume spi wasn't done because it is just examples of SPI usage.

The .example files are fine, but what about the two README files?

My guess is they were not converted because they are READMEs that
related to the examples. We can convert them if people want.

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

+ If your life is a hard drive, Christ can be your backup. +

A Diumenge 11 Novembre 2007, Tom Lane va escriure:

I think there's a case for putting these pages under Part V Server
Programming (though a few are not in fact server-side code), or under
Part VI Reference (ignoring the fact that most of the text isn't in a
uniform reference-page style ... though maybe we could plan to work
towards that) or under Appendixes (though I'm sure there are people
who will complain about that because their private agenda is to make
these things as prominent as possible). Or we could make them a new
top-level Part, probably just after Reference.

That's where I put them initialy AFAIR but somebody complained they should be
in the Reference. Maybe if we now agree that's not the appropiate place we
can move them to a new Part.

--
Albert Cervera i Areny
http://www.NaN-tic.com

Bruce Momjian wrote:

Tom Lane wrote:

I am still desperately unhappy with the choice to put the contrib docs
where they were put. They are by no stretch of the imagination part of
the "SQL Language", and there is no defense for having inserted them
into the middle of the part, in front of substantially more widely
interesting information such as concurrency control.

I think we need to decide where they will go; they are easy to move.

Furthermore, labeling them "Standard Modules" is somebody's flight of
wishful thinking --- if they were installed by default, they'd deserve
such a title, but that's not happening any time soon.

That name needs adjustment too.

How about "Additional Supplied Modules"?

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

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian <bruce@momjian.us> writes:

Tom Lane wrote:

I think there's a case for putting these pages under Part V Server
Programming (though a few are not in fact server-side code), or under
Part VI Reference (ignoring the fact that most of the text isn't in a
uniform reference-page style ... though maybe we could plan to work
towards that) or under Appendixes (though I'm sure there are people
who will complain about that because their private agenda is to make
these things as prominent as possible). Or we could make them a new
top-level Part, probably just after Reference.

I think appendix is the right place myself.

An argument in favor of that is that we've got External Projects as
an appendix too, and it seems to make sense to put contrib next door
to them.

I'll go with that for the moment, and 'Additional Supplied Modules'
as the title --- we can always change again later if there's a better
idea.

regards, tom lane