From: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter_e@gmx.net>
Cc: pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>
Cc: Oleg Bartunov <oleg@sai.msu.su>
Cc: Pavel Stehule <pavel.stehule@gmail.com>
Subject: Re: Code examples
Date: Mon, 03 Sep 2007 20:39:54 -0400
Message-ID: <6062.1188866394@sss.pgh.pa.us> (raw)
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>
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
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: tgl@sss.pgh.pa.us, peter_e@gmx.net, decibel@decibel.org, oleg@sai.msu.su, pavel.stehule@gmail.com
Subject: Re: Code examples
In-Reply-To: <6062.1188866394@sss.pgh.pa.us>
* 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