Обсуждение: minor doc work

Поиск
Список
Период
Сортировка

minor doc work

От
Neil Conway
Дата:
I've applied the two attached minor documentation patches to HEAD.
Each patch makes a few minor improvements to a particular section of
the docs (the discussion of IS NULL and the discussion of SET,
respectively).

Cheers,

Neil
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/func.sgml,v
retrieving revision 1.191
diff -c -r1.191 func.sgml
*** a/doc/src/sgml/func.sgml    5 Mar 2004 02:41:14 -0000    1.191
--- b/doc/src/sgml/func.sgml    5 Mar 2004 19:50:42 -0000
***************
*** 301,320 ****
      <literal><replaceable>expression</replaceable> = NULL</literal>
      because <literal>NULL</> is not <quote>equal to</quote>
      <literal>NULL</>.  (The null value represents an unknown value,
!     and it is not known whether two unknown values are equal.)
     </para>

     <para>
!     Some applications may (incorrectly) require that
      <literal><replaceable>expression</replaceable> = NULL</literal>
      returns true if <replaceable>expression</replaceable> evaluates to
!     the null value.  To support these applications, the run-time option
!     <varname>transform_null_equals</varname> can be turned on (e.g.,
!     <literal>SET transform_null_equals TO ON;</literal>).
!     <productname>PostgreSQL</productname> will then convert
!     <literal>x = NULL</literal> clauses to
!     <literal>x IS NULL</literal>.  This was
!     the default behavior in releases 6.5 through 7.1.
     </para>

     <para>
--- 301,322 ----
      <literal><replaceable>expression</replaceable> = NULL</literal>
      because <literal>NULL</> is not <quote>equal to</quote>
      <literal>NULL</>.  (The null value represents an unknown value,
!     and it is not known whether two unknown values are equal.) This
!     behavior conforms to the SQL standard.
     </para>

     <para>
!     Some applications may expect that
      <literal><replaceable>expression</replaceable> = NULL</literal>
      returns true if <replaceable>expression</replaceable> evaluates to
!     the null value.  It is highly recommended that these applications
!     be modified to comply with the SQL standard. However, if that
!     cannot be done the <varname>transform_null_equals</varname>
!     configuration variable is available. If it is enabled,
!     <productname>PostgreSQL</productname> will convert <literal>x =
!     NULL</literal> clauses to <literal>x IS NULL</literal>.  This was
!     the default behavior in <productname>PostgreSQL</productname>
!     releases 6.5 through 7.1.
     </para>

     <para>
Index: doc/src/sgml/runtime.sgml
===================================================================
RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/runtime.sgml,v
retrieving revision 1.244
diff -c -r1.244 runtime.sgml
*** a/doc/src/sgml/runtime.sgml    5 Mar 2004 23:16:17 -0000    1.244
--- b/doc/src/sgml/runtime.sgml    7 Mar 2004 00:59:19 -0000
***************
*** 541,548 ****
  SET ENABLE_SEQSCAN TO OFF;
  </screen>
      If <command>SET</> is allowed, it overrides all other sources of
!     values for the parameter.  Superusers are allowed to <command>SET</>
!     more values than ordinary users.
     </para>

     <para>
--- 541,551 ----
  SET ENABLE_SEQSCAN TO OFF;
  </screen>
      If <command>SET</> is allowed, it overrides all other sources of
!     values for the parameter.  Superusers are allowed to
!     <command>SET</> more values than ordinary users.  Some parameters
!     cannot be <command>SET</command> even by superusers: for example,
!     if they control behavior that cannot reasonably be changed without
!     restarting <productname>PostgreSQL</productname>.
     </para>

     <para>

Re: minor doc work

От
Peter Eisentraut
Дата:
Neil Conway wrote:
>       If <command>SET</> is allowed, it overrides all other sources of
> !     values for the parameter.  Superusers are allowed to
> !     <command>SET</> more values than ordinary users.  Some parameters
> !     cannot be <command>SET</command> even by superusers: for example,

Please don't use marked up command names as verbs.  Next week you'll be
<command>UPDATE</command>ing or something.  Here, there is no chance for
confusion, so just write "cannot be set" or "cannot be changed with
<command>SET</command>".  In fact, the latter is even clearer.

> !     if they control behavior that cannot reasonably be changed without
> !     restarting <productname>PostgreSQL</productname>.


Re: minor doc work

От
Neil Conway
Дата:
Peter Eisentraut <peter_e@gmx.net> writes:
> Please don't use marked up command names as verbs.  Next week you'll
> be <command>UPDATE</command>ing or something.

The existing documentation does this -- indeed, the very section of
the docs that I modified *already* did it:

      If <command>SET</> is allowed, it overrides all other sources of
!     values for the parameter.  Superusers are allowed to <command>SET</>
!     more values than ordinary users.

(which was the original text)

I've modified this particular section per your suggestion, but I
haven't made any wider changes (i.e. this style is still used in other
places).

-Neil