Postgres Pro
Downloads
Home   >   mailing lists

Thread: Documentation patch: change a name in a grammar rule to prevent confusion

Documentation patch: change a name in a grammar rule to prevent confusion

From
"Nicolas Barbier"
Date:
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
Attachment

Re: Documentation patch: change a name in a grammar rule

From
Neil Conway
Date:
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

Re: Documentation patch: change a name in a grammar rule

From
Tom Lane
Date:
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

Re: Documentation patch: change a name in a grammar rule to prevent confusion

From
"Nicolas Barbier"
Date:
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

Re: Documentation patch: change a name in a grammar rule

From
"Nicolas Barbier"
Date:
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

Re: Documentation patch: change a name in a grammar rule

From
Peter Eisentraut
Date:
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/

Re: Documentation patch: change a name in a grammar rule

From
"Nicolas Barbier"
Date:
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

Re: Documentation patch: change a name in a grammar rule to

From
Bruce Momjian
Date:
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. +
Index: doc/src/sgml/ref/alter_role.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/alter_role.sgml,v
retrieving revision 1.3
diff -c -c -r1.3 alter_role.sgml
*** doc/src/sgml/ref/alter_role.sgml    18 Dec 2005 02:17:16 -0000    1.3
--- doc/src/sgml/ref/alter_role.sgml    25 Apr 2006 14:45:24 -0000
***************
*** 36,43 ****

  ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> SET <replaceable>parameter</replaceable> { TO | = } {
<replaceable>value</replaceable>| DEFAULT } 
! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>parameter</replaceable>
  </synopsis>
   </refsynopsisdiv>

--- 36,43 ----

  ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> SET <replaceable>varname</replaceable> { TO | = } {
<replaceable>value</replaceable>| DEFAULT } 
! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>varname</replaceable>
  </synopsis>
   </refsynopsisdiv>

***************
*** 143,149 ****
       </varlistentry>

       <varlistentry>
!       <term><replaceable>parameter</replaceable></term>
        <term><replaceable>value</replaceable></term>
        <listitem>
         <para>
--- 143,149 ----
       </varlistentry>

       <varlistentry>
!       <term><replaceable>varname</replaceable></term>
        <term><replaceable>value</replaceable></term>
        <listitem>
         <para>
Index: doc/src/sgml/ref/alter_user.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v
retrieving revision 1.39
diff -c -c -r1.39 alter_user.sgml
*** doc/src/sgml/ref/alter_user.sgml    31 Jul 2005 17:19:17 -0000    1.39
--- doc/src/sgml/ref/alter_user.sgml    25 Apr 2006 14:45:25 -0000
***************
*** 36,43 ****

  ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER USER <replaceable class="PARAMETER">name</replaceable> SET <replaceable>parameter</replaceable> { TO | = } {
<replaceable>value</replaceable>| DEFAULT } 
! ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>parameter</replaceable>
  </synopsis>
   </refsynopsisdiv>

--- 36,43 ----

  ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER USER <replaceable class="PARAMETER">name</replaceable> SET <replaceable>varname</replaceable> { TO | = } {
<replaceable>value</replaceable>| DEFAULT } 
! ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>varname</replaceable>
  </synopsis>
   </refsynopsisdiv>

Index: doc/src/sgml/ref/reset.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v
retrieving revision 1.28
diff -c -c -r1.28 reset.sgml
*** doc/src/sgml/ref/reset.sgml    25 Apr 2006 14:11:51 -0000    1.28
--- doc/src/sgml/ref/reset.sgml    25 Apr 2006 14:45:25 -0000
***************
*** 20,26 ****

   <refsynopsisdiv>
  <synopsis>
! RESET <replaceable class="PARAMETER">name</replaceable>
  RESET ALL
  </synopsis>
   </refsynopsisdiv>
--- 20,26 ----

   <refsynopsisdiv>
  <synopsis>
! RESET <replaceable class="PARAMETER">varname</replaceable>
  RESET ALL
  </synopsis>
   </refsynopsisdiv>
***************
*** 33,39 ****
     default values.  <command>RESET</command> is an alternative
     spelling for
  <synopsis>
