Re: Operator class parameters and sgml docs
On Sun, Jun 21, 2020 at 2:28 AM Justin Pryzby wrote: > And a couple more in spgist.sgml (some of which were not added by this patch). Pushed, thanks! -- Regards, Alexander Korotkov
Re: Operator class parameters and sgml docs
And a couple more in spgist.sgml (some of which were not added by this patch). >From ed7bd93c6a6953d8626331de9bcba126ddb79b54 Mon Sep 17 00:00:00 2001 From: Justin Pryzby Date: Sat, 20 Jun 2020 16:37:51 -0500 Subject: [PATCH v2] Language fixen for 15cb2bd27009f73a84a35c2ba60fdd105b4bf263 --- doc/src/sgml/brin.sgml | 12 ++-- doc/src/sgml/btree.sgml | 12 ++-- doc/src/sgml/gin.sgml| 10 +- doc/src/sgml/gist.sgml | 18 +- doc/src/sgml/spgist.sgml | 12 ++-- doc/src/sgml/xindex.sgml | 18 +- 6 files changed, 41 insertions(+), 41 deletions(-) diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index d7f1af7819..4c5eeb875f 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -562,7 +562,7 @@ typedef struct BrinOpcInfo - Optionally, an operator class for BRIN can supply the + An operator class for BRIN can optionally specify the following method: @@ -570,22 +570,22 @@ typedef struct BrinOpcInfo void options(local_relopts *relopts) - Defines set of user-visible parameters that control operator class + Defines a set of user-visible parameters that control operator class behavior. - The options function has given pointer to + The options function is passed a pointer to a local_relopts struct, which needs to be filled with a set of operator class specific options. The options - can be accessed from other support functions using + can be accessed from other support functions using the PG_HAS_OPCLASS_OPTIONS() and PG_GET_OPCLASS_OPTIONS() macros. - Since both key extraction for indexed value and representation of the - key in GIN are flexible, it may depends on + Since both key extraction of indexed values and representation of the + key in GIN are flexible, they may depend on user-specified parameters. diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml index 661e7ab650..6c2fd453f5 100644 --- a/doc/src/sgml/btree.sgml +++ b/doc/src/sgml/btree.sgml @@ -557,7 +557,7 @@ equalimage(opcintype oid) returns bool Optionally, a B-tree operator family may provide options (operator class specific options) support functions, registered under support - function number 5. These functions define set of user-visible + function number 5. These functions define a set of user-visible parameters that control operator class behavior. @@ -566,19 +566,19 @@ equalimage(opcintype oid) returns bool options(relopts local_relopts *) returns void - The function has given pointer to local_relopts + The function is passed a pointer to a local_relopts struct, which needs to be filled with a set of operator class specific options. The options can be accessed from other support - functions using PG_HAS_OPCLASS_OPTIONS() and + functions using the PG_HAS_OPCLASS_OPTIONS() and PG_GET_OPCLASS_OPTIONS() macros. - Currently, no B-Tree operator class has options + Currently, no B-Tree operator class has an options support function. B-tree doesn't allow flexible representation of keys like GiST, SP-GiST, GIN and BRIN do. So, options - probably doesn't have much usage in current shape of B-tree index + probably doesn't have much application in the current B-tree index access method. Nevertheless, this support function was added to B-tree - for uniformity, and probably it will found its usage during further + for uniformity, and will probably find uses during further evolution of B-tree in PostgreSQL. diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index d85e7c8796..7a8c18a449 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -411,17 +411,17 @@ - The options function has given pointer to + The options function is passed a pointer to a local_relopts struct, which needs to be - filled with s set of operator class specific options. The options - can be accessed from other support functions using + filled with a set of operator class specific options. The options + can be accessed from other support functions using the PG_HAS_OPCLASS_OPTIONS() and PG_GET_OPCLASS_OPTIONS() macros. - Since both key extraction for indexed value and representation of the - key in GIN are flexible, it may depends on + Since both key extraction of indexed values and representation of the + key in GIN are flexible, they may depend on user-specified parameters. diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml index 31c28fdb61..5d970ee9f2 100644 --- a/doc/src/sgml/gist.sgml +++ b/doc/src/sgml/gist.sgml @@ -946,7 +946,7 @@
Re: Operator class parameters and sgml docs
On Sat, Jun 20, 2020 at 01:55:33PM +0300, Alexander Korotkov wrote:
> On Thu, Jun 18, 2020 at 8:06 PM Alexander Korotkov
> wrote:
> > On Wed, Jun 17, 2020 at 2:00 PM Alexander Korotkov
> > wrote:
> > > On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan wrote:
> > > > On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov
> > > > wrote:
> > > > > Thank you for patience. The documentation patch is attached. I think
> > > > > it requires review by native english speaker.
...
> > > Fixed, thanks!
> > >
> > > > It's very hard to write documentation like this, even for native
> > > > English speakers. I think that it's important to have something in
> > > > place, though. The GiST example helps a lot.
...
> > I'm going to push this patch if there are no objections. I'm almost
> > sure that documentation of opclass options will require further
> > adjustments. However, I think the current patch makes it better, not
> > worse.
>
> So, pushed!
Find attached some language review of user-facing docs.
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index d7f1af7819..4c5eeb875f 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -562,7 +562,7 @@ typedef struct BrinOpcInfo
[-Optionally, an-]{+An+} operator class for BRIN can
[-supply-]{+optionally specify+} the
following method:
@@ -570,22 +570,22 @@ typedef struct BrinOpcInfo
void options(local_relopts *relopts)
Defines {+a+} set of user-visible parameters that control operator class
behavior.
The options function [-has given-]{+is passed a+}
pointer to {+a+}
local_relopts struct, which needs to be
filled with a set of operator class specific options. The options
can be accessed from other support functions using {+the+}
PG_HAS_OPCLASS_OPTIONS() and
PG_GET_OPCLASS_OPTIONS() macros.
Since both key extraction [-for-]{+of+} indexed [-value-]{+values+} and
representation of the
key in GIN are flexible, [-it-]{+they+} may
[-depends-]{+depend+} on
user-specified parameters.
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 2c4dd48ea3..b17b166e84 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -557,7 +557,7 @@ equalimage(opcintype
oid) returns bool
Optionally, a B-tree operator family may provide
options (operator class specific
options) support functions, registered under support
function number 5. These functions define {+a+} set of user-visible
parameters that control operator class behavior.
@@ -566,19 +566,19 @@ equalimage(opcintype
oid) returns bool
options(relopts local_relopts *)
returns void
The function [-has given-]{+is passed a+} pointer to {+a+}
local_relopts
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other support
functions using {+the+} PG_HAS_OPCLASS_OPTIONS() and
PG_GET_OPCLASS_OPTIONS() macros.
Currently, no B-Tree operator class has {+an+} options
support function. B-tree doesn't allow flexible representation of keys
like GiST, SP-GiST, GIN and BRIN do. So, options
probably doesn't have much [-usage-]{+application+} in {+the+}
current[-shape of-] B-tree index
access method. Nevertheless, this support function was added to B-tree
for uniformity, and[-probably it-] will [-found its usage-]{+probably find
uses+} during further
evolution of B-tree in PostgreSQL.
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml
index d85e7c8796..7a8c18a449 100644
--- a/doc/src/sgml/gin.sgml
+++ b/doc/src/sgml/gin.sgml
@@ -411,17 +411,17 @@
The options function [-has given-]{+is passed a+}
pointer to {+a+}
local_relopts struct, which needs to be
filled with [-s-]{+a+} set of operator class specific options. The
options
can be accessed from other support functions using {+the+}
PG_HAS_OPCLASS_OPTIONS() and
PG_GET_OPCLASS_OPTIONS() macros.
Since both key extraction [-for-]{+of+} indexed [-value-]{+values+} and
representation of the
key in GIN are flexible, [-it-]{+they+} may
[-depends-]{+depend+} on
user-specified parameters.
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 31c28fdb61..5d970ee9f2 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -946,7 +946,7 @@ my_fetch(PG_FUNCTION_ARGS)
options
Allows [-defintion-]{+definition+} of user-visible parameters that
control operator
class behavior.
@@ -962,16 +962,16 @@ LANGUAGE C STRICT;
The function [-has given-]{+is passed a+} pointer to {+a+}
local_relopts
struct, which needs to be filled with a set of operator class
specific options. The options can be accessed from other
Re: Operator class parameters and sgml docs
On Sat, Jun 20, 2020 at 10:15 PM Peter Geoghegan wrote: > On Sat, Jun 20, 2020 at 3:55 AM Alexander Korotkov > wrote: > > So, pushed! > > Noticed one small thing. You forgot to update this part from the B-Tree docs: > > "As shown in Table 37.9, btree defines one required and three optional > support functions. The four user-defined methods are:" Thanks! I've also spotted a similar issue in SP-GiST. Fix for both is pushed. -- Regards, Alexander Korotkov
Re: Operator class parameters and sgml docs
On Sat, Jun 20, 2020 at 3:55 AM Alexander Korotkov wrote: > So, pushed! Noticed one small thing. You forgot to update this part from the B-Tree docs: "As shown in Table 37.9, btree defines one required and three optional support functions. The four user-defined methods are:" Thanks -- Peter Geoghegan
Re: Operator class parameters and sgml docs
On Thu, Jun 18, 2020 at 8:06 PM Alexander Korotkov wrote: > On Wed, Jun 17, 2020 at 2:00 PM Alexander Korotkov > wrote: > > On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan wrote: > > > On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov > > > wrote: > > > > Thank you for patience. The documentation patch is attached. I think > > > > it requires review by native english speaker. > > > > > > * "...paramaters that controls" should be "...paramaters that control". > > > > > > * "with set of operator class specific option" should be "with a set > > > of operator class specific options". > > > > > > * "The options could be accessible from each support function" should > > > be "The options can be accessed from other support functions" > > > > Fixed, thanks! > > > > > It's very hard to write documentation like this, even for native > > > English speakers. I think that it's important to have something in > > > place, though. The GiST example helps a lot. > > > > I've added a complete example for defining a set of parameters and > > accessing them from another support function to the GiST > > documentation. > > I'm going to push this patch if there are no objections. I'm almost > sure that documentation of opclass options will require further > adjustments. However, I think the current patch makes it better, not > worse. So, pushed! -- Regards, Alexander Korotkov
Re: Operator class parameters and sgml docs
On Wed, Jun 17, 2020 at 2:00 PM Alexander Korotkov wrote: > On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan wrote: > > On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov > > wrote: > > > Thank you for patience. The documentation patch is attached. I think > > > it requires review by native english speaker. > > > > * "...paramaters that controls" should be "...paramaters that control". > > > > * "with set of operator class specific option" should be "with a set > > of operator class specific options". > > > > * "The options could be accessible from each support function" should > > be "The options can be accessed from other support functions" > > Fixed, thanks! > > > It's very hard to write documentation like this, even for native > > English speakers. I think that it's important to have something in > > place, though. The GiST example helps a lot. > > I've added a complete example for defining a set of parameters and > accessing them from another support function to the GiST > documentation. I'm going to push this patch if there are no objections. I'm almost sure that documentation of opclass options will require further adjustments. However, I think the current patch makes it better, not worse. -- Alexander Korotkov Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
Re: Operator class parameters and sgml docs
On Wed, Jun 17, 2020 at 2:50 AM Peter Geoghegan wrote: > On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov > wrote: > > Thank you for patience. The documentation patch is attached. I think > > it requires review by native english speaker. > > * "...paramaters that controls" should be "...paramaters that control". > > * "with set of operator class specific option" should be "with a set > of operator class specific options". > > * "The options could be accessible from each support function" should > be "The options can be accessed from other support functions" Fixed, thanks! > It's very hard to write documentation like this, even for native > English speakers. I think that it's important to have something in > place, though. The GiST example helps a lot. I've added a complete example for defining a set of parameters and accessing them from another support function to the GiST documentation. -- Alexander Korotkov Postgres Professional: http://www.postgrespro.com The Russian Postgres Company opclass_options_doc_2.patch Description: Binary data
Re: Operator class parameters and sgml docs
On Tue, Jun 16, 2020 at 4:24 AM Alexander Korotkov wrote: > Thank you for patience. The documentation patch is attached. I think > it requires review by native english speaker. * "...paramaters that controls" should be "...paramaters that control". * "with set of operator class specific option" should be "with a set of operator class specific options". * "The options could be accessible from each support function" should be "The options can be accessed from other support functions" (At least I think that that's what you meant) It's very hard to write documentation like this, even for native English speakers. I think that it's important to have something in place, though. The GiST example helps a lot. -- Peter Geoghegan
Re: Operator class parameters and sgml docs
On Thu, May 28, 2020 at 11:02 PM Alexander Korotkov wrote: > > On Thu, May 21, 2020 at 3:17 AM Alexander Korotkov > wrote: > > > > On Thu, May 21, 2020 at 12:37 AM Peter Geoghegan wrote: > > > Commit 911e7020770 added a variety of new support routines to index > > > AMs. For example, it added a support function 5 to btree (see > > > BTOPTIONS_PROC), but didn't document this alongside the other support > > > functions in btree.sgml. > > > > > > It looks like the new support functions are fundamentally different to > > > the existing ones in that they exist only as a way of supplying > > > parameters to other support functions. The idea was to preserve > > > compatibility with the old support function signatures. Even still, I > > > think that the new support functions should get some mention alongside > > > the older support functions. > > > > > > I also wonder whether or not xindex.sgml needs to be updated to > > > account for opclass parameters. > > > > Thank you for pointing. I'm going to take a look on this in next few days. > > I'm sorry for the delay. I was very busy with various stuff. I'm > going to post docs patch next week. Thank you for patience. The documentation patch is attached. I think it requires review by native english speaker. -- Alexander Korotkov Postgres Professional: http://www.postgrespro.com The Russian Postgres Company opclass_options_doc.patch Description: Binary data
Re: Operator class parameters and sgml docs
On Thu, May 21, 2020 at 3:17 AM Alexander Korotkov wrote: > > On Thu, May 21, 2020 at 12:37 AM Peter Geoghegan wrote: > > Commit 911e7020770 added a variety of new support routines to index > > AMs. For example, it added a support function 5 to btree (see > > BTOPTIONS_PROC), but didn't document this alongside the other support > > functions in btree.sgml. > > > > It looks like the new support functions are fundamentally different to > > the existing ones in that they exist only as a way of supplying > > parameters to other support functions. The idea was to preserve > > compatibility with the old support function signatures. Even still, I > > think that the new support functions should get some mention alongside > > the older support functions. > > > > I also wonder whether or not xindex.sgml needs to be updated to > > account for opclass parameters. > > Thank you for pointing. I'm going to take a look on this in next few days. I'm sorry for the delay. I was very busy with various stuff. I'm going to post docs patch next week. -- Alexander Korotkov Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
Re: Operator class parameters and sgml docs
Hi, Peter! On Thu, May 21, 2020 at 12:37 AM Peter Geoghegan wrote: > Commit 911e7020770 added a variety of new support routines to index > AMs. For example, it added a support function 5 to btree (see > BTOPTIONS_PROC), but didn't document this alongside the other support > functions in btree.sgml. > > It looks like the new support functions are fundamentally different to > the existing ones in that they exist only as a way of supplying > parameters to other support functions. The idea was to preserve > compatibility with the old support function signatures. Even still, I > think that the new support functions should get some mention alongside > the older support functions. > > I also wonder whether or not xindex.sgml needs to be updated to > account for opclass parameters. Thank you for pointing. I'm going to take a look on this in next few days. -- Alexander Korotkov Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
Operator class parameters and sgml docs
Commit 911e7020770 added a variety of new support routines to index AMs. For example, it added a support function 5 to btree (see BTOPTIONS_PROC), but didn't document this alongside the other support functions in btree.sgml. It looks like the new support functions are fundamentally different to the existing ones in that they exist only as a way of supplying parameters to other support functions. The idea was to preserve compatibility with the old support function signatures. Even still, I think that the new support functions should get some mention alongside the older support functions. I also wonder whether or not xindex.sgml needs to be updated to account for opclass parameters. -- Peter Geoghegan
