From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201109051908.p85J8iT08660@momjian.us>
Subject: Re: documenting contrib modules (was Re: Building PDFs error)
In-Reply-To: <AANLkTinxQYzcHYf5A_T3RxYBcK1LeBtBigT=x3Xi50BA@mail.gmail.com>
To: Robert Haas <robertmhaas@gmail.com>
Date: Mon, 5 Sep 2011 15:08:44 -0400 (EDT)
CC: Tom Lane <tgl@sss.pgh.pa.us>, Peter Eisentraut <peter_e@gmx.net>,
	Josh Kupershmidt <schmiddy@gmail.com>,
	pgsql-docs <pgsql-docs@postgresql.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"

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. +