Contrib docs v1

I attach the patch for the contrib docs. Mainly it's been formatting the
README files of each directory into SGML.

I've removed TODOs, history, licenses (all of them are BSD AFAICS), file
descriptions and install instructions (I only left one for them all).

The hole contrib is one single chapter after Full Text Search. I think this
gives it a lot of visibility as it's where other functions are, and given
that most contrib modules provide functions seemed a good place. However, Tom
showed some concerns with that so a final position should be decided. Each
section is the name of the contrib module. The first paragraph summarises
what it does. And usually the last subsection contains the author(s). The
rest is pretty different from one another and possibly some polishing will
have to be done afterwards.

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

Albert Cervera i Areny wrote:
> I attach the patch for the contrib docs. Mainly it's been formatting the
> README files of each directory into SGML.
>
> I've removed TODOs, history, licenses (all of them are BSD AFAICS), file
> descriptions and install instructions (I only left one for them all).
>
> The hole contrib is one single chapter after Full Text Search. I think this
> gives it a lot of visibility as it's where other functions are, and given
> that most contrib modules provide functions seemed a good place. However, Tom
> showed some concerns with that so a final position should be decided. Each
> section is the name of the contrib module. The first paragraph summarises
> what it does. And usually the last subsection contains the author(s). The
> rest is pretty different from one another and possibly some polishing will
> have to be done afterwards.

Your patch was missing these SGML files:

onsgmls:contrib.sgml:26:1:E: cannot find "btree-gist.sgml"; tried "btree-gist.sgml", "./btree-gist.sgml"
onsgmls:contrib.sgml:28:1:E: cannot find "cube.sgml"; tried "cube.sgml", "./cube.sgml"
onsgmls:contrib.sgml:53:1:E: cannot find "xml2.sgml"; tried "xml2.sgml", "./xml2.sgml"

Are you still working on those?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

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

Sorry, I missed them, indeed I packed btree_gist instead of the good one
btree-gist. The cube and xml2 have been added to.

A Divendres 09 Novembre 2007, Bruce Momjian va escriure:
> Albert Cervera i Areny wrote:
> > I attach the patch for the contrib docs. Mainly it's been formatting the
> > README files of each directory into SGML.
> >
> > I've removed TODOs, history, licenses (all of them are BSD AFAICS), file
> > descriptions and install instructions (I only left one for them all).
> >
> > The hole contrib is one single chapter after Full Text Search. I think
> > this gives it a lot of visibility as it's where other functions are, and
> > given that most contrib modules provide functions seemed a good place.
> > However, Tom showed some concerns with that so a final position should be
> > decided. Each section is the name of the contrib module. The first
> > paragraph summarises what it does. And usually the last subsection
> > contains the author(s). The rest is pretty different from one another and
> > possibly some polishing will have to be done afterwards.
>
> Your patch was missing these SGML files:
>
> onsgmls:contrib.sgml:26:1:E: cannot find "btree-gist.sgml"; tried
> "btree-gist.sgml", "./btree-gist.sgml" onsgmls:contrib.sgml:28:1:E: cannot
> find "cube.sgml"; tried "cube.sgml", "./cube.sgml"
> onsgmls:contrib.sgml:53:1:E: cannot find "xml2.sgml"; tried "xml2.sgml",
> "./xml2.sgml"
>
> Are you still working on those?

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

Albert Cervera i Areny wrote:
> Sorry, I missed them, indeed I packed btree_gist instead of the good one
> btree-gist. The cube and xml2 have been added to.

Thanks. All applied. I know people liked the README files in each
/contrib directory but we have no chance of keeping them in sync with
the SGML so I removed them.

I still have lots of adjustments to make but at least it is in.

Albert, can you do the new dict_int and dict_xsyn READMEs. I could do
them but I am afraid I would not do as consistent of a job as you did.
Thanks. Those README's are still in CVS /contrib, of course.

---------------------------------------------------------------------------

