pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedCode examples
9+ messages / 5 participants
[nested] [flat]
* Code examples
@ 2007-09-03 17:18 Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 9+ messages in thread
From: Decibel! @ 2007-09-03 17:18 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>; pgsql-docs
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)
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
@ 2007-09-04 00:29 ` Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 9+ messages in thread
From: Peter Eisentraut @ 2007-09-04 00:29 UTC (permalink / raw)
To: pgsql-docs; +Cc: Decibel! <decibel@decibel.org>; Tom Lane <tgl@sss.pgh.pa.us>; Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>
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/
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
@ 2007-09-04 00:39 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 09:01 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 9+ messages in thread
From: Tom Lane @ 2007-09-04 00:39 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>; Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
@ 2007-09-04 09:01 ` Peter Eisentraut <peter_e@gmx.net>
2007-09-04 14:11 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 9+ messages in thread
From: Peter Eisentraut @ 2007-09-04 09:01 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>; Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>
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/
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 09:01 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
@ 2007-09-04 14:11 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 14:36 ` Re: Code examples Alvaro Herrera <alvherre@commandprompt.com>
2007-09-04 15:04 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
0 siblings, 2 replies; 9+ messages in thread
From: Tom Lane @ 2007-09-04 14:11 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>; Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 09:01 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 14:11 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
@ 2007-09-04 14:36 ` Alvaro Herrera <alvherre@commandprompt.com>
2007-09-04 16:19 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 9+ messages in thread
From: Alvaro Herrera @ 2007-09-04 14:36 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter_e@gmx.net>; pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>; Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>
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)
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 09:01 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 14:11 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 14:36 ` Re: Code examples Alvaro Herrera <alvherre@commandprompt.com>
@ 2007-09-04 16:19 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 16:37 ` Re: Code examples Oleg Bartunov <oleg@sai.msu.su>
0 siblings, 1 reply; 9+ messages in thread
From: Tom Lane @ 2007-09-04 16:19 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@commandprompt.com>; +Cc: Peter Eisentraut <peter_e@gmx.net>; pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>; Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 09:01 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 14:11 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 14:36 ` Re: Code examples Alvaro Herrera <alvherre@commandprompt.com>
2007-09-04 16:19 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
@ 2007-09-04 16:37 ` Oleg Bartunov <oleg@sai.msu.su>
0 siblings, 0 replies; 9+ messages in thread
From: Oleg Bartunov @ 2007-09-04 16:37 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Alvaro Herrera <alvherre@commandprompt.com>; Peter Eisentraut <peter_e@gmx.net>; pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>; Pavel Stehule <pavel.stehule@gmail.com>
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Code examples
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 09:01 ` Re: Code examples Peter Eisentraut <peter_e@gmx.net>
2007-09-04 14:11 ` Re: Code examples Tom Lane <tgl@sss.pgh.pa.us>
@ 2007-09-04 15:04 ` Peter Eisentraut <peter_e@gmx.net>
1 sibling, 0 replies; 9+ messages in thread
From: Peter Eisentraut @ 2007-09-04 15:04 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs@postgresql.org, Decibel! <decibel@decibel.org>; Oleg Bartunov <oleg@sai.msu.su>; Pavel Stehule <pavel.stehule@gmail.com>
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/
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2007-09-04 16:37 UTC | newest]
Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2007-09-03 17:18 Code examples Decibel! <decibel@decibel.org>
2007-09-04 00:29 ` Peter Eisentraut <peter_e@gmx.net>
2007-09-04 00:39 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 09:01 ` Peter Eisentraut <peter_e@gmx.net>
2007-09-04 14:11 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 14:36 ` Alvaro Herrera <alvherre@commandprompt.com>
2007-09-04 16:19 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-09-04 16:37 ` Oleg Bartunov <oleg@sai.msu.su>
2007-09-04 15:04 ` Peter Eisentraut <peter_e@gmx.net>
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