On Tue, Dec 28, 2010 at 03:49:16AM +0000, Peter Geoghegan wrote: > 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?
I don't see how people can be relying on links to 9.1-to-be's documentation. > 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? They are. :) Cheers, David. -- David Fetter <da...@fetter.org> http://fetter.org/ Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter Skype: davidfetter XMPP: david.fet...@gmail.com iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics Remember to vote! Consider donating to Postgres: http://www.postgresql.org/about/donate -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
