To: Peter Eisentraut <peter_e@gmx.net>
cc: pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>,
	Oleg Bartunov <oleg@sai.msu.su>, Pavel Stehule <pavel.stehule@gmail.com>
Subject: Re: Code examples 
In-reply-to: <200709040229.29591.peter_e@gmx.net> 
References: <162867790709021328i7771aa9jfe79268bccbf123d@mail.gmail.com>
	<18259.1188773171@sss.pgh.pa.us>
	<20070903171858.GV38801@decibel.org>
	<200709040229.29591.peter_e@gmx.net>
Comments: In-reply-to Peter Eisentraut <peter_e@gmx.net>
	message dated "Tue, 04 Sep 2007 02:29:28 +0200"
Date: Mon, 03 Sep 2007 20:39:54 -0400
Message-ID: <6062.1188866394@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Peter Eisentraut <peter_e@gmx.net> writes:
> 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.

Well, both my point and Jim's was that trying to compile and run the
code would help to expose such silliness.

In the case at hand, there's another consideration: the examples are
large and are (I believe) intended as working skeletons for real code
development.  They'd be a lot more useful for that purpose if they were
available as actual contrib modules.  C code that's been hacked until
it passes for SGML isn't compilable.

			regards, tom lane