Thread: 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@decibel.org EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)
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/
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
Am Dienstag, 4. September 2007 02:39 schrieb Tom Lane: > C code that's been hacked until it passes for SGML isn't compilable. I don't understand this point. Why would SGML care what the C code looks like? -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut <peter_e@gmx.net> writes:
> Am Dienstag, 4. September 2007 02:39 schrieb Tom Lane:
>> C code that's been hacked until it passes for SGML isn't compilable.
> I don't understand this point. Why would SGML care what the C code looks
> like?
&, <, and > need to be hacked so that SGML doesn't barf on them.
Unfortunately, all three symbols are a bit commonplace in C code.
Now admittedly this can be fixed with moderately simple
search-and-replaces, but it's still another obstacle in the path of
someone who actually wishes to use the code for its intended purpose,
or even someone who would like to find out if the examples aren't
broken.
regards, tom lane
Tom Lane escribió: > Peter Eisentraut <peter_e@gmx.net> writes: > > Am Dienstag, 4. September 2007 02:39 schrieb Tom Lane: > >> C code that's been hacked until it passes for SGML isn't compilable. > > > I don't understand this point. Why would SGML care what the C code looks > > like? > > &, <, and > need to be hacked so that SGML doesn't barf on them. > Unfortunately, all three symbols are a bit commonplace in C code. Maybe we could set things up so that there are actual files which are programatically preprocessed to SGML to be included in the docs? That way, the docs always reflect the actual file, which by itself is compilable. The SGML source would only contain something like <include file="examples/foo.c" /> or something like that. Is that feasible? -- Alvaro Herrera http://www.amazon.com/gp/registry/CTMLCN8V17R4 "No necesitamos banderas No reconocemos fronteras" (Jorge González)
Am Dienstag, 4. September 2007 16:11 schrieb Tom Lane: > &, <, and > need to be hacked so that SGML doesn't barf on them. > Unfortunately, all three symbols are a bit commonplace in C code. I assume that someone who wants to try out the code would copy it from the HTML, not out of the SGML source. But in any case you can avoid the escaping like so: <![CDATA[ ... code ... ]]> Grep for existing uses. The idea of including the C files directly could also work. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Alvaro Herrera <alvherre@commandprompt.com> writes:
> Maybe we could set things up so that there are actual files which are
> programatically preprocessed to SGML to be included in the docs? That
> way, the docs always reflect the actual file, which by itself is
> compilable. The SGML source would only contain something like
> <include file="examples/foo.c" /> or something like that.
Well, if we have actual contrib modules (which is still a good idea
so that they get tested on a regular basis), I don't see any need to
copy the code into the docs at all. The docs should just say "a working
example can be found in contrib/whatever".
regards, tom lane
On Tue, 4 Sep 2007, Tom Lane wrote:
> Alvaro Herrera <alvherre@commandprompt.com> writes:
>> Maybe we could set things up so that there are actual files which are
>> programatically preprocessed to SGML to be included in the docs? That
>> way, the docs always reflect the actual file, which by itself is
>> compilable. The SGML source would only contain something like
>> <include file="examples/foo.c" /> or something like that.
>
> Well, if we have actual contrib modules (which is still a good idea
> so that they get tested on a regular basis), I don't see any need to
> copy the code into the docs at all. The docs should just say "a working
> example can be found in contrib/whatever".
I thin Tom is right. We already have many user's dictionaries which
would be worth to distribute.
>
> regards, tom lane
>
Regards,
Oleg
_____________________________________________________________
Oleg Bartunov, Research Scientist, Head of AstroNet (www.astronet.ru),
Sternberg Astronomical Institute, Moscow University, Russia
Internet: oleg@sai.msu.su, http://www.sai.msu.su/~megera/
phone: +007(495)939-16-83, +007(495)939-23-83
Hi,
It seems to me this mention of extract()
in the manual (chapter 9.8):
extract('dow', ...)
is better replaced with
extract(dow from ...)
( 8.3, 8.4, HEAD )
hth
Erik Rijkers
--- doc/src/sgml/func.sgml.orig 2009-11-15 21:58:02.000000000 +0100
+++ doc/src/sgml/func.sgml 2009-11-15 21:59:16.000000000 +0100
@@ -5274,9 +5274,9 @@
<listitem>
<para>
<function>to_char(..., 'ID')</function>'s day of the week numbering
- matches the <function>extract('isodow', ...)</function> function, but
+ matches the <function>extract(isodow from ...)</function> function, but
<function>to_char(..., 'D')</function>'s does not match
- <function>extract('dow', ...)</function>'s day numbering.
+ <function>extract(dow from ...)</function>'s day numbering.
</para>
</listitem>
On sön, 2009-11-15 at 22:50 +0100, Erik Rijkers wrote:
> It seems to me this mention of extract()
> in the manual (chapter 9.8):
> extract('dow', ...)
>
> is better replaced with
> extract(dow from ...)
>
> ( 8.3, 8.4, HEAD )
Fix applied to those versions. Thanks.