From: Peter Eisentraut <peter_e@gmx.net>
To: pgsql-docs@postgresql.org
Subject: Re: Code examples
Date: Tue, 4 Sep 2007 02:29:28 +0200
User-Agent: KMail/1.9.5
Cc: Decibel! <decibel@decibel.org>, Tom Lane <tgl@sss.pgh.pa.us>,
	Oleg Bartunov <oleg@sai.msu.su>, Pavel Stehule <pavel.stehule@gmail.com>
References: <162867790709021328i7771aa9jfe79268bccbf123d@mail.gmail.com>
	<18259.1188773171@sss.pgh.pa.us>
	<20070903171858.GV38801@decibel.org>
In-Reply-To: <20070903171858.GV38801@decibel.org>
MIME-Version: 1.0
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
Message-Id: <200709040229.29591.peter_e@gmx.net>

Decibel! wrote:
> Couldn't we come up with some method of specifying code examples in
> the docs and then having the doc build process actually run those
> examples and put that into the doc build?

While that seems very tempting, I think you need manual review to check 
whether the examples make didactic sense.  For example, I seem to 
recall that we had to change some examples about how operator 
precendence or type casting gives unexpected results several times over 
the years because the unexpected results had turned into expected 
results in response to new features.  If you'd just produce the 
documentation examples automatically, you'd be left with quite 
embarrassing nonsense in there.

-- 
Peter Eisentraut
http://developer.postgresql.org/~petere/