Doc patch, normalize search_path in index

Hi,

The attached patch (against git head)
normalizes "search_path" as the thing indexed
and uses a secondary index term to distinguish
the configuration parameter from the run-time
setting.

"search path" the concept remains distinguished
in the index from "search_path" the setting/config param.
It's hard to say whether it's useful to make this
distinction. From a practical perspective it's easy
for the eye to stop scanning when the indent
level changes and so fail to notice that both
"search path" and "search_path" are index
entries. At least the index is a
lot more tidy than before.

Regards,

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

On Fri, Sep 28, 2012 at 1:40 PM, Karl O. Pinc <kop(at)meme(dot)com> wrote:
> Hi,
>
> The attached patch (against git head)
> normalizes "search_path" as the thing indexed
> and uses a secondary index term to distinguish
> the configuration parameter from the run-time
> setting.

Makes sense to me, although I suspect the conceptual material is
better served by the "search path"-the-concept index entry and the
reference material by the "search_path configuration parameter" entry
(so, from that perspective, perhaps the patch should just be to remove
the "search_path" index entry from the DDL schemas conceptual
section).

> "search path" the concept remains distinguished
> in the index from "search_path" the setting/config param.
> It's hard to say whether it's useful to make this
> distinction.

I think that indexing "search path"-the-concept is useful for
translations, and the Japanese translation includes an index (I
couldn't find the index for the French translation).

--
Dan Scott
Laurentian University

On Fri, Sep 28, 2012 at 12:40:38PM -0500, Karl O. Pinc wrote:
> Hi,
>
> The attached patch (against git head)
> normalizes "search_path" as the thing indexed
> and uses a secondary index term to distinguish
> the configuration parameter from the run-time
> setting.
>
> "search path" the concept remains distinguished
> in the index from "search_path" the setting/config param.
> It's hard to say whether it's useful to make this
> distinction. From a practical perspective it's easy
> for the eye to stop scanning when the indent
> level changes and so fail to notice that both
> "search path" and "search_path" are index
> entries. At least the index is a
> lot more tidy than before.

I have applied a modified version of your patch that creates separate
secondary index references for search_path.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> I have applied a modified version of your patch that creates separate
> secondary index references for search_path.

This patch seems pretty bizarre. What is the difference between a
"configuration parameter" and a "run-time setting"? Why would you
point people to two different places for those two terms?

regards, tom lane

On Fri, Jan 25, 2013 at 01:35:49PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > I have applied a modified version of your patch that creates separate
> > secondary index references for search_path.
>
> This patch seems pretty bizarre. What is the difference between a
> "configuration parameter" and a "run-time setting"? Why would you
> point people to two different places for those two terms?

I think he is trying to distinguish between the parameter and the
setting of the parameter, and also its use for security. No one really
replied to the email so I thought the distinction was accpetable.

Should I make them both "configuration parameter" and leave the
"security" as a second one separate?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> On Fri, Jan 25, 2013 at 01:35:49PM -0500, Tom Lane wrote:
>> This patch seems pretty bizarre. What is the difference between a
>> "configuration parameter" and a "run-time setting"? Why would you
>> point people to two different places for those two terms?

> Should I make them both "configuration parameter" and leave the
> "security" as a second one separate?

Works for me. I think "configuration parameter" is the phrase we
use most places.

regards, tom lane

On Fri, Jan 25, 2013 at 01:42:48PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > On Fri, Jan 25, 2013 at 01:35:49PM -0500, Tom Lane wrote:
> >> This patch seems pretty bizarre. What is the difference between a
> >> "configuration parameter" and a "run-time setting"? Why would you
> >> point people to two different places for those two terms?
>
> > Should I make them both "configuration parameter" and leave the
> > "security" as a second one separate?
>
> Works for me. I think "configuration parameter" is the phrase we
> use most places.

OK, attached patch applied.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On 1/25/13 12:50 PM, Bruce Momjian wrote:
> On Fri, Sep 28, 2012 at 12:40:38PM -0500, Karl O. Pinc wrote:
>> Hi,
>>
>> The attached patch (against git head)
>> normalizes "search_path" as the thing indexed
>> and uses a secondary index term to distinguish
>> the configuration parameter from the run-time
>> setting.
>>
>> "search path" the concept remains distinguished
>> in the index from "search_path" the setting/config param.
>> It's hard to say whether it's useful to make this
>> distinction. From a practical perspective it's easy
>> for the eye to stop scanning when the indent
>> level changes and so fail to notice that both
>> "search path" and "search_path" are index
>> entries. At least the index is a
>> lot more tidy than before.
>
> I have applied a modified version of your patch that creates separate
> secondary index references for search_path.

This matter was already closed:
https://commitfest.postgresql.org/action/patch_view?id=949

It looks like your patch reverts part of that.

On Fri, Jan 25, 2013 at 01:46:46PM -0500, Peter Eisentraut wrote:
> On 1/25/13 12:50 PM, Bruce Momjian wrote:
> > On Fri, Sep 28, 2012 at 12:40:38PM -0500, Karl O. Pinc wrote:
> >> Hi,
> >>
> >> The attached patch (against git head)
> >> normalizes "search_path" as the thing indexed
> >> and uses a secondary index term to distinguish
> >> the configuration parameter from the run-time
> >> setting.
> >>
> >> "search path" the concept remains distinguished
> >> in the index from "search_path" the setting/config param.
> >> It's hard to say whether it's useful to make this
> >> distinction. From a practical perspective it's easy
> >> for the eye to stop scanning when the indent
> >> level changes and so fail to notice that both
> >> "search path" and "search_path" are index
> >> entries. At least the index is a
> >> lot more tidy than before.
> >
> > I have applied a modified version of your patch that creates separate
> > secondary index references for search_path.
>
> This matter was already closed:
> https://commitfest.postgresql.org/action/patch_view?id=949
>
> It looks like your patch reverts part of that.

Uh, I am confused because the patch at:

https://commitfest.postgresql.org/action/patch_view?id=950
http://www.postgresql.org/message-id/1352874080.4647.0@mofo

shows "configuration parameter" being moved to <secondary>, though this
commit:

http://git.postgresql.org/gitweb/?p=postgresql.git&a=commitdiff&h=a301eb99c9537186f7dd46ba418e84d755227a94

shows it not as secondary. Would you please suggest a patch or patch
it? Thanks.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On 01/25/2013 12:35:49 PM, Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > I have applied a modified version of your patch that creates
> separate
> > secondary index references for search_path.
>
> This patch seems pretty bizarre. What is the difference between a
> "configuration parameter" and a "run-time setting"? Why would you
> point people to two different places for those two terms?

One was the setting/querying of the parameter, the other the
purpose/impact of the setting. Somewhere in there I'm also
thinking it's a matter of the lexical token used v.s.
the functionality manipulated. One would have an _ in
between the words of the index entry, the other wouldn't.
The distinction would get all messed up by the browser
when it underlined hyperlinks.

I no longer recall the point
in making the distinction, although I believe that it came
from something to do with the vocabulary already in place
involving indexing settings and what they do. Or maybe I made it up.
In any case I don't think that the patch the Peter pushed
when he closed the commitfest entry made any distinction
between the token and the concept. Given that the difference
in sort order is the presence/absence of an _, and the
way hyperlinks are represented, I think this made the
the resulting index look best.

There was also a "use of search path to secure functions"
indexing wrapped in with the rest of the patch.

Hope this helps.

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

On 1/25/13 1:59 PM, Bruce Momjian wrote:
> On Fri, Jan 25, 2013 at 01:46:46PM -0500, Peter Eisentraut wrote:
>> This matter was already closed:
>> https://commitfest.postgresql.org/action/patch_view?id=949
>>
>> It looks like your patch reverts part of that.
>
> Uh, I am confused because the patch at:
>
> https://commitfest.postgresql.org/action/patch_view?id=950
> http://www.postgresql.org/message-id/1352874080.4647.0@mofo
>
> shows "configuration parameter" being moved to <secondary>, though this
> commit:
>
> http://git.postgresql.org/gitweb/?p=postgresql.git&a=commitdiff&h=a301eb99c9537186f7dd46ba418e84d755227a94

The discussion yielded a patch that is different from the commit fest entry.

We index all GUC settings as

<primary><varname>something</varname> configuration parameter</primary>

which the commit a301eb99c9537186f7dd46ba418e84d755227a94 also made the case for search_path.

Your two commits changed that again.

> shows it not as secondary. Would you please suggest a patch or patch
> it? Thanks.

I think both of your commits should be reverted.

On Fri, Jan 25, 2013 at 05:10:14PM -0500, Peter Eisentraut wrote:
> On 1/25/13 1:59 PM, Bruce Momjian wrote:
> > On Fri, Jan 25, 2013 at 01:46:46PM -0500, Peter Eisentraut wrote:
> >> This matter was already closed:
> >> https://commitfest.postgresql.org/action/patch_view?id=949
> >>
> >> It looks like your patch reverts part of that.
> >
> > Uh, I am confused because the patch at:
> >
> > https://commitfest.postgresql.org/action/patch_view?id=950
> > http://www.postgresql.org/message-id/1352874080.4647.0@mofo
> >
> > shows "configuration parameter" being moved to <secondary>, though this
> > commit:
> >
> > http://git.postgresql.org/gitweb/?p=postgresql.git&a=commitdiff&h=a301eb99c9537186f7dd46ba418e84d755227a94
>
> The discussion yielded a patch that is different from the commit fest entry.
>
> We index all GUC settings as
>
> <primary><varname>something</varname> configuration parameter</primary>
>
> which the commit a301eb99c9537186f7dd46ba418e84d755227a94 also made the case for search_path.
>
> Your two commits changed that again.
>
> > shows it not as secondary. Would you please suggest a patch or patch
> > it? Thanks.
>
> I think both of your commits should be reverted.

I now see the pattern. Thanks. Patches reverted.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +