Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-30 Thread Guillaume Lelarge
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.
!-- http://abs.traduc.org/
 http://lfs.traduc.org/
 http://docs.postgresqlfr.org/ --

---(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

2007-08-30 Thread Peter Eisentraut
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 2: Don't 'kill -9' the postmaster


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-30 Thread Peter Eisentraut
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 5: don't forget to increase your free space map settings


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-30 Thread Andrew Dunstan



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 3: Have you checked our extensive FAQ?

  http://www.postgresql.org/docs/faq


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-30 Thread Tom Lane
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 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

2007-08-30 Thread Peter Eisentraut
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 7: You can help support the PostgreSQL project by donating at

http://www.postgresql.org/about/donate


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-30 Thread Peter Eisentraut
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 6: explain analyze is your friend


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-30 Thread Andrew Dunstan



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 3: Have you checked our extensive FAQ?

  http://www.postgresql.org/docs/faq


Re: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Nikolay Samokhvalov
There is a problem with line feeds for contrib/xml2:
http://www.nan-tic.com/ftp/pgdoc/xml2.html

As for idea itself, I find it very useful (besides usability
improvements, it would help to promote Postgres advanced features).

On 8/29/07, Albert Cervera i Areny [EMAIL PROTECTED] wrote:
 I've been working on converting the current README files for all contrib
 modules into sgml and add it to the documentation. There are still some fixes
 to do but i'd like to have some feedback. Indeed, it wasn't agreed to have
 all if any of the modules together with the core documentation.

 You can see the docs on [1] in chapter VIII. If you think these could be a
 good addition, please fill free to comment on how you think sections should
 be organized to be consistent and easy to read.

 [1] http://www.nan-tic.com/ftp/pgdoc

 ---(end of broadcast)---
 TIP 4: Have you searched our list archives?

http://archives.postgresql.org



-- 
Best regards,
Nikolay

---(end of broadcast)---
TIP 2: Don't 'kill -9' the postmaster


Re: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Josh Berkus
Albert,

(crossed over to -docs, where it really belongs)

 I've been working on converting the current README files for all contrib
 modules into sgml and add it to the documentation. There are still some
 fixes to do but i'd like to have some feedback. Indeed, it wasn't agreed to
 have all if any of the modules together with the core documentation.

 You can see the docs on [1] in chapter VIII. If you think these could be a
 good addition, please fill free to comment on how you think sections should
 be organized to be consistent and easy to read.

 [1] http://www.nan-tic.com/ftp/pgdoc

Wow, this is really, really cool!  You're my hero.

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.  

Guys, would it be out of the question to do this in 8.3?  Please please?

If we go ahead with this, I'll commit to doing a contrib README cleanup so the 
doc system works better.

-- 
Josh Berkus
PostgreSQL @ Sun
San Francisco

---(end of broadcast)---
TIP 3: Have you checked our extensive FAQ?

   http://www.postgresql.org/docs/faq


Re: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Decibel!
On Wed, Aug 29, 2007 at 10:09:07AM -0700, Josh Berkus wrote:
 Albert,
 
 (crossed over to -docs, where it really belongs)
 
  I've been working on converting the current README files for all contrib
  modules into sgml and add it to the documentation. There are still some
  fixes to do but i'd like to have some feedback. Indeed, it wasn't agreed to
  have all if any of the modules together with the core documentation.
 
  You can see the docs on [1] in chapter VIII. If you think these could be a
  good addition, please fill free to comment on how you think sections should
  be organized to be consistent and easy to read.
 
  [1] http://www.nan-tic.com/ftp/pgdoc
 
 Wow, this is really, really cool!  You're my hero.
 
 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.  
 
 Guys, would it be out of the question to do this in 8.3?  Please please?
 
 If we go ahead with this, I'll commit to doing a contrib README cleanup so 
 the 
 doc system works better.

One question... would there still be a README in each contrib directory?
I think getting this stuff in the docs is great, but the README in the
source is also very valuable and I'd hate to lose it.
-- 
Decibel!, aka Jim Nasby[EMAIL PROTECTED]
EnterpriseDB  http://enterprisedb.com  512.569.9461 (cell)


pgpbJLvWh95Cg.pgp
Description: PGP signature


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-29 Thread Tom Lane
Josh Berkus [EMAIL PROTECTED] writes:
 If we go ahead with this, I'll commit to doing a contrib README
 cleanup so the doc system works better.

Why wouldn't we just remove the README files altogether?  I can't
see maintaining duplicate sets of documentation.

regards, tom lane

---(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

2007-08-29 Thread Joshua D. Drake
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

Tom Lane wrote:
 Josh Berkus [EMAIL PROTECTED] writes:
 If we go ahead with this, I'll commit to doing a contrib README
 cleanup so the doc system works better.
 
 Why wouldn't we just remove the README files altogether?  I can't
 see maintaining duplicate sets of documentation.

+1

Athough I could see a README at the top of contrib that says, contrib
documentation is now here link / directory etc...

Joshua D. Drake

 
   regards, tom lane
 
 ---(end of broadcast)---
 TIP 5: don't forget to increase your free space map settings
 


- --

  === The PostgreSQL Company: Command Prompt, Inc. ===
Sales/Support: +1.503.667.4564   24x7/Emergency: +1.800.492.2240
PostgreSQL solutions since 1997  http://www.commandprompt.com/
UNIQUE NOT NULL
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate
PostgreSQL Replication: http://www.commandprompt.com/products/

-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFG1bQQATb/zqfZUUQRAuYoAJ95zQkchY8pSq2BCyiy62ZAbA0hGgCdEHKt
SXzpwREgcgVNXjolnQh927o=
=mawb
-END PGP SIGNATURE-

---(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

2007-08-29 Thread Neil Conway
On Wed, 2007-08-29 at 13:53 -0400, Tom Lane wrote:
 Why wouldn't we just remove the README files altogether?  I can't
 see maintaining duplicate sets of documentation.

I agree that duplication is bad, but I think README files in the
individual contrib directories is useful and worth keeping: if I'm about
to install a contrib module and want to learn how to install and use it,
this change would only make that information *more* difficult to find.

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.

-Neil



---(end of broadcast)---
TIP 2: Don't 'kill -9' the postmaster


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-29 Thread Andrew Dunstan



Tom Lane wrote:

Josh Berkus [EMAIL PROTECTED] writes:
  

If we go ahead with this, I'll commit to doing a contrib README
cleanup so the doc system works better.



Why wouldn't we just remove the README files altogether?  I can't
see maintaining duplicate sets of documentation.


  


Right.

Also, let's recall what has previously been discussed for contrib, 
namely that we break it out into standard modules (think Perl standard 
modules) and other tools, and that we abandon the wholly misleading 
contrib name altogether. I really want to see that happen next 
release. Getting the modules properly documented is a very important 
milestone along the way to getting that done. Maybe then the modules 
will be considered more first class citizens (until the buildfarm came 
along they were often hardly tested at all).


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

2007-08-29 Thread Mario Gonzalez
On 29/08/2007, Neil Conway [EMAIL PROTECTED] wrote:

 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.


  Hello Neil, I think I'm doing something similar but not with README
files. Currently I'm writing the FAQ into Docbook XML, that's why we
can build the HTML and plain text at one.

 I'm going to finish this week then I'll show the results.



-- 
http://www.advogato.org/person/mgonzalez/

---(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: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Greg Smith

On Wed, 29 Aug 2007, Josh Berkus wrote:


Guys, would it be out of the question to do this in 8.3?  Please please?


Are you suggesting to add an additional piece of work to the already 
behind schedule 8.3 timeline when there's already this idea floating 
around to overhaul the entire contrib structure in 8.4, which may very 
well make much of that work redundant?  Albert's work is cool and all, but 
from from back here where I sit I'd expect anyone in a position to 
integrate it into 8.3 properly should be working on something that's 
already on the to-do list instead.


I know I'm about to dump a big stack of 8.3 data onto the list I'd 
appreciate some attention from you on, rather than having you distracted 
cleaning up documentation that's perfectly functional for now.


--
* Greg Smith [EMAIL PROTECTED] http://www.gregsmith.com Baltimore, MD

---(end of broadcast)---
TIP 3: Have you checked our extensive FAQ?

  http://www.postgresql.org/docs/faq


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-29 Thread Scott Marlowe
On 8/29/07, Mario Gonzalez [EMAIL PROTECTED] wrote:
 On 29/08/2007, Neil Conway [EMAIL PROTECTED] wrote:
 
  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.
 

   Hello Neil, I think I'm doing something similar but not with README
 files. Currently I'm writing the FAQ into Docbook XML, that's why we
 can build the HTML and plain text at one.

While I like the idea of the READMEs from contrib being in the docs, I
can't tell you the number of times I've installed a contrib module in
a dark ops center at 2am with no html browser handy (or at best a text
based one)  or with no access to external internet etc... and just
needed a line or two from the README file that came with the contrib
module.

Could the contrib README files couldn't be generated from the same
source as the docs (i.e. sgml) and then put into the appropriate
contrib/module/ directory.

---(end of broadcast)---
TIP 3: Have you checked our extensive FAQ?

   http://www.postgresql.org/docs/faq


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-29 Thread Michael Glaesemann


On Aug 29, 2007, at 13:27 , Andrew Dunstan wrote:

Also, let's recall what has previously been discussed for contrib,  
namely that we break it out into standard modules (think Perl  
standard modules) and other tools, and that we abandon the wholly  
misleading contrib name altogether. I really want to see that  
happen next release.


 +1

Michael Glaesemann
grzm seespotcode net



---(end of broadcast)---
TIP 5: don't forget to increase your free space map settings


Re: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Josh Berkus
Greg,

 Are you suggesting to add an additional piece of work to the already
 behind schedule 8.3 timeline when there's already this idea floating
 around to overhaul the entire contrib structure in 8.4, which may very
 well make much of that work redundant?  Albert's work is cool and all, but
 from from back here where I sit I'd expect anyone in a position to
 integrate it into 8.3 properly should be working on something that's
 already on the to-do list instead.

Or the contrib overhaul may *not* get into 8.4 (ala updatable views).  Having 
the contrib stuff in the main docs would remove one of the largest barriers 
to people knowing about the contrib features.

Further, you know we don't finish the docs until beta.  Ever.

 I know I'm about to dump a big stack of 8.3 data onto the list I'd
 appreciate some attention from you on, rather than having you distracted
 cleaning up documentation that's perfectly functional for now.

What kind of data?  On bgwriter_lru autotuning?

-- 
Josh Berkus
PostgreSQL @ Sun
San Francisco

---(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: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Andrew Dunstan



Josh Berkus wrote:

Greg,

  

Are you suggesting to add an additional piece of work to the already
behind schedule 8.3 timeline when there's already this idea floating
around to overhaul the entire contrib structure in 8.4, which may very
well make much of that work redundant?  Albert's work is cool and all, but
from from back here where I sit I'd expect anyone in a position to
integrate it into 8.3 properly should be working on something that's
already on the to-do list instead.



Or the contrib overhaul may *not* get into 8.4 (ala updatable views).  Having 
the contrib stuff in the main docs would remove one of the largest barriers 
to people knowing about the contrib features.


  


I don't agree with Greg that we shouldn't make this docs improvement. I 
do think we should do it in such a way that it will fit with our plans 
for the future.


cheers

andrew

---(end of broadcast)---
TIP 3: Have you checked our extensive FAQ?

  http://www.postgresql.org/docs/faq


Re: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Brar Piening

Josh Berkus wrote:

Having the contrib stuff in the main docs would remove one of the largest barriers 
to people knowing about the contrib features.
  
Using PostgreSQL since Version 7.1.3 and reading this List since - I 
dont't know exactly but my current archives start in 2003 which was the 
last time I crashed my system - Albert's work is actually the first 
piece of contrib documentation I ever read. I always knew about contrib 
but as I haven't been missing any feature in the core distribution (well 
- actually I've been missing PL/R until it came up - but as you know 
it's not in contrib ;-) I never found time to dig into the contrib 
directories and README's. Now that I did I'm pretty amazed about the 
nice features I've never thought about.

Further, you know we don't finish the docs until beta.  Ever.
  

Whenever you want - but do it.

I also highly appreciate Albert's Idea/Work.

Regards,
Brar

---(end of broadcast)---
TIP 5: don't forget to increase your free space map settings


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-29 Thread Alvaro Herrera
Scott Marlowe escribió:

 Could the contrib README files couldn't be generated from the same
 source as the docs (i.e. sgml) and then put into the appropriate
 contrib/module/ directory.

Sure they can.  We already do that for INSTALL for example.

-- 
Alvaro Herrera   http://www.PlanetPostgreSQL.org/
¡Ja ja ja! ¡Sólo hablaba en serio!

---(end of broadcast)---
TIP 3: Have you checked our extensive FAQ?

   http://www.postgresql.org/docs/faq


Re: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Greg Smith

On Wed, 29 Aug 2007, Josh Berkus wrote:


Further, you know we don't finish the docs until beta.  Ever.


In that context, as long as the documentation cleanup doesn't slow the 
schedule for when beta starts I think it would be a great thing to slip 
into 8.3.  In fact, if those are going higher-profile, I may slip an 
update into the docs for pg_buffercache with the queries I keep 
recommending people look at.



What kind of data?  On bgwriter_lru autotuning?


That would be my data; HOT is in a similar category.  I have many test 
results to pass along, and I'd like to know that the people who might help 
confirm/deny what I've discovered are as focused as I've been on trying to 
wrap all this up already, before wandering into new tangents that aren't 
already blocking the schedule.  That's all I'm saying.


--
* Greg Smith [EMAIL PROTECTED] http://www.gregsmith.com Baltimore, MD

---(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

2007-08-29 Thread Scott Marlowe
On 8/29/07, Alvaro Herrera [EMAIL PROTECTED] wrote:
 Scott Marlowe escribió:

  Could the contrib README files couldn't be generated from the same
  source as the docs (i.e. sgml) and then put into the appropriate
  contrib/module/ directory.

 Sure they can.  We already do that for INSTALL for example.

OK, s/Could/May/ up there.  :)

---(end of broadcast)---
TIP 5: don't forget to increase your free space map settings


Re: [DOCS] [HACKERS] Contrib modules documentation online

2007-08-29 Thread Tom Lane
Josh Berkus [EMAIL PROTECTED] writes:
 Further, you know we don't finish the docs until beta.  Ever.

Right, working on docs is a standard beta-period activity.  I think
Greg is suggesting that right now is not the time to think about
improving contrib docs --- right now is the time to keep our eyes
on the ball and *get* to beta.  If you've got time to worry about
it afterward, do so then.

regards, tom lane

---(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: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Albert Cervera i Areny

 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?

About command options if done different things, it depends on the module I 
need to revisit this. I also think one command per subchapter isn't very 
handy.

There's also the install issue. By now it's on the introduction of the 
chapter. And I've repeated it in some of the modules, not all. Do you think 
it be better put the exact instructions for compiling and installing for each 
one? What about 'extra' notes, such us some performance tests, and so one. 
Some of the notes should probably stay in the README files, just like the 
README files that can be found in some dirs of core. So I'd keep information 
targeted to developers into the README's and general info into the main doc.


 Guys, would it be out of the question to do this in 8.3?  Please please?

I will try to have everything before 8.3. I'd like it gave very little or no 
work to core developers. If so many people is interested you can help me 
revise it before the final version.

By the way, if somebody has updated any of the contrib README files recently, 
please send me an e-mail and I'll check if I have the last changes in.



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

---(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: [HACKERS] Contrib modules documentation online

2007-08-29 Thread Andrew Dunstan



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.


cheers

andrew



---(end of broadcast)---
TIP 3: Have you checked our extensive FAQ?

  http://www.postgresql.org/docs/faq


[HACKERS] Contrib modules documentation online

2007-08-28 Thread Albert Cervera i Areny
I've been working on converting the current README files for all contrib 
modules into sgml and add it to the documentation. There are still some fixes 
to do but i'd like to have some feedback. Indeed, it wasn't agreed to have 
all if any of the modules together with the core documentation.

You can see the docs on [1] in chapter VIII. If you think these could be a 
good addition, please fill free to comment on how you think sections should 
be organized to be consistent and easy to read.

[1] http://www.nan-tic.com/ftp/pgdoc

---(end of broadcast)---
TIP 4: Have you searched our list archives?

   http://archives.postgresql.org