Re: Code examples

From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: Peter Eisentraut <peter_e(at)gmx(dot)net>
Cc: pgsql-docs(at)postgresql(dot)org, Decibel! <decibel(at)decibel(dot)org>, Oleg Bartunov <oleg(at)sai(dot)msu(dot)su>, Pavel Stehule <pavel(dot)stehule(at)gmail(dot)com>
Subject: Re: Code examples
Date: 2007-09-04 00:39:54
Message-ID: 6062.1188866394@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs pgsql-hackers

Peter Eisentraut <peter_e(at)gmx(dot)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

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Pavel Stehule 2007-09-04 05:04:27 Re: tsearch filenames unlikes special symbols and numbers
Previous Message Peter Eisentraut 2007-09-04 00:29:28 Re: Code examples

Browse pgsql-hackers by date

  From Date Subject
Next Message Florian G. Pflug 2007-09-04 00:50:16 Re: Per-function GUC settings: trickier than it looked
Previous Message Tom Lane 2007-09-04 00:34:14 Re: Hash index todo list item