>
> A Divendres 09 Novembre 2007, Bruce Momjian va escriure:
> > Albert Cervera i Areny wrote:
> > > I attach the patch for the contrib docs. Mainly it's been formatting the
> > > README files of each directory into SGML.
> > >
> > > I've removed TODOs, history, licenses (all of them are BSD AFAICS), file
> > > descriptions and install instructions (I only left one for them all).
> > >
> > > The hole contrib is one single chapter after Full Text Search. I think
> > > this gives it a lot of visibility as it's where other functions are, and
> > > given that most contrib modules provide functions seemed a good place.
> > > However, Tom showed some concerns with that so a final position should be
> > > decided. Each section is the name of the contrib module. The first
> > > paragraph summarises what it does. And usually the last subsection
> > > contains the author(s). The rest is pretty different from one another and
> > > possibly some polishing will have to be done afterwards.
> >
> > Your patch was missing these SGML files:
> >
> > onsgmls:contrib.sgml:26:1:E: cannot find "btree-gist.sgml"; tried
> > "btree-gist.sgml", "./btree-gist.sgml" onsgmls:contrib.sgml:28:1:E: cannot
> > find "cube.sgml"; tried "cube.sgml", "./cube.sgml"
> > onsgmls:contrib.sgml:53:1:E: cannot find "xml2.sgml"; tried "xml2.sgml",
> > "./xml2.sgml"
> >
> > Are you still working on those?
>
>
>
> --
> Albert Cervera i Areny
> http://www.NaN-tic.com

[ Attachment, skipping... ]

>
> ---------------------------(end of broadcast)---------------------------
> TIP 6: explain analyze is your friend

--
Bruce Momjian <bruce(at)momjian(dot)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, Bruce Momjian va escriure:
> Albert Cervera i Areny wrote:
> > Sorry, I missed them, indeed I packed btree_gist instead of the good one
> > btree-gist. The cube and xml2 have been added to.
>
> Thanks. All applied. I know people liked the README files in each
> /contrib directory but we have no chance of keeping them in sync with
> the SGML so I removed them.
>
> I still have lots of adjustments to make but at least it is in.

I know there are many things to improve but as you say at least it is in. Now
we can improve it incrementally.

>
> Albert, can you do the new dict_int and dict_xsyn READMEs. I could do
> them but I am afraid I would not do as consistent of a job as you did.
> Thanks. Those README's are still in CVS /contrib, of course.

Of course. I'll send them ASAP.

>
> ---------------------------------------------------------------------------
>
> > A Divendres 09 Novembre 2007, Bruce Momjian va escriure:
> > > Albert Cervera i Areny wrote:
> > > > I attach the patch for the contrib docs. Mainly it's been formatting
> > > > the README files of each directory into SGML.
> > > >
> > > > I've removed TODOs, history, licenses (all of them are BSD AFAICS),
> > > > file descriptions and install instructions (I only left one for them
> > > > all).
> > > >
> > > > The hole contrib is one single chapter after Full Text Search. I
> > > > think this gives it a lot of visibility as it's where other functions
> > > > are, and given that most contrib modules provide functions seemed a
> > > > good place. However, Tom showed some concerns with that so a final
> > > > position should be decided. Each section is the name of the contrib
> > > > module. The first paragraph summarises what it does. And usually the
> > > > last subsection contains the author(s). The rest is pretty different
> > > > from one another and possibly some polishing will have to be done
> > > > afterwards.
> > >
> > > Your patch was missing these SGML files:
> > >
> > > onsgmls:contrib.sgml:26:1:E: cannot find "btree-gist.sgml"; tried
> > > "btree-gist.sgml", "./btree-gist.sgml" onsgmls:contrib.sgml:28:1:E:
> > > cannot find "cube.sgml"; tried "cube.sgml", "./cube.sgml"
> > > onsgmls:contrib.sgml:53:1:E: cannot find "xml2.sgml"; tried
> > > "xml2.sgml", "./xml2.sgml"
> > >
> > > Are you still working on those?
> >
> > --
> > Albert Cervera i Areny
> > http://www.NaN-tic.com
>
> [ Attachment, skipping... ]
>
> > ---------------------------(end of broadcast)---------------------------
> > TIP 6: explain analyze is your friend

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

Albert Cervera i Areny wrote:
> A Diumenge 11 Novembre 2007, Bruce Momjian va escriure:
> > Albert Cervera i Areny wrote:
> > > Sorry, I missed them, indeed I packed btree_gist instead of the good one
> > > btree-gist. The cube and xml2 have been added to.
> >
> > Thanks. All applied. I know people liked the README files in each
> > /contrib directory but we have no chance of keeping them in sync with
> > the SGML so I removed them.
> >
> > I still have lots of adjustments to make but at least it is in.
>
> I know there are many things to improve but as you say at least it is in. Now
> we can improve it incrementally.
>
> >
> > Albert, can you do the new dict_int and dict_xsyn READMEs. I could do
> > them but I am afraid I would not do as consistent of a job as you did.
> > Thanks. Those README's are still in CVS /contrib, of course.
>
> Of course. I'll send them ASAP.

Uh, don't start converting them yet. I now realize that
/contrib/dict_int is an example and just like the stuff in /contrib/spi
perhaps shouldn't have its docs moved to SGML. Is /contrib/dict_xsyn
also just an example? Should we leave example /contrib modules
documented in READMEs?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

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

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Uh, don't start converting them yet. I now realize that
> /contrib/dict_int is an example and just like the stuff in /contrib/spi
> perhaps shouldn't have its docs moved to SGML.

