On 28 December 2010 01:09, Kevin Grittner <Kevin.Grittner@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
