Documentation patch: change a name in a grammar rule to prevent confusion
Hello,
the following patch changes "parameter" to "gucname" in the grammar
(and later references) for the SET syntax in ALTER ROLE and ALTER
USER. The rationale for this is that on #postgresql (IRC), we observe
many people trying to change the password for a role as follows:
ALTER ROLE blah SET PASSWORD = 'password';
(the correct syntax is "ALTER ROLE blah PASSWORD 'password';")
The confusion is induced by the usage of the word "parameter" and the
name of a section called "Parameters", which then lists the possible
non-GUC parameters. This apparently makes readers think that those are
the "parameters" that can be changed with above syntax.
Nicolas
--
Nicolas Barbier
http://www.gnu.org/philosophy/no-word-attachments.html
Attachments:
pgsql_doc_alter_role_clarification.patchtext/x-patch; charset=us-ascii; name=pgsql_doc_alter_role_clarification.patchDownload+10-10
On Sat, 2006-04-15 at 01:59 +0200, Nicolas Barbier wrote:
the following patch changes "parameter" to "gucname" in the grammar
(and later references) for the SET syntax in ALTER ROLE and ALTER
USER.
Wouldn't "var_name", "varname", or something similar be more clear?
"GUC" is probably not an acronym we should be exposing prominently to
the user.
-Neil
Neil Conway <neilc@samurai.com> writes:
On Sat, 2006-04-15 at 01:59 +0200, Nicolas Barbier wrote:
the following patch changes "parameter" to "gucname" in the grammar
(and later references) for the SET syntax in ALTER ROLE and ALTER
USER.
Wouldn't "var_name", "varname", or something similar be more clear?
"GUC" is probably not an acronym we should be exposing prominently to
the user.
s/prominently/at all/ ... I don't think the proposed patch is an
improvement, and in fact see nothing wrong with the use of "parameter"
here. If we want to abandon "parameter" as the official documentation
term for GUC variables, then there are dozens or hundreds of changes
to be made in config.sgml, to say nothing of other files.
regards, tom lane
2006/4/15, Neil Conway <neilc@samurai.com>:
On Sat, 2006-04-15 at 01:59 +0200, Nicolas Barbier wrote:
the following patch changes "parameter" to "gucname" in the grammar
(and later references) for the SET syntax in ALTER ROLE and ALTER
USER.Wouldn't "var_name", "varname", or something similar be more clear?
"GUC" is probably not an acronym we should be exposing prominently to
the user.
Indeed, that is what people on IRC also told me (after I sent it :-)).
It now uses "varname". Updated patch attached.
Nicolas
--
Nicolas Barbier
http://www.gnu.org/philosophy/no-word-attachments.html
Attachments:
pgsql_doc_alter_role_clarification_2.patchtext/x-patch; charset=us-ascii; name=pgsql_doc_alter_role_clarification_2.patchDownload+10-10
2006/4/15, Tom Lane <tgl@sss.pgh.pa.us>:
s/prominently/at all/ ... I don't think the proposed patch is an
improvement, and in fact see nothing wrong with the use of "parameter"
here. If we want to abandon "parameter" as the official documentation
term for GUC variables, then there are dozens or hundreds of changes
to be made in config.sgml, to say nothing of other files.
In for example set.sgml, just "name" is used for the exact same
concept. I changed the patch so that "varname" is used, because "name"
was already in use by this specific grammar. Maybe the usage of "var"
makes it less clear indeed, for people that know that those things are
always referred to as "parameters" and never as "variables". But then,
leaving it as-is doesn't solve the apparently occuring confusion
between "parameter" the GUC and "parameter" the "parameter to the
statement", as we have had at least three people in #postgresql that
made that exact mistake.
Nicolas
--
Nicolas Barbier
http://www.gnu.org/philosophy/no-word-attachments.html
Nicolas Barbier wrote:
In for example set.sgml, just "name" is used for the exact same
concept. I changed the patch so that "varname" is used, because
"name" was already in use by this specific grammar. Maybe the usage
of "var" makes it less clear indeed, for people that know that those
things are always referred to as "parameters" and never as
"variables".
A variable would be something that you store application data in,
whereas a parameter is some nondata value that influences your
calculations. That's my recollection of how the terms are used in
mathematics. So parameter is decidedly the better term than variable.
If that is confusing, make it config_param or something like that.
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
2006/4/17, Peter Eisentraut <peter_e@gmx.net>:
Nicolas Barbier wrote:
In for example set.sgml, just "name" is used for the exact same
concept. I changed the patch so that "varname" is used, because
"name" was already in use by this specific grammar. Maybe the usage
of "var" makes it less clear indeed, for people that know that those
things are always referred to as "parameters" and never as
"variables".A variable would be something that you store application data in,
whereas a parameter is some nondata value that influences your
calculations. That's my recollection of how the terms are used in
mathematics. So parameter is decidedly the better term than variable.
If that is confusing, make it config_param or something like that.
Updated patch attached. We just had another person that made the
mistake, hopefully making up for the time and resources I'm depriving
you guys of :-).
Nicolas
--
Nicolas Barbier
http://www.gnu.org/philosophy/no-word-attachments.html
Attachments:
pgsql_doc_alter_role_clarification_3.patchtext/x-patch; charset=us-ascii; name=pgsql_doc_alter_role_clarification_3.patchDownload+10-10
Patch applied. I also updated SET and RESET to be similar.
---------------------------------------------------------------------------
Nicolas Barbier wrote:
2006/4/15, Neil Conway <neilc@samurai.com>:
On Sat, 2006-04-15 at 01:59 +0200, Nicolas Barbier wrote:
the following patch changes "parameter" to "gucname" in the grammar
(and later references) for the SET syntax in ALTER ROLE and ALTER
USER.Wouldn't "var_name", "varname", or something similar be more clear?
"GUC" is probably not an acronym we should be exposing prominently to
the user.Indeed, that is what people on IRC also told me (after I sent it :-)).
It now uses "varname". Updated patch attached.Nicolas
--
Nicolas Barbier
http://www.gnu.org/philosophy/no-word-attachments.html
[ Attachment, skipping... ]
---------------------------(end of broadcast)---------------------------
TIP 6: explain analyze is your friend
--
Bruce Momjian http://candle.pha.pa.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Attachments:
/bjm/difftext/plainDownload+20-20
OK, updated patch calls them "configuration_paramters"s.
---------------------------------------------------------------------------
Nicolas Barbier wrote:
2006/4/17, Peter Eisentraut <peter_e@gmx.net>:
Nicolas Barbier wrote:
In for example set.sgml, just "name" is used for the exact same
concept. I changed the patch so that "varname" is used, because
"name" was already in use by this specific grammar. Maybe the usage
of "var" makes it less clear indeed, for people that know that those
things are always referred to as "parameters" and never as
"variables".A variable would be something that you store application data in,
whereas a parameter is some nondata value that influences your
calculations. That's my recollection of how the terms are used in
mathematics. So parameter is decidedly the better term than variable.
If that is confusing, make it config_param or something like that.Updated patch attached. We just had another person that made the
mistake, hopefully making up for the time and resources I'm depriving
you guys of :-).Nicolas
--
Nicolas Barbier
http://www.gnu.org/philosophy/no-word-attachments.html
[ Attachment, skipping... ]
---------------------------(end of broadcast)---------------------------
TIP 6: explain analyze is your friend
--
Bruce Momjian http://candle.pha.pa.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +