Update hstore % Doc
Hackers,
I noticed that the hstore docs still document the => operator instead of %. This patch changes that. It also updates the first examples to us full SQL statements, because otherwise the use of => without surrounding single quotes was confusing.
Best,
David
Attachments:
hstoredoc.patchapplication/octet-stream; name=hstoredoc.patch; x-unix-mode=0644Download
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index d5e11bd..a744cb3 100644
*** a/doc/src/sgml/hstore.sgml
--- b/doc/src/sgml/hstore.sgml
***************
*** 25,33 ****
<replaceable>value</> pairs separated by commas. Some examples:
<synopsis>
! k => v
! foo => bar, baz => whatever
! "1-a" => "anything at all"
</synopsis>
The order of the pairs is not significant (and may not be reproduced on
--- 25,33 ----
<replaceable>value</> pairs separated by commas. Some examples:
<synopsis>
! SELECT k % v;
! SELECT 'foo => bar, baz => whatever';
! SELECT '"1-a" => "anything at all"
</synopsis>
The order of the pairs is not significant (and may not be reproduced on
*************** key => NULL
*** 114,122 ****
</row>
<row>
! <entry><type>text</> <literal>=></> <type>text</></entry>
<entry>make single-pair <type>hstore</></entry>
! <entry><literal>'a' => 'b'</literal></entry>
<entry><literal>"a"=>"b"</literal></entry>
</row>
--- 114,122 ----
</row>
<row>
! <entry><type>text</> <literal>%</> <type>text</></entry>
<entry>make single-pair <type>hstore</></entry>
! <entry><literal>'a' % 'b'</literal></entry>
<entry><literal>"a"=>"b"</literal></entry>
</row>
"David E. Wheeler" <david.wheeler@pgexperts.com> writes:
I noticed that the hstore docs still document the => operator instead
of %. This patch changes that.
It looks to me like you are changing the examples of the I/O
representation ... which did NOT change.
regards, tom lane
On Aug 6, 2010, at 3:16 PM, Tom Lane wrote:
I noticed that the hstore docs still document the => operator instead
of %. This patch changes that.It looks to me like you are changing the examples of the I/O
representation ... which did NOT change.
Hrm? The first few examples at the top? I find them confusing because there are no single quotes around them, so they look like the use of the deprecated => operator (especially the first two). Just look at:
http://developer.postgresql.org/pgdocs/postgres/hstore.html
Maybe that's standard in the docs, but it seems weird to me. It's a minor point, though.
We definitely need to document the `text % text` constructor rather than the deprecated `text => text` constructor.
And I hate to say it, but % is awful. Sorry, I know I'm probably opening a can of worms here, and I did finally push % after all the arguments, but coming back to it fresh it just looks bizarre to me. Maybe that ship has sailed, though, and I'm just being difficult.
Best,
David
"David E. Wheeler" <david.wheeler@pgexperts.com> writes:
On Aug 6, 2010, at 3:16 PM, Tom Lane wrote:
It looks to me like you are changing the examples of the I/O
representation ... which did NOT change.
Hrm? The first few examples at the top? I find them confusing because there are no single quotes around them, so they look like the use of the deprecated => operator (especially the first two). Just look at:
Yeah, but there's a sentence in front of them that says specifically
that these are examples of the text representation, not pieces of SQL.
And I hate to say it, but % is awful.
Yeah, I know, but you can't have =>. Unless you can persuade the SQL
committee to back off their syntax choice for parameters. (:= would
have been a lot better ...)
regards, tom lane
"David E. Wheeler" <david.wheeler@pgexperts.com> writes:
We definitely need to document the `text % text` constructor
BTW, there isn't any % constructor anymore --- we agreed to provide
only the hstore(text, text) constructor.
regards, tom lane
On Aug 6, 2010, at 3:38 PM, Tom Lane wrote:
We definitely need to document the `text % text` constructor
BTW, there isn't any % constructor anymore --- we agreed to provide
only the hstore(text, text) constructor.
Oh, I must've been looking at an older checkout, then. Never mind.
Best,
David
On Fri, Aug 6, 2010 at 6:49 PM, David E. Wheeler
<david.wheeler@pgexperts.com> wrote:
On Aug 6, 2010, at 3:38 PM, Tom Lane wrote:
We definitely need to document the `text % text` constructor
BTW, there isn't any % constructor anymore --- we agreed to provide
only the hstore(text, text) constructor.Oh, I must've been looking at an older checkout, then. Never mind.
And also - it was never the constructor. It was briefly the slice operator.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company