Re: [DOCS] [HACKERS] Contrib modules documentation online
Andrew Dunstan a écrit : > > > Albert Cervera i Areny wrote: >>> I'm very strongly in favor of having this documentation. However, I >>> think >>> it might make sense to put "Contrib Modules" as a section under either >>> "Reference" or "Appendices". Also, I don't think it's necessary to make >>> each command option a separate subchapter, but I can see how that >>> would be >>> hard to avoid in an automated system. >>> >> >> It's not an automated system, README files have different structures >> so it's all manual work. That's why I asked how you think it should be >> organized. Anyone else thinks we should put it in Reference or >> Appendixes? >> > > I would far rather have a new top level heading. Something like > "Standard Modules and Tools". (Please avoid the use of the word > "contrib"). If not, than as a sub-chapter of "References". I don't think > it belongs in the Appendixes. > Appendixes or References are fine to me but not on a top level heading. References would certainly be my (light) preference. If you can find a way to keep each one of them on a single page, it would be best. Having one page for the installation procedure only (see for example this page http://www.nan-tic.com/ftp/pgdoc/x76728.html) is a little too much. Anyways, great work, Albert. Thanks. Regards. -- Guillaume. ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] [HACKERS] Contrib modules documentation online
Am Mittwoch, 29. August 2007 20:18 schrieb Neil Conway: > I wonder if it would be possible to keep the master version of the > contrib docs as SGML, and generate plaintext READMEs from it during the > documentation build. Using asciidoc you could do it the other way around. -- Peter Eisentraut http://developer.postgresql.org/~petere/ ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] [HACKERS] Contrib modules documentation online
Am Mittwoch, 29. August 2007 20:27 schrieb Andrew Dunstan: > Also, let's recall what has previously been discussed for contrib, > namely that we break it out into standard modules But that would also mean that the documentation system is somewhat modularized. That is, if I deinstall some module, it disappears from the documentation. And if I install a module from some other place, its documentation would appear in the same place where the other modules already show up. I haven't seen the inside of the current proposal, but if it just copies the SGML-converted documentation into the documentation directory with everything else, it doesn't quite accomplish that. -- Peter Eisentraut http://developer.postgresql.org/~petere/ ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] [HACKERS] Contrib modules documentation online
Peter Eisentraut wrote: Am Mittwoch, 29. August 2007 20:27 schrieb Andrew Dunstan: Also, let's recall what has previously been discussed for contrib, namely that we break it out into standard modules But that would also mean that the documentation system is somewhat modularized. What? No it doesn't. You have missed the key word in the sentence above: "standard". The idea is that the docs will describe the *standard* modules, i.e. those that ship with the PostgreSQL core distribution (because they are currently in contrib). If you want to design a pluggable documentation system then go for it, but it's not required by what I understand is the consensus plan for contrib. cheers andrew ---(end of broadcast)--- TIP 1: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
Re: [DOCS] [HACKERS] Contrib modules documentation online
Andrew Dunstan <[EMAIL PROTECTED]> writes: > If you want to design a pluggable documentation system then go for it, > but it's not required by what I understand is the consensus plan for > contrib. I thought a large part of the desire was to improve the visibility of the contrib docs, ie, put the docs under the noses of people who have *not* installed or even heard of the modules. So "it's not in the docs unless you installed it" seems counter to the point. regards, tom lane ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] [HACKERS] Contrib modules documentation online
Am Donnerstag, 30. August 2007 15:13 schrieb Andrew Dunstan:
> What? No it doesn't. You have missed the key word in the sentence above:
> "standard". The idea is that the docs will describe the *standard*
> modules, i.e. those that ship with the PostgreSQL core distribution
> (because they are currently in contrib).
>
> If you want to design a pluggable documentation system then go for it,
> but it's not required by what I understand is the consensus plan for
> contrib.
That brings up additional questions such as what is standard and whose
consensus. You initially referred to Perl, and I note that Perl modules
shipped with the main Perl package ("standard"?) and those that are not
provide access to their facilities in identical ways. That's as far as I can
read your mind anyway. ;-)
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
---(end of broadcast)---
TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] [HACKERS] Contrib modules documentation online
Am Donnerstag, 30. August 2007 15:26 schrieb Tom Lane: > I thought a large part of the desire was to improve the visibility of > the contrib docs, ie, put the docs under the noses of people who have > *not* installed or even heard of the modules. So "it's not in the docs > unless you installed it" seems counter to the point. I thought the point was to make the extensibility features of PostgreSQL more usable so people would be more inclined to use them. The assumption being that the problem is not finding things but the hesitation against using "unofficial" things. Moving everything to the main blob of things seems to go against that idea. So perhaps some market research is required to clarify the actual requirements and goals. -- Peter Eisentraut http://developer.postgresql.org/~petere/ ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
Re: [DOCS] [HACKERS] Contrib modules documentation online
Peter Eisentraut wrote: Am Donnerstag, 30. August 2007 15:26 schrieb Tom Lane: I thought a large part of the desire was to improve the visibility of the contrib docs, ie, put the docs under the noses of people who have *not* installed or even heard of the modules. So "it's not in the docs unless you installed it" seems counter to the point. I thought the point was to make the extensibility features of PostgreSQL more usable so people would be more inclined to use them. The assumption being that the problem is not finding things but the hesitation against using "unofficial" things. Moving everything to the main blob of things seems to go against that idea. So perhaps some market research is required to clarify the actual requirements and goals. The idea that seemed to gain traction last time this was discussed was to treat the contrib modules as standard, included in the core distribution as examples of how modules work, and as modules that have moderately wide use (not sure how true that is of all of them, but I don't see any great point in pushing them out.) Quite apart from anything else, keeping them part of the main distribution helps us to validate the module process via buildfarm etc. So this isn't just "moving everything to the main blob of things". If you want to pay for market research then feel free ;-) cheers andrew ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
[DOCS] Why does SGML use zone=?
I see many places in the SGML docs that we do: user current In almost every case the "zone" tag has the same name as the section it is in. However, there are other cases that have no "zone" tag and they default to the section they are in. What I am wondering is why we specify "zone" at all? Why not just let it default to the section name? Seems that would make writing and editing easier. The SGML docs at: http://www.oasis-open.org/docbook/documentation/reference/html/indexterm.html Say: Zone The use of Zone implies a spanning index entry. Zone holds the IDs of the elements to which it applies. The IndexTerm applies to the contents of the entire element(s) to which it points. If Zone is used, the phyiscal placement of the IndexTerm in the flow of the document is irrelavant. It seems "zone" is for cases where you want to specify index terms outside of the main document flow, but we don't do that. -- Bruce Momjian <[EMAIL PROTECTED]> http://momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + ---(end of broadcast)--- TIP 1: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
Re: [DOCS] Why does SGML use zone=?
Bruce Momjian wrote: > What I am wondering is why we specify "zone" at all? It means that the entire section is relevant to the index term. Otherwise it would mean that only the narrow area around the index term is relevant. In printed renditions, that would be the difference between saying foo, 87 and foo, 86-90 in the index. -- Peter Eisentraut http://developer.postgresql.org/~petere/ ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] Why does SGML use zone=?
Peter Eisentraut wrote: > Bruce Momjian wrote: > > What I am wondering is why we specify "zone" at all? > > It means that the entire section is relevant to the index term. > Otherwise it would mean that only the narrow area around the index term > is relevant. In printed renditions, that would be the difference > between saying > > foo, 87 > > and > > foo, 86-90 > > in the index. Ah, interesting. Thanks. -- Bruce Momjian <[EMAIL PROTECTED]> http://momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
[DOCS] Problem with index building
Can someone tell me what is the matter with this index entry in textsearch.sgml? GiST I have commented out the entry in CVS so indexes can be built but with it enabled it generates an error in bookindex.sgml: openjade:bookindex.sgml:2731:0:E: character data is not allowed here openjade:bookindex.sgml:2732:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag openjade:bookindex.sgml:2744:0:E: character data is not allowed here openjade:bookindex.sgml:2745:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag -- Bruce Momjian <[EMAIL PROTECTED]> http://momjian.us EnterpriseDB http://www.enterprisedb.com + If your life is a hard drive, Christ can be your backup. + ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
