Re: "writable CTEs"

Peter Geoghegan wrote:

> It's worth noting that officially (i.e. in the docs), we don't even
> call CTEs CTEs at any point. We call them WITH queries. I think
> that that's a mistake because we call them CTEs everywhere else.
>
> Is there interest in correcting this, by putting "CTEs" or "Common
> table expressions" in parenthesis after "WITH queries" in the docs
> at certain select places? I could write a documentation patch.

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.

-Kevin

On 28 December 2010 01:09, Kevin Grittner <Kevin(dot)Grittner(at)wicourts(dot)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

On Tue, Dec 28, 2010 at 03:49:16AM +0000, Peter Geoghegan wrote:
> On 28 December 2010 01:09, Kevin Grittner <Kevin(dot)Grittner(at)wicourts(dot)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 <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david(dot)fetter(at)gmail(dot)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

On Tue, Dec 28, 2010 at 12:45 AM, David Fetter <david(at)fetter(dot)org> wrote:
> I don't see how people can be relying on links to 9.1-to-be's
> documentation.

Well, it's always handy when the filenames are the same across
versions. Ever looked at the 9.0 documentation for something and then
modified the URL to see what it looked like in 8.1 or something?

>> 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. :)

No, actually I think Peter has it right. A query with one or more
common table expressions is a WITH-query. This is a subtle difference
but could affect the way that things are phrased in the documentation.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Excerpts from David Fetter's message of mar dic 28 02:45:11 -0300 2010:
> On Tue, Dec 28, 2010 at 03:49:16AM +0000, Peter Geoghegan wrote:

> > 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.

If you change it to give it a new name, the old name disappears.
It's a little thing but we've gotten complaints about links disappearing
from one version to another. (Personally this has given me reason to
think that the "/current" link to docs are a bad idea).

--
Álvaro Herrera <alvherre(at)commandprompt(dot)com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On 28 December 2010 12:09, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> On Tue, Dec 28, 2010 at 12:45 AM, David Fetter <david(at)fetter(dot)org> wrote:
>> I don't see how people can be relying on links to 9.1-to-be's
>> documentation.
>
> Well, it's always handy when the filenames are the same across
> versions.  Ever looked at the 9.0 documentation for something and then
> modified the URL to see what it looked like in 8.1 or something?

I do this all the time. Anyway, I intend for this doc patch to be
backported to 8.4 as a bugfix, which is part of the reason why it
isn't invasive - it's just a clarification. Clearly if it makes sense
for 9.1, it makes just as much sense for 9.0 and 8.4.

> No, actually I think Peter has it right.  A query with one or more
> common table expressions is a WITH-query.  This is a subtle difference
> but could affect the way that things are phrased in the documentation.

Attached is a new patch written with this consideration in mind. It
also has an acronym.sgml entry for CTE, which was absent from my
earlier patch. I think David actually agreed that I was right to have
doubts.

--
Regards,
Peter Geoghegan

On Tue, Dec 28, 2010 at 07:09:14AM -0500, Robert Haas wrote:
> On Tue, Dec 28, 2010 at 12:45 AM, David Fetter <david(at)fetter(dot)org> wrote:
> > I don't see how people can be relying on links to 9.1-to-be's
> > documentation.
>
> Well, it's always handy when the filenames are the same across
> versions. Ever looked at the 9.0 documentation for something and then
> modified the URL to see what it looked like in 8.1 or something?

I have occasionally wondered if it would be possible to include in the
SGML references to the same (or equivalent) page in previous versions,
so that each page in the docs could reference the equivalent page in
other versions. That would be extremely useful when trying to work out
what works in your particular version.

I've never done anything serious with SGML, but it'd be cool if it was
possible.

Have a nice day,
--
Martijn van Oosterhout <kleptog(at)svana(dot)org> http://svana.org/kleptog/
> Patriotism is when love of your own people comes first; nationalism,
> when hate for people other than your own comes first.
> - Charles de Gaulle

