Thread

1. Re: "writable CTEs"

   Kevin Grittner <kevin.grittner@wicourts.gov> — 2010-12-28T01:09:41Z

   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
   
   

2. Re: "writable CTEs"

   Peter Geoghegan <peter.geoghegan86@gmail.com> — 2010-12-28T03:49:16Z

   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
   

3. Re: "writable CTEs"

   David Fetter <david@fetter.org> — 2010-12-28T05:45:11Z

   On Tue, Dec 28, 2010 at 03:49:16AM +0000, Peter Geoghegan wrote:
   > 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?
   
   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@fetter.org> http://fetter.org/
   Phone: +1 415 235 3778  AIM: dfetter666  Yahoo!: dfetter
   Skype: davidfetter      XMPP: david.fetter@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
   
   

4. Re: "writable CTEs"

   Robert Haas <robertmhaas@gmail.com> — 2010-12-28T12:09:14Z

   On Tue, Dec 28, 2010 at 12:45 AM, David Fetter <david@fetter.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
   
   

5. Re: "writable CTEs"

   Alvaro Herrera <alvherre@commandprompt.com> — 2010-12-28T13:14:46Z

   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@commandprompt.com>
   The PostgreSQL Company - Command Prompt, Inc.
   PostgreSQL Replication, Consulting, Custom Development, 24x7 support
   
   

6. Re: "writable CTEs"

   Peter Geoghegan <peter.geoghegan86@gmail.com> — 2010-12-28T14:08:36Z

   On 28 December 2010 12:09, Robert Haas <robertmhaas@gmail.com> wrote:
   > On Tue, Dec 28, 2010 at 12:45 AM, David Fetter <david@fetter.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
   

7. Re: "writable CTEs"

   Martijn van Oosterhout <kleptog@svana.org> — 2010-12-29T21:28:27Z

   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@fetter.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@svana.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
   

8. Re: "writable CTEs"

   Peter Geoghegan <peter.geoghegan86@gmail.com> — 2011-01-05T23:25:37Z

   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
   
   

9. REVIEW: "writable CTEs" - doc patch

   Stephen Frost <sfrost@snowman.net> — 2011-01-20T02:13:36Z

   Greetings,
   
   * Peter Geoghegan (peter.geoghegan86@gmail.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@snowman.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@snowman.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
   

10. Re: REVIEW: "writable CTEs" - doc patch

    Peter Geoghegan <peter.geoghegan86@gmail.com> — 2011-01-20T02:48:19Z

    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
    
    

11. Re: REVIEW: "writable CTEs" - doc patch

    Magnus Hagander <magnus@hagander.net> — 2011-01-21T13:13:02Z

    On Thu, Jan 20, 2011 at 03:48, Peter Geoghegan
    <peter.geoghegan86@gmail.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/