Thread: Placement of contrib modules in SGML documentation
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.
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.
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.
As for the title, how about "Available Add-On Modules", or something
like that?
BTW, why are neither contrib/dblink nor contrib/spi included in the
conversion?
regards, tom lane
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