Hello,

I have added my common table expressions docpatch to the 2011-01 commitfest:

https://commitfest.postgresql.org/action/patch_view?id=476

I think that we need to get this resolved.

--
Regards,
Peter Geoghegan

Greetings,

* Peter Geoghegan (peter(dot)geoghegan86(at)gmail(dot)com) wrote:
> I do this all the time. Anyway, I intend for this doc patch to be
> backported to 8.4 as a bugfix, which is part of the reason why it
> isn't invasive - it's just a clarification. Clearly if it makes sense
> for 9.1, it makes just as much sense for 9.0 and 8.4.

I agree with the patch, in general, as well as the recommendation to
back-port it. I reviewed it and didn't find any issues (though I
couldn't figure out the right magic things to install to actually build
the docs.. :( ). The only minor change I made was to capitalize Common
Table Expressions (having it as an acronym w/o capitalizing the full
name seemed odd to me..).

Updated patch attached. Marking as ready for committer.

commit 91e9e9285752c9fbe0c222708a10a301731594c8
Author: Stephen Frost <sfrost(at)snowman(dot)net>
Date: Wed Jan 19 20:56:44 2011 -0500

Update WITH documentation to capitalize acronym

Common Table Expressions, being a 'proper' name and having an
acronym associated with them, really should be capitalized. This
patch makes that change in the WITH documentation.

commit 9e4565cc97b81fd6b3f96d8e346bcb7ee6e8878e
Author: Stephen Frost <sfrost(at)snowman(dot)net>
Date: Wed Jan 19 20:54:47 2011 -0500

Add CTE as an acryonym and clarify WITH docs

This patch adds CTE to the list of acronyms and then updates the
WITH documentation to note that WITH queries are also known as
CTEs.

Patch by Peter Geoghegan

Thanks,

Stephen

On Wed, Jan 19, 2011 at 9:13 PM, Stephen Frost <sfrost(at)snowman(dot)net> wrote:
> Greetings,
>
> * Peter Geoghegan (peter(dot)geoghegan86(at)gmail(dot)com) wrote:
>> I do this all the time. Anyway, I intend for this doc patch to be
>> backported to 8.4 as a bugfix, which is part of the reason why it
>> isn't invasive - it's just a clarification. Clearly if it makes sense
>> for 9.1, it makes just as much sense for 9.0 and 8.4.
>
> I agree with the patch, in general, as well as the recommendation to
> back-port it.  I reviewed it and didn't find any issues (though I
> couldn't figure out the right magic things to install to actually build
> the docs.. :( ).  The only minor change I made was to capitalize Common
> Table Expressions (having it as an acronym w/o capitalizing the full
> name seemed odd to me..).
>
> Updated patch attached.  Marking as ready for committer.

Committed.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

I think that a major goal of the DocBook format is that it separates
content from presentation, so whatever tool is used to render that
content as HTML for .org isn't necessarily publicly available.

--
Regards,
Peter Geoghegan

On Thu, Jan 20, 2011 at 03:48, Peter Geoghegan
<peter(dot)geoghegan86(at)gmail(dot)com> wrote:
> I think that a major goal of the DocBook format is that it separates
> content from presentation, so whatever tool is used to render that
> content as HTML for .org isn't necessarily publicly available.

Sure it is. And FWIW, it just uses the HTML generated by the docbook
tools, we don't actually work off the SGML.

The current version can be found at
https://pgweb.postgresql.org/browser/trunk/portal/tools/docs.

The new, upcoming, version that does things like attempt-to-make-xhtml
is at http://git.postgresql.org/gitweb?p=pgweb.git;a=blob;f=tools/docs/docload.py;h=5abc2f734003d28836a85fbc0ec6c01804937af8;hb=a3523e2ba8a250950a928879ae7fa5c0a8a46d94

You will quickly notice they do basically nothing other than read in
the HTML, and then "copy/paste" it into the current framework.

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/