Received: from localhost (unknown [200.46.204.184])
	by postgresql.org (Postfix) with ESMTP id 985E09F9F7C
	for <pgsql-docs-postgresql.org@postgresql.org>;
	Tue,  4 Sep 2007 13:19:35 -0300 (ADT)
Received: from postgresql.org ([200.46.204.71])
	by localhost (mx1.hub.org [200.46.204.184]) (amavisd-maia, port 10024)
	with ESMTP id 28409-01 for <pgsql-docs-postgresql.org@postgresql.org>;
	Tue,  4 Sep 2007 13:19:30 -0300 (ADT)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.5
Received: from sss.pgh.pa.us (sss.pgh.pa.us [66.207.139.130])
	by postgresql.org (Postfix) with ESMTP id D5A709F9B74
	for <pgsql-docs@postgresql.org>; Tue,  4 Sep 2007 13:19:30 -0300 (ADT)
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.1/8.14.1) with ESMTP id l84GJEZ7026292;
	Tue, 4 Sep 2007 12:19:14 -0400 (EDT)
To: Alvaro Herrera <alvherre@commandprompt.com>
cc: Peter Eisentraut <peter_e@gmx.net>, 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: <20070904143640.GF6466@alvh.no-ip.org> 
References: <162867790709021328i7771aa9jfe79268bccbf123d@mail.gmail.com>
	<200709040229.29591.peter_e@gmx.net>
	<6062.1188866394@sss.pgh.pa.us>
	<200709041101.54641.peter_e@gmx.net>
	<24261.1188915090@sss.pgh.pa.us>
	<20070904143640.GF6466@alvh.no-ip.org>
Comments: In-reply-to Alvaro Herrera <alvherre@commandprompt.com>
	message dated "Tue, 04 Sep 2007 10:36:40 -0400"
Date: Tue, 04 Sep 2007 12:19:14 -0400
Message-ID: <26291.1188922754@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Archive-Number: 200709/8
X-Sequence-Number: 4406

Alvaro Herrera <alvherre@commandprompt.com> writes:
> Maybe we could set things up so that there are actual files which are
> programatically preprocessed to SGML to be included in the docs?  That
> way, the docs always reflect the actual file, which by itself is
> compilable.  The SGML source would only contain something like
> <include file="examples/foo.c" /> or something like that.

Well, if we have actual contrib modules (which is still a good idea
so that they get tested on a regular basis), I don't see any need to
copy the code into the docs at all.  The docs should just say "a working
example can be found in contrib/whatever".

			regards, tom lane