[DOCS] Code examples
Moving to -docs On Sun, Sep 02, 2007 at 06:46:11PM -0400, Tom Lane wrote: > > Another problem I see are broken examples of dictionary and parser in > > documentation: > > http://momjian.us/main/writings/pgsql/sgml/textsearch-rule-dictionary-example.html > > http://momjian.us/main/writings/pgsql/sgml/textsearch-parser-example.html > > Yeah, I wanted to discuss that with you. Code examples in sgml docs are > a bad idea: they're impossible to use as actual templates, because of > all the weird markup changes, and there's no easy way to notice if > they're broken. It would be better to remove these from the docs and > set them up as contrib modules. 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? I wrote some code that does this back when I was thinking about writing a book, if anyone wants to see it. -- Decibel!, aka Jim Nasby[EMAIL PROTECTED] EnterpriseDB http://enterprisedb.com 512.569.9461 (cell) pgp5HmGl0zpDR.pgp Description: PGP signature
Re: [DOCS] Code examples
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/ ---(end of broadcast)--- TIP 6: explain analyze is your friend
Re: [DOCS] Code examples
Peter Eisentraut <[EMAIL PROTECTED]> 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 ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
