Thread: Re: [PATCHES] Contrib docs v1
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@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:
> 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@momjian.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@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:
>> 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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +