Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jmmo5-0003pD-CW for pgsql-hackers@arkaria.postgresql.org; Sat, 20 Jun 2020 23:21:53 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jmmo4-0006kI-6F for pgsql-hackers@arkaria.postgresql.org; Sat, 20 Jun 2020 23:21:52 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jmmo3-0006kB-Gw for pgsql-hackers@lists.postgresql.org; Sat, 20 Jun 2020 23:21:51 +0000 Received: from mail-io1-xd43.google.com ([2607:f8b0:4864:20::d43]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jmmo0-0004i0-F8 for pgsql-hackers@postgresql.org; Sat, 20 Jun 2020 23:21:50 +0000 Received: by mail-io1-xd43.google.com with SMTP id c4so2032389iot.4 for ; Sat, 20 Jun 2020 16:21:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=telsasoft-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=fCBYcYJjuurBqKjlMDB1Ji3k6fpXICzcahifVOtCuxY=; b=1+RXnLLqJ5zPtFn1o5yBoeKr7ZHB07GzKWItI9lthF2X/wcjnWoByzF1BVIpZs3du6 sSaOxpNRm85gyI8QVTktDRM9VAXpVW9Ho+PHvFBbh3pNINFT4vk/zH25cSxXC1RoNJyV V0oC/VJ1kc79gTJHdL46tBRSolUJNUBzzkK6Cz6YROj2rnoX5Fg11qz7pfzcBlcr7iDi XP17Zet4B9GXW7WaSYPJWvj0OP4+IcwQbdZcucv2drdrdfRtqxNITOfrixnQOsLjVXhs Pk/GxDI1iHAXqHy6PsvFb8080R1QAgMGyf+caw+/seDzkxaIPyOM5QuVDJ5xiS1oOQbd mdpw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=fCBYcYJjuurBqKjlMDB1Ji3k6fpXICzcahifVOtCuxY=; b=hF5aZ8UEI62hdytfxa/W4Z8NsSsF7KvRLRhKqQ15IzBKV9zRS5lk4secqaBIzKoSjW h05z7RrPxzUgrbLfsT57VVSDkvoJ0BtvR+IBLX8gIedsfof4McfNsr17AcgGTXYKP0FE S+SeCWgZnZWl+aNGKjfMjGm3l69D4LIyjoLbb5pM1k0qEeqlNKTyBC5/22YThy6veRqc 3ipvh0Z/LnZg/zsCayXbuUXEOcDIXgUeaXs7meUge1OH1FZ764D8OnVBHMSsaSeA5NTX 5V6Y7MmJjpg3zLUH3bU6wWNMVRjWmanlfqR6v6orCbKiJLoXZce/SIERTPB1JqAmfoGe hPrw== X-Gm-Message-State: AOAM533aw/vlnAsirDY3NEYWCN3DTg//OeAT3jruRsnbjee2c8xm4NNI ZZBdJ53Mew2m908IE9NrbbXIOg== X-Google-Smtp-Source: ABdhPJz74CIH/qYWuX+gs+3H93LvobluoXnWlL7ON/wLHxnpy0E0lBljsdUKmnXHa4mEwWnQaYXHYA== X-Received: by 2002:a05:6602:2f0a:: with SMTP id q10mr11814335iow.134.1592695307606; Sat, 20 Jun 2020 16:21:47 -0700 (PDT) Received: from pryzbyj.telsasoft (charmander.telsasoft.com. [50.244.222.1]) by smtp.gmail.com with ESMTPSA id n7sm5401829ile.76.2020.06.20.16.21.46 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 20 Jun 2020 16:21:46 -0700 (PDT) Received: by pryzbyj.telsasoft (Postfix, from userid 1000) id 89DFE800A36; Sat, 20 Jun 2020 18:21:45 -0500 (CDT) Date: Sat, 20 Jun 2020 18:21:45 -0500 From: Justin Pryzby To: Alexander Korotkov Cc: Peter Geoghegan , pgsql-hackers@postgresql.org Subject: Re: Operator class parameters and sgml docs Message-ID: <20200620232145.GB17995@telsasoft.com> References: MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="W2ydbIOJmkm74tJ2" Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.9.4 (2018-02-28) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --W2ydbIOJmkm74tJ2 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 support functions using {+the+} PG_HAS_OPCLASS_OPTIONS() and PG_GET_OPCLASS_OPTIONS() macros. [-The sample-]{+An example+} implementation of [-my_option()-]{+my_options()+} and parameters [-usage-] [- in the another-]{+use+} {+ from other+} support [-function-]{+functions+} are given below: typedef enum MyEnumType @@ -990,7 +990,7 @@ typedef struct int str_param; /* string parameter */ } MyOptionsStruct; /* String [-representations for-]{+representation of+} enum values */ static relopt_enum_elt_def myEnumValues[] = { {"on", MY_ENUM_ON}, @@ -1002,7 +1002,7 @@ static relopt_enum_elt_def myEnumValues[] = static char *str_param_default = "default"; /* * Sample [-validatior:-]{+validator:+} checks that string is not longer than 8 bytes. */ static void validate_my_string_relopt(const char *value) @@ -1090,8 +1090,8 @@ my_compress(PG_FUNCTION_ARGS) Since the representation of the key in GiST is flexible, it may [-depends-]{+depend+} on user-specified parameters. For [-instace,-]{+instance,+} the length of key signature may be [-such parameter.-]{+specified.+} See gtsvector_options() for example. diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml index 03f914735b..1395dbaf88 100644 --- a/doc/src/sgml/spgist.sgml +++ b/doc/src/sgml/spgist.sgml @@ -895,16 +895,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 support functions using {+the+} PG_HAS_OPCLASS_OPTIONS() and PG_GET_OPCLASS_OPTIONS() macros. Since the representation of the key in SP-GiST is flexible, it may [-depends-]{+depend+} on user-specified parameters. diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml index 0e4587a81b..2cfd71b5b7 100644 --- a/doc/src/sgml/xindex.sgml +++ b/doc/src/sgml/xindex.sgml @@ -410,9 +410,9 @@ Additionally, some opclasses allow [-user-]{+users+} to [-set specific parameters,-]{+specify parameters+} which [-controls its-]{+control their+} behavior. Each builtin index access method [-have-]{+has an+} optional options support function, which defines {+a+} set of opclass-specific parameters. @@ -459,7 +459,7 @@ Defines {+a+} set of options that are specific [-for-]{+to+} this operator class (optional) 5 @@ -501,7 +501,7 @@ Defines {+a+} set of options that are specific [-for-]{+to+} this operator class (optional) 3 @@ -584,7 +584,7 @@ options Defines {+a+} set of options that are specific [-for-]{+to+} this operator class (optional) 10 @@ -643,7 +643,7 @@ options Defines {+a+} set of options that are specific [-for-]{+to+} this operator class (optional) 6 @@ -720,7 +720,7 @@ options Defines {+a+} set of options that are specific [-for-]{+to+} this operator class (optional) 7 @@ -778,7 +778,7 @@ options Defines {+a+} set of options that are specific [-for-]{+to+} this operator class (optional) 5 --W2ydbIOJmkm74tJ2 Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="v1-0001-Language-fixen-for-15cb2bd27009f73a84a35c2ba60fdd.patch" From c590277f8ae3f77be420f93aeaece5cefdfd15a1 Mon Sep 17 00:00:00 2001 From: Justin Pryzby Date: Sat, 20 Jun 2020 16:37:51 -0500 Subject: [PATCH v1] 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 | 6 +++--- doc/src/sgml/xindex.sgml | 18 +++++++++--------- 6 files changed, 38 insertions(+), 38 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 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 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 @@ my_fetch(PG_FUNCTION_ARGS) options - Allows defintion of user-visible parameters that control operator + Allows definition of user-visible parameters that control operator class behavior. @@ -962,16 +962,16 @@ LANGUAGE C STRICT; - 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. - The sample implementation of my_option() and parameters usage - in the another support function are given below: + An example implementation of my_options() and parameters use + from other support functions are given below: typedef enum MyEnumType @@ -990,7 +990,7 @@ typedef struct int str_param; /* string parameter */ } MyOptionsStruct; -/* String representations for enum values */ +/* String representation of enum values */ static relopt_enum_elt_def myEnumValues[] = { {"on", MY_ENUM_ON}, @@ -1002,7 +1002,7 @@ static relopt_enum_elt_def myEnumValues[] = static char *str_param_default = "default"; /* - * Sample validatior: checks that string is not longer than 8 bytes. + * Sample validator: checks that string is not longer than 8 bytes. */ static void validate_my_string_relopt(const char *value) @@ -1090,8 +1090,8 @@ my_compress(PG_FUNCTION_ARGS) Since the representation of the key in GiST is - flexible, it may depends on user-specified parameters. For instace, - the length of key signature may be such parameter. See + flexible, it may depend on user-specified parameters. For instance, + the length of key signature may be specified. See gtsvector_options() for example. diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml index 03f914735b..1395dbaf88 100644 --- a/doc/src/sgml/spgist.sgml +++ b/doc/src/sgml/spgist.sgml @@ -895,16 +895,16 @@ LANGUAGE C STRICT; - 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. Since the representation of the key in SP-GiST is - flexible, it may depends on user-specified parameters. + flexible, it may depend on user-specified parameters. diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml index 0e4587a81b..2cfd71b5b7 100644 --- a/doc/src/sgml/xindex.sgml +++ b/doc/src/sgml/xindex.sgml @@ -410,9 +410,9 @@ - Additionally, some opclasses allow user to set specific parameters, which - controls its behavior. Each builtin index access method have optional - options support function, which defines set of + Additionally, some opclasses allow users to specify parameters which + control their behavior. Each builtin index access method has an optional + options support function, which defines a set of opclass-specific parameters. @@ -459,7 +459,7 @@ - Defines set of options that are specific for this operator class + Defines a set of options that are specific to this operator class (optional) 5 @@ -501,7 +501,7 @@ - Defines set of options that are specific for this operator class + Defines a set of options that are specific to this operator class (optional) 3 @@ -584,7 +584,7 @@ options - Defines set of options that are specific for this operator class + Defines a set of options that are specific to this operator class (optional) 10 @@ -643,7 +643,7 @@ options - Defines set of options that are specific for this operator class + Defines a set of options that are specific to this operator class (optional) 6 @@ -720,7 +720,7 @@ options - Defines set of options that are specific for this operator class + Defines a set of options that are specific to this operator class (optional) 7 @@ -778,7 +778,7 @@ options - Defines set of options that are specific for this operator class + Defines a set of options that are specific to this operator class (optional) 5 -- 2.17.0 --W2ydbIOJmkm74tJ2--