! SET <replaceable class="parameter">parameter</replaceable> TO DEFAULT
  </synopsis>
     Refer to <xref linkend="sql-set" endterm="sql-set-title"> for
     details.
--- 33,39 ----
     default values.  <command>RESET</command> is an alternative
     spelling for
  <synopsis>
! SET <replaceable class="parameter">varname</replaceable> TO DEFAULT
  </synopsis>
     Refer to <xref linkend="sql-set" endterm="sql-set-title"> for
     details.
***************
*** 62,68 ****

    <variablelist>
     <varlistentry>
!     <term><replaceable class="PARAMETER">name</replaceable></term>
      <listitem>
       <para>
        The name of a run-time parameter. See <xref linkend="sql-set"
--- 62,68 ----

    <variablelist>
     <varlistentry>
!     <term><replaceable class="PARAMETER">varname</replaceable></term>
      <listitem>
       <para>
        The name of a run-time parameter. See <xref linkend="sql-set"
Index: doc/src/sgml/ref/set.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v
retrieving revision 1.86
diff -c -c -r1.86 set.sgml
*** doc/src/sgml/ref/set.sgml    10 Aug 2004 00:55:08 -0000    1.86
--- doc/src/sgml/ref/set.sgml    25 Apr 2006 14:45:25 -0000
***************
*** 20,26 ****

   <refsynopsisdiv>
  <synopsis>
! SET [ SESSION | LOCAL ] <replaceable class="PARAMETER">name</replaceable> { TO | = } { <replaceable
class="PARAMETER">value</replaceable>| '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT } 
  SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</replaceable> | LOCAL | DEFAULT }
  </synopsis>
   </refsynopsisdiv>
--- 20,26 ----

   <refsynopsisdiv>
  <synopsis>
! SET [ SESSION | LOCAL ] <replaceable class="PARAMETER">varname</replaceable> { TO | = } { <replaceable
class="PARAMETER">value</replaceable>| '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT } 
  SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</replaceable> | LOCAL | DEFAULT }
  </synopsis>
   </refsynopsisdiv>
***************
*** 91,97 ****
     </varlistentry>

     <varlistentry>
!     <term><replaceable class="PARAMETER">name</replaceable></term>
      <listitem>
       <para>
        Name of a settable run-time parameter.  Available parameters are
--- 91,97 ----
     </varlistentry>

     <varlistentry>
!     <term><replaceable class="PARAMETER">varname</replaceable></term>
      <listitem>
       <para>
        Name of a settable run-time parameter.  Available parameters are

Re: Documentation patch: change a name in a grammar rule

From
Bruce Momjian
Date:
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. +
Index: doc/src/sgml/ref/alter_role.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/alter_role.sgml,v
retrieving revision 1.4
diff -c -c -r1.4 alter_role.sgml
*** doc/src/sgml/ref/alter_role.sgml    25 Apr 2006 14:47:29 -0000    1.4
--- doc/src/sgml/ref/alter_role.sgml    25 Apr 2006 14:55:23 -0000
***************
*** 36,43 ****

  ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> SET <replaceable>varname</replaceable> { TO | = } {
<replaceable>value</replaceable>| DEFAULT } 
! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>varname</replaceable>
  </synopsis>
   </refsynopsisdiv>

--- 36,43 ----

  ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> SET <replaceable>configuration_parameter</replaceable> {
TO| = } { <replaceable>value</replaceable> | DEFAULT } 
! ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>configuration_parameter</replaceable>
  </synopsis>
   </refsynopsisdiv>

***************
*** 143,149 ****
       </varlistentry>

       <varlistentry>
!       <term><replaceable>varname</replaceable></term>
        <term><replaceable>value</replaceable></term>
        <listitem>
         <para>
--- 143,149 ----
       </varlistentry>

       <varlistentry>
!       <term><replaceable>configuration_parameter</replaceable></term>
        <term><replaceable>value</replaceable></term>
        <listitem>
         <para>
