Thread: Mark a reloption as indexterm
Hi, I'd like to propose to mark reloptions as indexterms, like GUC, so that users can more easily search the pages describing a reloption in document. Attached is the patch which does this. Is this helpful? Thought? Regards, -- Fujii Masao
Attachment
On 2019-Apr-10, Fujii Masao wrote: > Hi, > > I'd like to propose to mark reloptions as indexterms, like GUC, > so that users can more easily search the pages describing > a reloption in document. Attached is the patch which does this. > Is this helpful? Thought? +1 for adding index entries to all reloptions. I'm not sure what you're achieving by splitting the text for some existing index entries in two and putting two words in the <secondary> that were part of the <primary>, though. I'd just put the whole text in <primary> (obviously the option name must be the first word of that). -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Wed, Apr 10, 2019 at 4:11 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > > On 2019-Apr-10, Fujii Masao wrote: > > > Hi, > > > > I'd like to propose to mark reloptions as indexterms, like GUC, > > so that users can more easily search the pages describing > > a reloption in document. Attached is the patch which does this. > > Is this helpful? Thought? > > +1 for adding index entries to all reloptions. I'm not sure what you're > achieving by splitting the text for some existing index entries in two > and putting two words in the <secondary> that were part of the > <primary>, though. I'd just put the whole text in <primary> (obviously > the option name must be the first word of that). Indeed. Attached is the updated version of the patch. Regards, -- Fujii Masao
Attachment
On Fri, Apr 12, 2019 at 12:33:45PM +0900, Fujii Masao wrote: > Indeed. Attached is the updated version of the patch. On top of what Alvaro has mentioned, it seems to me that we should make the difference between table-level configuration parameter and index-level configuration parameters, and also add <primary> markups to create_index.sgml. If you take the example of fillfactor, it applies to both indexes and tables, but with your patch you just define "configuration parameter", and point to only CREATE TABLE. -- Michael
Attachment
On 2019-Apr-12, Fujii Masao wrote: > On Wed, Apr 10, 2019 at 4:11 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > > > > On 2019-Apr-10, Fujii Masao wrote: > > > > > Hi, > > > > > > I'd like to propose to mark reloptions as indexterms, like GUC, > > > so that users can more easily search the pages describing > > > a reloption in document. Attached is the patch which does this. > > > Is this helpful? Thought? > > > > +1 for adding index entries to all reloptions. I'm not sure what you're > > achieving by splitting the text for some existing index entries in two > > and putting two words in the <secondary> that were part of the > > <primary>, though. I'd just put the whole text in <primary> (obviously > > the option name must be the first word of that). > > Indeed. Attached is the updated version of the patch. Hmm, actually, I now see you were originally proposing the words "storage parameter" for the fillfactor index entries, but for v2 you instead copied the "configuration parameter" words that was in some other of the older entries. I think "configuration parameter" is wrong (we use that for GUCs, and it seems to me that it would be confusing to mix both things), and we should use the words "storage parameter" for all of these, don't you think? -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 2019-Apr-12, Michael Paquier wrote: > On Fri, Apr 12, 2019 at 12:33:45PM +0900, Fujii Masao wrote: > > Indeed. Attached is the updated version of the patch. > > On top of what Alvaro has mentioned, it seems to me that we should > make the difference between table-level configuration parameter and > index-level configuration parameters, and also add <primary> markups > to create_index.sgml. If you take the example of fillfactor, it > applies to both indexes and tables, but with your patch you just > define "configuration parameter", and point to only CREATE TABLE. Are you suggesting that it should show "index storage parameters" and "table storage parameters"? I'm not sure about that myself ... particularly considering that certain parameters might apply to some index AMs and not others. BTW what about the index-specific options such as, say, BRIN's pages_per_range? I know other AMs have their own reloptions ... -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Thu, Apr 11, 2019 at 11:57:32PM -0400, Alvaro Herrera wrote: > Are you suggesting that it should show "index storage parameters" and > "table storage parameters"? I'm not sure about that myself ... > particularly considering that certain parameters might apply to some > index AMs and not others. Yes, that's exactly what I was suggesting: putting all the index-related parameters into an index bucket, without caring about the AM involved. -- Michael
Attachment
On Fri, Apr 12, 2019 at 12:54 PM Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:
>
> On 2019-Apr-12, Fujii Masao wrote:
>
> > On Wed, Apr 10, 2019 at 4:11 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
> > >
> > > On 2019-Apr-10, Fujii Masao wrote:
> > >
> > > > Hi,
> > > >
> > > > I'd like to propose to mark reloptions as indexterms, like GUC,
> > > > so that users can more easily search the pages describing
> > > > a reloption in document. Attached is the patch which does this.
> > > > Is this helpful? Thought?
> > >
> > > +1 for adding index entries to all reloptions. I'm not sure what you're
> > > achieving by splitting the text for some existing index entries in two
> > > and putting two words in the <secondary> that were part of the
> > > <primary>, though. I'd just put the whole text in <primary> (obviously
> > > the option name must be the first word of that).
> >
> > Indeed. Attached is the updated version of the patch.
>
> Hmm, actually, I now see you were originally proposing the words
> "storage parameter" for the fillfactor index entries, but for v2 you
> instead copied the "configuration parameter" words that was in some
> other of the older entries. I think "configuration parameter" is wrong
> (we use that for GUCs, and it seems to me that it would be confusing to
> mix both things), and we should use the words "storage parameter" for
> all of these, don't you think?
So you are suggesting to use
<primary><varname>xxx</varname> storage parameter</primary> for
reltoption and
<primary><varname>xxx</varname> configuration parameter</primary> for GUC?
If we do that, the following two lines are in the index.
xxx configuration parameter, XXX
xxx storage parameter, Storage Parameter
OTOH, originally I thought that the following style is smarter.
xxx
configuration parameter, XXX
storage parameter, Storage Parameter
Regards,
--
Fujii Masao
On Fri, Apr 12, 2019 at 1:09 PM Michael Paquier <michael@paquier.xyz> wrote: > > On Thu, Apr 11, 2019 at 11:57:32PM -0400, Alvaro Herrera wrote: > > Are you suggesting that it should show "index storage parameters" and > > "table storage parameters"? I'm not sure about that myself ... > > particularly considering that certain parameters might apply to some > > index AMs and not others. > > Yes, that's exactly what I was suggesting: putting all the > index-related parameters into an index bucket, without caring about > the AM involved. +1 While reading the doc for index reloptins, I found that there is no information about the type for each index reloption in the doc. Probably it's worth adding that information, like the doc for table reloptions have. Regards, -- Fujii Masao
On 2019-Apr-12, Fujii Masao wrote: > OTOH, originally I thought that the following style is smarter. > > xxx > configuration parameter, XXX > storage parameter, Storage Parameter Ah. Well, I like this style. Let's do that. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Sat, Apr 13, 2019 at 1:30 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > > On 2019-Apr-12, Fujii Masao wrote: > > > > OTOH, originally I thought that the following style is smarter. > > > > xxx > > configuration parameter, XXX > > storage parameter, Storage Parameter > > Ah. Well, I like this style. Let's do that. So I used <secondary> tag again for the above style if both reloption and guc with the same parameter name exist. Attached is the updated version of the patch. This patch also marks index-reloption as indexterm. Barring any objections, I will commit this patch. Regards, -- Fujii Masao
Attachment
On 2019-Apr-16, Fujii Masao wrote: > On Sat, Apr 13, 2019 at 1:30 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > > > > On 2019-Apr-12, Fujii Masao wrote: > > > > > > > OTOH, originally I thought that the following style is smarter. > > > > > > xxx > > > configuration parameter, XXX > > > storage parameter, Storage Parameter > > > > Ah. Well, I like this style. Let's do that. > > So I used <secondary> tag again for the above style if both reloption > and guc with the same parameter name exist. Attached is the updated > version of the patch. This patch also marks index-reloption as indexterm. I checked the HTML output. For autovacuum it says "configuration parameters" rather than "configuration parameter". Other than that, it looks good to me. (I didn't check that all storage options were covered.) -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Tue, Apr 16, 2019 at 12:35 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > > On 2019-Apr-16, Fujii Masao wrote: > > > On Sat, Apr 13, 2019 at 1:30 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > > > > > > On 2019-Apr-12, Fujii Masao wrote: > > > > > > > > > > OTOH, originally I thought that the following style is smarter. > > > > > > > > xxx > > > > configuration parameter, XXX > > > > storage parameter, Storage Parameter > > > > > > Ah. Well, I like this style. Let's do that. > > > > So I used <secondary> tag again for the above style if both reloption > > and guc with the same parameter name exist. Attached is the updated > > version of the patch. This patch also marks index-reloption as indexterm. > > I checked the HTML output. Thanks for the review! > For autovacuum it says "configuration > parameters" rather than "configuration parameter". Other than that, it > looks good to me. (I didn't check that all storage options were covered.) Good catch! Seems "configuration parameters" had been used for autovacuum parameter since old version. I agree to replace it with "configuration parameter" for the sake of consistency. But I think that it's better to do that by the separate patch because they are separate things. Regards, -- Fujii Masao
On 2019-Apr-16, Fujii Masao wrote: > On Tue, Apr 16, 2019 at 12:35 AM Alvaro Herrera > <alvherre@2ndquadrant.com> wrote: > > For autovacuum it says "configuration > > parameters" rather than "configuration parameter". Other than that, it > > looks good to me. (I didn't check that all storage options were covered.) > > Good catch! Seems "configuration parameters" had been used for autovacuum > parameter since old version. I agree to replace it with "configuration > parameter" > for the sake of consistency. But I think that it's better to do that by > the separate patch because they are separate things. OK, no objection :-) -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Tue, Apr 16, 2019 at 12:14:01AM +0900, Fujii Masao wrote: > So I used <secondary> tag again for the above style if both reloption > and guc with the same parameter name exist. Attached is the updated > version of the patch. This patch also marks index-reloption as indexterm. > > Barring any objections, I will commit this patch. Thanks Fujii-san. This looks fine to me. -- Michael
Attachment
On Tue, Apr 16, 2019 at 1:15 AM Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > > On 2019-Apr-16, Fujii Masao wrote: > > > On Tue, Apr 16, 2019 at 12:35 AM Alvaro Herrera > > <alvherre@2ndquadrant.com> wrote: > > > > For autovacuum it says "configuration > > > parameters" rather than "configuration parameter". Other than that, it > > > looks good to me. (I didn't check that all storage options were covered.) > > > > Good catch! Seems "configuration parameters" had been used for autovacuum > > parameter since old version. I agree to replace it with "configuration > > parameter" > > for the sake of consistency. But I think that it's better to do that by > > the separate patch because they are separate things. > > OK, no objection :-) While reading config.sgml again, I found that there are both "autovacuum configuration parameters" and "autovacuum configuration parameter", i.e., the plural and the singular. The latter indicates the autovacuum GUC itself. OTOH, the former seems to indicate all the autovacuum-related GUC parameters. So the plural form is used. So now I'm thinking that we would not need to fix that plural form of the index term. Regards, -- Fujii Masao
On Tue, Apr 16, 2019 at 12:26 PM Michael Paquier <michael@paquier.xyz> wrote: > > On Tue, Apr 16, 2019 at 12:14:01AM +0900, Fujii Masao wrote: > > So I used <secondary> tag again for the above style if both reloption > > and guc with the same parameter name exist. Attached is the updated > > version of the patch. This patch also marks index-reloption as indexterm. > > > > Barring any objections, I will commit this patch. > > Thanks Fujii-san. This looks fine to me. Thanks for the review! Committed! Regards, -- Fujii Masao