What makes you realize any such thing? You could make that argument for
test_parser, probably, but the dict modules are useful in their own
right.

> Should we leave example /contrib modules documented in READMEs?

What is the point of such a distinction?

regards, tom lane

Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > Uh, don't start converting them yet. I now realize that
> > /contrib/dict_int is an example and just like the stuff in /contrib/spi
> > perhaps shouldn't have its docs moved to SGML.
>
> What makes you realize any such thing? You could make that argument for
> test_parser, probably, but the dict modules are useful in their own
> right.
>
> > Should we leave example /contrib modules documented in READMEs?
>
> What is the point of such a distinction?

If the contrib value is the source code itself then it seems a README is
more appropriate as people are not going to install the contrib module
itself --- they are using it only to learn.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

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

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Tom Lane wrote:
>> What is the point of such a distinction?

> If the contrib value is the source code itself then it seems a README is
> more appropriate as people are not going to install the contrib module
> itself --- they are using it only to learn.

I find this argument pretty unconvincing. Most of the contrib modules
serve at least some purpose as coding examples.

If we set up a situation where all but one or two are documented in the
main SGML docs, the net effect will be that people don't even know that
the ones left out exist. Even a module that's only useful as an example
won't be useful at all, if people don't find it.

regards, tom lane

Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > Tom Lane wrote:
> >> What is the point of such a distinction?
>
> > If the contrib value is the source code itself then it seems a README is
> > more appropriate as people are not going to install the contrib module
> > itself --- they are using it only to learn.
>
> I find this argument pretty unconvincing. Most of the contrib modules
> serve at least some purpose as coding examples.
>
> If we set up a situation where all but one or two are documented in the
> main SGML docs, the net effect will be that people don't even know that
> the ones left out exist. Even a module that's only useful as an example
> won't be useful at all, if people don't find it.

Makes sense. Albert, can you do the remaining READMEs? You can skip
tsearch2 and the Japanese ones. That is going away before final 8.3.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

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

Albert Cervera i Areny <albert(at)nan-tic(dot)com> writes:
> [ contrib sgml docs ]

I am distressed to discover that these seem to have been generated from
a snapshot taken some time in June, as they are missing the last five
months' worth of changes to the now-deleted README files.

regards, tom lane

Tom Lane wrote:
> Albert Cervera i Areny <albert(at)nan-tic(dot)com> writes:
>
>> [ contrib sgml docs ]
>>
>
> I am distressed to discover that these seem to have been generated from
> a snapshot taken some time in June, as they are missing the last five
> months' worth of changes to the now-deleted README files.
>
>
>

I guess that's why we have an Attic, no? They aren't really deleted.

cheers

andrew

Tom Lane wrote:
> Albert Cervera i Areny <albert(at)nan-tic(dot)com> writes:
> > [ contrib sgml docs ]
>
> I am distressed to discover that these seem to have been generated from
> a snapshot taken some time in June, as they are missing the last five
> months' worth of changes to the now-deleted README files.

That is odd. I found changes from a README that was modified on October
1 in the SGML so I thought were were only missing the changes since
then. This change from October 1 is in SGML:

http://developer.postgresql.org/cvsweb.cgi/pgsql/contrib/chkpass/Attic/README.chkpass.diff?r1=1.4;r2=1.5;f=h

So I assume we were only missing the dict_*/README additions.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com

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

I started importing the files when I notified the list, can't remember exactly
when and I've iteratively improved all the files so there can be differences
though I thought that contrib READMES where very stable. Anyway, I'll try to
take a look at the diffs from then and add those changes.

A Dimecres 14 Novembre 2007, Tom Lane va escriure:
> Albert Cervera i Areny <albert(at)nan-tic(dot)com> writes:
> > [ contrib sgml docs ]
>
> I am distressed to discover that these seem to have been generated from
> a snapshot taken some time in June, as they are missing the last five
> months' worth of changes to the now-deleted README files.
>
> regards, tom lane
>
> ---------------------------(end of broadcast)---------------------------
> TIP 7: You can help support the PostgreSQL project by donating at
>
> http://www.postgresql.org/about/donate

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

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> So I assume we were only missing the dict_*/README additions.

You are entirely mistaken. There are missing updates in at least
README.pg_standby, README.pageinspect, README.intarray, README.pgbench;
and README.pgrowlocks is sufficiently confused that it's hard to tell
if it was copied before or after the last change.

regards, tom lane