Re: documenting contrib modules (was Re: Building PDFs error)

Robert Haas wrote:
> On Sat, Mar 12, 2011 at 3:57 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > Peter Eisentraut <peter_e(at)gmx(dot)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(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +