From: Peter Eisentraut <peter_e@gmx.net>
To: pgsql-docs@postgresql.org
Cc: Decibel! <decibel@decibel.org>
Cc: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Oleg Bartunov <oleg@sai.msu.su>
Cc: Pavel Stehule <pavel.stehule@gmail.com>
Subject: Re: Code examples
Date: Tue, 4 Sep 2007 02:29:28 +0200
Message-ID: <200709040229.29591.peter_e@gmx.net> (raw)
In-Reply-To: <20070903171858.GV38801@decibel.org>
References: <162867790709021328i7771aa9jfe79268bccbf123d@mail.gmail.com>
<18259.1188773171@sss.pgh.pa.us>
<20070903171858.GV38801@decibel.org>
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/
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: peter_e@gmx.net, decibel@decibel.org, tgl@sss.pgh.pa.us, oleg@sai.msu.su, pavel.stehule@gmail.com
Subject: Re: Code examples
In-Reply-To: <200709040229.29591.peter_e@gmx.net>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox