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 1jmmuT-0003yN-BS for pgsql-hackers@arkaria.postgresql.org; Sat, 20 Jun 2020 23:28:29 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jmmuS-0001LV-83 for pgsql-hackers@arkaria.postgresql.org; Sat, 20 Jun 2020 23:28:28 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jmmuR-0001LN-WE for pgsql-hackers@lists.postgresql.org; Sat, 20 Jun 2020 23:28:28 +0000 Received: from mail-io1-xd2d.google.com ([2607:f8b0:4864:20::d2d]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jmmuK-0005V4-VW for pgsql-hackers@postgresql.org; Sat, 20 Jun 2020 23:28:27 +0000 Received: by mail-io1-xd2d.google.com with SMTP id m81so15635524ioa.1 for ; Sat, 20 Jun 2020 16:28:20 -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=K9hBvHfFB3fpNDJbHPlBeu5bNrloOtzpzqvluZjIQY0=; b=y7yIHhbifdDhCc/+TtctfW7yZWnCPPV6IWpyQVOV/VmGUcECyCJCDN4nwxo0J8QGN4 04GKC6JRH7R5UNAUEAYkPrFoD3d1NVYq7e+vR6JHu6K+ltBMD+cvYL3cRGi+BpJzZFY5 A7aE2pdRXrNzQnNQVzaaKStbS1Io6JLRx/2w+FPgAk3wIB1iO5KYvuilQNeOpVCUMqjY R+Otn53tRA21kpZQSkHC1f0ZPgk+hyz9Qmnx06Rhb3/hDgLh7lJmy5FeGBkguDuy+e3d Iaf5Ea2iiheDI2hbDVf8j6s7m2xPL886tvKiW2dI0KfHEeYJA17r3FUeifTwknloJAxB ls0w== 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=K9hBvHfFB3fpNDJbHPlBeu5bNrloOtzpzqvluZjIQY0=; b=fH76/8C5sDrqJY2Bg8QTvX6u3XOMXbaDNKiE3OFELftVe8uDBcuQ0aSaYXcM7P7St5 rtnMYoFFGjxZeTkcdytLNWAS5EoS7Vmd14qXQPHcqcrmd7aINo6QWOZDKPdFlZhw4Z0e lVODuUAyZjZNglidHPnuX05J2OSpRhDaP7J8AZc8lFSQZ90bR79GahB5x6qCQJde1pEU Zabk0nXuimK6fbICuUuxHHuIRf8n43VYpAXw8DYz6/q+hbkVYmhTs/sY0A0V/P9Y5mcK EPuwXM0pvHEAL37BLvExsPiMJjOzSeP0c7C5ImWCepSmu8EuA7LM7JCKcM9fTEFJP9yg qAzA== X-Gm-Message-State: AOAM533RNoUlkZecz6Kt8mUYeep+qcE+CkFn/oxScq4VQpNBNM3KzvBe eitpGNB0HCCp6F3p6L3GGNa6gw== X-Google-Smtp-Source: ABdhPJzFAUXmy3z1Z/yseEVUalpUOdQ49NjplOhXvGTxP0q8P7Bj8ZubiqoKrq1wvpiZtFJvp811hA== X-Received: by 2002:a6b:6c11:: with SMTP id a17mr11996064ioh.154.1592695699093; Sat, 20 Jun 2020 16:28:19 -0700 (PDT) Received: from pryzbyj.telsasoft (charmander.telsasoft.com. [50.244.222.1]) by smtp.gmail.com with ESMTPSA id d13sm5410856ilo.40.2020.06.20.16.28.17 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sat, 20 Jun 2020 16:28:18 -0700 (PDT) Received: by pryzbyj.telsasoft (Postfix, from userid 1000) id 5C164800A36; Sat, 20 Jun 2020 18:28:16 -0500 (CDT) Date: Sat, 20 Jun 2020 18:28:16 -0500 From: Justin Pryzby To: Alexander Korotkov Cc: Peter Geoghegan , pgsql-hackers@postgresql.org Subject: Re: Operator class parameters and sgml docs Message-ID: <20200620232816.GA23670@telsasoft.com> References: <20200620232145.GB17995@telsasoft.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="envbJBWh7q8WU6mo" Content-Disposition: inline In-Reply-To: <20200620232145.GB17995@telsasoft.com> User-Agent: Mutt/1.9.4 (2018-02-28) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --envbJBWh7q8WU6mo Content-Type: text/plain; charset=us-ascii Content-Disposition: inline And a couple more in spgist.sgml (some of which were not added by this patch). --envbJBWh7q8WU6mo Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="v2-0001-Language-fixen-for-15cb2bd27009f73a84a35c2ba60fdd.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 @@ 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 ad8d348a43..d9ecfe74ed 100644 --- a/doc/src/sgml/spgist.sgml +++ b/doc/src/sgml/spgist.sgml @@ -290,13 +290,13 @@ values for the support method, while the second argument is a pointer to a C struct where output values must be placed. Four of the mandatory methods just return void, since all their results appear in the output struct; but - leaf_consistent additionally returns a boolean result. + leaf_consistent returns a boolean result. The methods must not modify any fields of their input structs. In all cases, the output struct is initialized to zeroes before calling the user-defined method. The optional sixth method compress - accepts datum to be indexed as the only argument and returns a value suitable + accepts a datum to be indexed as the only argument and returns a value suitable for physical storage in a leaf tuple. The optional seventh method - options accepts internal pointer to a C struct, where + options accepts an internal pointer to a C struct, where opclass-specific parameters should be placed, and returns void. @@ -897,16 +897,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 --envbJBWh7q8WU6mo--