On 28 December 2010 01:09, Kevin Grittner <kevin.gritt...@wicourts.gov> wrote:
> Personally, I think it's worth fixing. This sort of disjunction
> between code and documentation can cause confusing for someone
> trying to get started on hacking. It is an exception to the
> otherwise excellent documentation of both the product and the code.
Hmm. Having looked at the relevant sgml file, queries.sgml, common
table expressions appear at one point:
<indexterm>
<primary>common table expression</primary>
<see>WITH</see>
</indexterm>
This indicates that the term common table expression should be indexed
(the dead tree way), which isn't much use for the majority of users
that access the docs on the web. This term doesn't appear in the html
source. Perhaps whatever infrastructure we use to render the sgml
files as html for dot org should produce keyword meta tags for indexed
terms, in case anyone searches the docs using Altavista. More
seriously, if we did this I imagine we'd see WITH Queries (for
example) in the first page of results if we search for "common table
expression" from dot org directly. The fact that whatever docbook tool
we use doesn't already do this does suggests that it might not be such
a good idea. It may not be worth the effort. I've cc'd Thom Brown to
see what he thinks.
Attached documentation patch should make things clearer. I haven't
changed the "queries-with" section to
"queries-common-table-expression" per David's suggestion for the sake
of stability. I hesitate to change it without reaching a consensus -
will this break a lot of links?
The main change I've made is: "WITH queries, also referred to as
Common table expressions or CTEs, provide a way to write subqueries
for use as part of a larger query". I'm concerned that this might not
be strictly correct, because the term "WITH query" may not be exactly
equivalent to the term "CTE" - WITH queries are comprised of one or
more CTEs, plus a main query. Or are they?
Comments?
--
Regards,
Peter Geoghegan
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index f6e081e..45df052 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -1525,7 +1525,7 @@ SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression
<sect1 id="queries-with">
- <title><literal>WITH</literal> Queries</title>
+ <title><literal>WITH</literal> Queries (Common Table Expressions)</title>
<indexterm zone="queries-with">
<primary>WITH</primary>
@@ -1538,10 +1538,10 @@ SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression
</indexterm>
<para>
- <literal>WITH</> provides a way to write subqueries for use in a larger
- query. The subqueries can be thought of as defining
- temporary tables that exist just for this query. One use of this feature
- is to break down complicated queries into simpler parts. An example is:
+ <literal>WITH</> queries, also referred to as Common table expressions or
+ <acronym>CTE</acronym>s, provide a way to write subqueries for use as part of a larger query.
+ The subqueries can be thought of as defining temporary tables that exist just for this query.
+ One use of this feature is to break down complicated queries into simpler parts. An example is:
<programlisting>
WITH regional_sales AS (
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
