Обсуждение: documenting contrib modules (was Re: Building PDFs error)
On Sat, Mar 12, 2011 at 3:57 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Peter Eisentraut <peter_e@gmx.net> writes: >> On lör, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote: >>> OK, it is not something worthwhile, or just something you don't have >>> time for. If the later, can you give us a hint on how to fix it? > >> I'm not even sure what the actual action item is supposed to be. > > The last suggestion in the thread was to move the contrib docs up one > level in the hierarchy, ie each contrib module would get a chapter not a > sect1. Trouble is, many of those will be extremely short chapters. Consider passwordcheck, for example. I think that contrib has a bit of a split-personality disorder at present. It has at least four different kinds of things in it: - First-class citizens intended to provide core functionality (file_fdw, pg_upgrade, dblink, hstore, sepgsql, pg_archivecleanup) - Debugging and instrumentation tools (pageinspect, pg_buffercache, pg_rowlocks, pg_stat_statements, auto_explain, oid2name) - Code examples, some of which are also used for regression testing (spi, dummy_seclabel, test_parser) - Modules that are largely superseded by new core features, but we can't quite bring ourselves to kill them yet because they still have some possible remaining utility (xml2, intarray, intagg) I think it would be really helpful to try to group these modules in some way, and perhaps provide a chapter for each group rather than a chapter for the entire set. If you're looking at contrib for the first time, it's pretty hard to know that the thing called hstore is something many people think is teh awesome while the thing called intagg is a compatibility wrapper with no obvious residual utility whatsoever. Arguably we should try to rearrange the actual source code tree at some point, too, but maybe that should left for phase 2. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Robert Haas wrote: > On Sat, Mar 12, 2011 at 3:57 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > Peter Eisentraut <peter_e@gmx.net> writes: > >> On l?r, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote: > >>> OK, it is not something worthwhile, or just something you don't have > >>> time for. ?If the later, can you give us a hint on how to fix it? > > > >> I'm not even sure what the actual action item is supposed to be. > > > > The last suggestion in the thread was to move the contrib docs up one > > level in the hierarchy, ie each contrib module would get a chapter not a > > sect1. > > Trouble is, many of those will be extremely short chapters. Consider > passwordcheck, for example. > > I think that contrib has a bit of a split-personality disorder at > present. It has at least four different kinds of things in it: > > - First-class citizens intended to provide core functionality > (file_fdw, pg_upgrade, dblink, hstore, sepgsql, pg_archivecleanup) > - Debugging and instrumentation tools (pageinspect, pg_buffercache, > pg_rowlocks, pg_stat_statements, auto_explain, oid2name) > - Code examples, some of which are also used for regression testing > (spi, dummy_seclabel, test_parser) > - Modules that are largely superseded by new core features, but we > can't quite bring ourselves to kill them yet because they still have > some possible remaining utility (xml2, intarray, intagg) > > I think it would be really helpful to try to group these modules in > some way, and perhaps provide a chapter for each group rather than a > chapter for the entire set. If you're looking at contrib for the > first time, it's pretty hard to know that the thing called hstore is > something many people think is teh awesome while the thing called > intagg is a compatibility wrapper with no obvious residual utility > whatsoever. Arguably we should try to rearrange the actual source > code tree at some point, too, but maybe that should left for phase 2. Is this a TODO? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On Mon, Sep 5, 2011 at 2:08 PM, Bruce Momjian <bruce@momjian.us> wrote: > Is this a TODO? Well, it's on my personal TODO list to wear down Tom's resistance to the idea. But I'm not sure we have any project-wide consensus on it at this point. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company