Index: doc/src/sgml/ref/alter_user.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v
retrieving revision 1.40
diff -c -c -r1.40 alter_user.sgml
*** doc/src/sgml/ref/alter_user.sgml    25 Apr 2006 14:47:29 -0000    1.40
--- doc/src/sgml/ref/alter_user.sgml    25 Apr 2006 14:55:23 -0000
***************
*** 36,43 ****

  ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER USER <replaceable class="PARAMETER">name</replaceable> SET <replaceable>varname</replaceable> { TO | = } {
<replaceable>value</replaceable>| DEFAULT } 
! ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>varname</replaceable>
  </synopsis>
   </refsynopsisdiv>

--- 36,43 ----

  ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>

! ALTER USER <replaceable class="PARAMETER">name</replaceable> SET <replaceable>configuration_parameter</replaceable> {
TO| = } { <replaceable>value</replaceable> | DEFAULT } 
! ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>configuration_parameter</replaceable>
  </synopsis>
   </refsynopsisdiv>

Index: doc/src/sgml/ref/reset.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v
retrieving revision 1.29
diff -c -c -r1.29 reset.sgml
*** doc/src/sgml/ref/reset.sgml    25 Apr 2006 14:47:29 -0000    1.29
--- doc/src/sgml/ref/reset.sgml    25 Apr 2006 14:55:23 -0000
***************
*** 20,26 ****

   <refsynopsisdiv>
  <synopsis>
! RESET <replaceable class="PARAMETER">varname</replaceable>
  RESET ALL
  </synopsis>
   </refsynopsisdiv>
--- 20,26 ----

   <refsynopsisdiv>
  <synopsis>
! RESET <replaceable class="PARAMETER">configuration_parameter</replaceable>
  RESET ALL
  </synopsis>
   </refsynopsisdiv>
***************
*** 33,39 ****
     default values.  <command>RESET</command> is an alternative
     spelling for
  <synopsis>
! SET <replaceable class="parameter">varname</replaceable> TO DEFAULT
  </synopsis>
     Refer to <xref linkend="sql-set" endterm="sql-set-title"> for
     details.
--- 33,39 ----
     default values.  <command>RESET</command> is an alternative
     spelling for
  <synopsis>
! SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFAULT
  </synopsis>
     Refer to <xref linkend="sql-set" endterm="sql-set-title"> for
     details.
***************
*** 62,68 ****

    <variablelist>
     <varlistentry>
!     <term><replaceable class="PARAMETER">varname</replaceable></term>
      <listitem>
       <para>
        The name of a run-time parameter. See <xref linkend="sql-set"
--- 62,68 ----

    <variablelist>
     <varlistentry>
!     <term><replaceable class="PARAMETER">configuration_parameter</replaceable></term>
      <listitem>
       <para>
        The name of a run-time parameter. See <xref linkend="sql-set"
Index: doc/src/sgml/ref/set.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v
retrieving revision 1.87
diff -c -c -r1.87 set.sgml
*** doc/src/sgml/ref/set.sgml    25 Apr 2006 14:47:29 -0000    1.87
--- doc/src/sgml/ref/set.sgml    25 Apr 2006 14:55:23 -0000
***************
*** 20,26 ****

   <refsynopsisdiv>
  <synopsis>
! SET [ SESSION | LOCAL ] <replaceable class="PARAMETER">varname</replaceable> { TO | = } { <replaceable
class="PARAMETER">value</replaceable>| '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT } 
  SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</replaceable> | LOCAL | DEFAULT }
  </synopsis>
   </refsynopsisdiv>
--- 20,26 ----

   <refsynopsisdiv>
  <synopsis>
! SET [ SESSION | LOCAL ] <replaceable class="PARAMETER">configuration_parameter</replaceable> { TO | = } {
<replaceableclass="PARAMETER">value</replaceable> | '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT } 
  SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</replaceable> | LOCAL | DEFAULT }
  </synopsis>
   </refsynopsisdiv>
***************
*** 91,97 ****
     </varlistentry>

     <varlistentry>
!     <term><replaceable class="PARAMETER">varname</replaceable></term>
      <listitem>
       <para>
        Name of a settable run-time parameter.  Available parameters are
--- 91,97 ----
     </varlistentry>

     <varlistentry>
!     <term><replaceable class="PARAMETER">configuration_parameter</replaceable></term>
      <listitem>
       <para>
        Name of a settable run-time parameter.  Available parameters are