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 decibel(at)decibel(dot)org
EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)