varname for GUC variables - Mailing list pgsql-docs

I have applied the attached patch to use <varname> SGML markup
consistently for GUC variables.  Should we be using <xref> to link to
more GUC details in the docs?  E.g., change:

    <varname>standard_conforming_strings</>

to:

    <xref linkend="guc-standard-conforming-strings">

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
index 0b55446..707bd5a 100644
*** a/doc/src/sgml/datetime.sgml
--- b/doc/src/sgml/datetime.sgml
***************
*** 360,369 ****
     </para>

     <para>
!     <literal>timezone_abbreviations</> can be set to any file name
      found in <filename>.../share/timezonesets/</>, if the file's name
      is entirely alphabetic.  (The prohibition against non-alphabetic
!     characters in <literal>timezone_abbreviations</> prevents reading
      files outside the intended directory, as well as reading editor
      backup files and other extraneous files.)
     </para>
--- 360,369 ----
     </para>

     <para>
!     <varname>timezone_abbreviations</> can be set to any file name
      found in <filename>.../share/timezonesets/</>, if the file's name
      is entirely alphabetic.  (The prohibition against non-alphabetic
!     characters in <varname>timezone_abbreviations</> prevents reading
      files outside the intended directory, as well as reading editor
      backup files and other extraneous files.)
     </para>
***************
*** 420,426 ****
      according to the <literal>zoneinfo</> timezone database.  The zone name
      definitions found in these files can be copied and pasted into a custom
      configuration file as needed.  Note that these files cannot be directly
!     referenced as <literal>timezone_abbreviations</> settings, because of
      the dot embedded in their names.
     </para>

--- 420,426 ----
      according to the <literal>zoneinfo</> timezone database.  The zone name
      definitions found in these files can be copied and pasted into a custom
      configuration file as needed.  Note that these files cannot be directly
!     referenced as <varname>timezone_abbreviations</> settings, because of
      the dot embedded in their names.
     </para>

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7b70970..ab09f35 100644
*** a/doc/src/sgml/libpq.sgml
--- b/doc/src/sgml/libpq.sgml
*************** const char *PQparameterStatus(const PGco
*** 1418,1463 ****

        <para>
         Parameters reported as of the current release include
!        <literal>server_version</>,
!        <literal>server_encoding</>,
!        <literal>client_encoding</>,
!        <literal>application_name</>,
!        <literal>is_superuser</>,
!        <literal>session_authorization</>,
!        <literal>DateStyle</>,
!        <literal>IntervalStyle</>,
!        <literal>TimeZone</>,
!        <literal>integer_datetimes</>, and
!        <literal>standard_conforming_strings</>.
!        (<literal>server_encoding</>, <literal>TimeZone</>, and
!        <literal>integer_datetimes</> were not reported by releases before 8.0;
!        <literal>standard_conforming_strings</> was not reported by releases
         before 8.1;
!        <literal>IntervalStyle</> was not reported by releases before 8.4;
!        <literal>application_name</> was not reported by releases before 9.0.)
         Note that
!        <literal>server_version</>,
!        <literal>server_encoding</> and
!        <literal>integer_datetimes</>
         cannot change after startup.
        </para>

        <para>
         Pre-3.0-protocol servers do not report parameter settings, but
         <application>libpq</> includes logic to obtain values for
!        <literal>server_version</> and <literal>client_encoding</> anyway.
         Applications are encouraged to use <function>PQparameterStatus</>
         rather than <foreignphrase>ad hoc</> code to determine these values.
         (Beware however that on a pre-3.0 connection, changing
!        <literal>client_encoding</> via <command>SET</> after connection
         startup will not be reflected by <function>PQparameterStatus</>.)
!        For <literal>server_version</>, see also
         <function>PQserverVersion</>, which returns the information in a
         numeric form that is much easier to compare against.
        </para>

        <para>
!        If no value for <literal>standard_conforming_strings</> is reported,
         applications can assume it is <literal>off</>, that is, backslashes
         are treated as escapes in string literals.  Also, the presence of
         this parameter can be taken as an indication that the escape string
--- 1418,1463 ----

        <para>
         Parameters reported as of the current release include
!        <varname>server_version</>,
!        <varname>server_encoding</>,
!        <varname>client_encoding</>,
!        <varname>application_name</>,
!        <varname>is_superuser</>,
!        <varname>session_authorization</>,
!        <varname>DateStyle</>,
!        <varname>IntervalStyle</>,
!        <varname>TimeZone</>,
!        <varname>integer_datetimes</>, and
!        <varname>standard_conforming_strings</>.
!        (<varname>server_encoding</>, <varname>TimeZone</>, and
!        <varname>integer_datetimes</> were not reported by releases before 8.0;
!        <varname>standard_conforming_strings</> was not reported by releases
         before 8.1;
!        <varname>IntervalStyle</> was not reported by releases before 8.4;
!        <varname>application_name</> was not reported by releases before 9.0.)
         Note that
!        <varname>server_version</>,
!        <varname>server_encoding</> and
!        <varname>integer_datetimes</>
         cannot change after startup.
        </para>

        <para>
         Pre-3.0-protocol servers do not report parameter settings, but
         <application>libpq</> includes logic to obtain values for
!        <varname>server_version</> and <varname>client_encoding</> anyway.
         Applications are encouraged to use <function>PQparameterStatus</>
         rather than <foreignphrase>ad hoc</> code to determine these values.
         (Beware however that on a pre-3.0 connection, changing
!        <varname>client_encoding</> via <command>SET</> after connection
         startup will not be reflected by <function>PQparameterStatus</>.)
!        For <varname>server_version</>, see also
         <function>PQserverVersion</>, which returns the information in a
         numeric form that is much easier to compare against.
        </para>

        <para>
!        If no value for <varname>standard_conforming_strings</> is reported,
         applications can assume it is <literal>off</>, that is, backslashes
         are treated as escapes in string literals.  Also, the presence of
         this parameter can be taken as an indication that the escape string
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index f3d1669..03cc6c9 100644
*** a/doc/src/sgml/maintenance.sgml
--- b/doc/src/sgml/maintenance.sgml
*************** analyze threshold = analyze base thresho
*** 670,682 ****
      autovacuum will only touch the table if it must do so
      to prevent transaction ID wraparound.
      Another two parameters,
!     <literal>autovacuum_vacuum_cost_delay</literal> and
!     <literal>autovacuum_vacuum_cost_limit</literal>, are used to set
      table-specific values for the cost-based vacuum delay feature
      (see <xref linkend="runtime-config-resource-vacuum-cost">).
!     <literal>autovacuum_freeze_min_age</literal>,
!     <literal>autovacuum_freeze_max_age</literal> and
!     <literal>autovacuum_freeze_table_age</literal> are used to set
      values for <xref linkend="guc-vacuum-freeze-min-age">,
      <xref linkend="guc-autovacuum-freeze-max-age"> and
      <xref linkend="guc-vacuum-freeze-table-age"> respectively.
--- 670,682 ----
      autovacuum will only touch the table if it must do so
      to prevent transaction ID wraparound.
      Another two parameters,
!     <varname>autovacuum_vacuum_cost_delay</> and
!     <varname>autovacuum_vacuum_cost_limit</>, are used to set
      table-specific values for the cost-based vacuum delay feature
      (see <xref linkend="runtime-config-resource-vacuum-cost">).
!     <varname>autovacuum_freeze_min_age</>,
!     <varname>autovacuum_freeze_max_age</> and
!     <varname>autovacuum_freeze_table_age</> are used to set
      values for <xref linkend="guc-vacuum-freeze-min-age">,
      <xref linkend="guc-autovacuum-freeze-max-age"> and
      <xref linkend="guc-vacuum-freeze-table-age"> respectively.
*************** analyze threshold = analyze base thresho
*** 764,770 ****
     A better approach is to send the server's
     <systemitem>stderr</> output to some type of log rotation program.
     There is a built-in log rotation facility, which you can use by
!    setting the configuration parameter <literal>logging_collector</> to
     <literal>true</> in <filename>postgresql.conf</>.  The control
     parameters for this program are described in <xref
     linkend="runtime-config-logging-where">. You can also use this approach
--- 764,770 ----
     A better approach is to send the server's
     <systemitem>stderr</> output to some type of log rotation program.
     There is a built-in log rotation facility, which you can use by
!    setting the configuration parameter <varname>logging_collector</> to
     <literal>true</> in <filename>postgresql.conf</>.  The control
     parameters for this program are described in <xref
     linkend="runtime-config-logging-where">. You can also use this approach
*************** pg_ctl start | rotatelogs /var/log/pgsql
*** 794,800 ****
     Another production-grade approach to managing log output is to
     send it to <application>syslog</> and let
     <application>syslog</> deal with file rotation. To do this, set the
!    configuration parameter <literal>log_destination</> to <literal>syslog</>
     (to log to <application>syslog</> only) in
     <filename>postgresql.conf</>. Then you can send a <literal>SIGHUP</literal>
     signal to the <application>syslog</> daemon whenever you want to force it
--- 794,800 ----
     Another production-grade approach to managing log output is to
     send it to <application>syslog</> and let
     <application>syslog</> deal with file rotation. To do this, set the
!    configuration parameter <varname>log_destination</> to <literal>syslog</>
     (to log to <application>syslog</> only) in
     <filename>postgresql.conf</>. Then you can send a <literal>SIGHUP</literal>
     signal to the <application>syslog</> daemon whenever you want to force it
diff --git a/doc/src/sgml/pgarchivecleanup.sgml b/doc/src/sgml/pgarchivecleanup.sgml
index 026f5b2..725f3ed 100644
*** a/doc/src/sgml/pgarchivecleanup.sgml
--- b/doc/src/sgml/pgarchivecleanup.sgml
*************** pg_archivecleanup:  removing file "archi
*** 111,117 ****
  archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>cleanup.log'
  </programlisting>
     where the archive directory is physically located on the standby server,
!    so that the <literal>archive_command</> is accessing it across NFS,
     but the files are local to the standby.
     This will:
    </para>
--- 111,117 ----
  archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>cleanup.log'
  </programlisting>
     where the archive directory is physically located on the standby server,
!    so that the <varname>archive_command</> is accessing it across NFS,
     but the files are local to the standby.
     This will:
    </para>
diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml
index a99fdf9..7f0a874 100644
*** a/doc/src/sgml/pgstandby.sgml
--- b/doc/src/sgml/pgstandby.sgml
***************
*** 15,21 ****

   <para>
    <application>pg_standby</> is designed to be a waiting
!   <literal>restore_command</literal>, which is needed to turn a standard
    archive recovery into a warm standby operation.  Other
    configuration is required as well, all of which is described in the main
    server manual (see <xref linkend="warm-standby">).
--- 15,21 ----

   <para>
    <application>pg_standby</> is designed to be a waiting
!   <varname>restore_command</>, which is needed to turn a standard
    archive recovery into a warm standby operation.  Other
    configuration is required as well, all of which is described in the main
    server manual (see <xref linkend="warm-standby">).
*************** restore_command = 'pg_standby <replaceab
*** 61,67 ****
  <synopsis>
  pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</>
<replaceable>nextwalfile</><replaceable>xlogfilepath</> <optional> <replaceable>restartwalfile</> </optional> 
  </synopsis>
!    When used within <literal>restore_command</literal>, the <literal>%f</> and
     <literal>%p</> macros should be specified for <replaceable>nextwalfile</>
     and <replaceable>xlogfilepath</> respectively, to provide the actual file
     and path required for the restore.
--- 61,67 ----
  <synopsis>
  pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</>
<replaceable>nextwalfile</><replaceable>xlogfilepath</> <optional> <replaceable>restartwalfile</> </optional> 
  </synopsis>
!    When used within <varname>restore_command</>, the <literal>%f</> and
     <literal>%p</> macros should be specified for <replaceable>nextwalfile</>
     and <replaceable>xlogfilepath</> respectively, to provide the actual file
     and path required for the restore.
*************** restore_command = 'pg_standby -d -s 2 -t
*** 241,247 ****
  recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'
  </programlisting>
     where the archive directory is physically located on the standby server,
!    so that the <literal>archive_command</> is accessing it across NFS,
     but the files are local to the standby (enabling use of <literal>ln</>).
     This will:
    <itemizedlist>
--- 241,247 ----
  recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'
  </programlisting>
     where the archive directory is physically located on the standby server,
!    so that the <varname>archive_command</> is accessing it across NFS,
     but the files are local to the standby (enabling use of <literal>ln</>).
     This will:
    <itemizedlist>
*************** restore_command = 'pg_standby -d -s 5 -t
*** 285,292 ****
  recovery_end_command = 'del C:\pgsql.trigger.5442'
  </programlisting>
     Note that backslashes need to be doubled in the
!    <literal>archive_command</>, but <emphasis>not</emphasis> in the
!    <literal>restore_command</> or <literal>recovery_end_command</>.
     This will:
    <itemizedlist>
     <listitem>
--- 285,292 ----
  recovery_end_command = 'del C:\pgsql.trigger.5442'
  </programlisting>
     Note that backslashes need to be doubled in the
!    <varname>archive_command</>, but <emphasis>not</emphasis> in the
!    <varname>restore_command</> or <varname>recovery_end_command</>.
     This will:
    <itemizedlist>
     <listitem>
*************** recovery_end_command = 'del C:\pgsql.tri
*** 357,363 ****
    </para>
    <para>
     <productname>PostgreSQL</> 8.4 provides the
!    <literal>recovery_end_command</literal> option.  Without this option
     a leftover trigger file can be hazardous.
    </para>
   </sect2>
--- 357,363 ----
    </para>
    <para>
     <productname>PostgreSQL</> 8.4 provides the
!    <varname>recovery_end_command</> option.  Without this option
     a leftover trigger file can be hazardous.
    </para>
   </sect2>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 73c05ed..4521496 100644
*** a/doc/src/sgml/protocol.sgml
--- b/doc/src/sgml/protocol.sgml
***************
*** 1092,1118 ****
     <para>
      At present there is a hard-wired set of parameters for which
      ParameterStatus will be generated: they are
!     <literal>server_version</>,
!     <literal>server_encoding</>,
!     <literal>client_encoding</>,
!     <literal>application_name</>,
!     <literal>is_superuser</>,
!     <literal>session_authorization</>,
!     <literal>DateStyle</>,
!     <literal>IntervalStyle</>,
!     <literal>TimeZone</>,
!     <literal>integer_datetimes</>, and
!     <literal>standard_conforming_strings</>.
!     (<literal>server_encoding</>, <literal>TimeZone</>, and
!     <literal>integer_datetimes</> were not reported by releases before 8.0;
!     <literal>standard_conforming_strings</> was not reported by releases
      before 8.1;
!     <literal>IntervalStyle</> was not reported by releases before 8.4;
!     <literal>application_name</> was not reported by releases before 9.0.)
      Note that
!     <literal>server_version</>,
!     <literal>server_encoding</> and
!     <literal>integer_datetimes</>
      are pseudo-parameters that cannot change after startup.
      This set might change in the future, or even become configurable.
      Accordingly, a frontend should simply ignore ParameterStatus for
--- 1092,1118 ----
     <para>
      At present there is a hard-wired set of parameters for which
      ParameterStatus will be generated: they are
!     <varname>server_version</>,
!     <varname>server_encoding</>,
!     <varname>client_encoding</>,
!     <varname>application_name</>,
!     <varname>is_superuser</>,
!     <varname>session_authorization</>,
!     <varname>DateStyle</>,
!     <varname>IntervalStyle</>,
!     <varname>TimeZone</>,
!     <varname>integer_datetimes</>, and
!     <varname>standard_conforming_strings</>.
!     (<varname>server_encoding</>, <varname>TimeZone</>, and
!     <varname>integer_datetimes</> were not reported by releases before 8.0;
!     <varname>standard_conforming_strings</> was not reported by releases
      before 8.1;
!     <varname>IntervalStyle</> was not reported by releases before 8.4;
!     <varname>application_name</> was not reported by releases before 9.0.)
      Note that
!     <varname>server_version</>,
!     <varname>server_encoding</> and
!     <varname>integer_datetimes</>
      are pseudo-parameters that cannot change after startup.
      This set might change in the future, or even become configurable.
      Accordingly, a frontend should simply ignore ParameterStatus for
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index fdc4b92..f90d669 100644
*** a/doc/src/sgml/ref/pg_dump.sgml
--- b/doc/src/sgml/ref/pg_dump.sgml
*************** PostgreSQL documentation
*** 864,870 ****
    <para>
     The database activity of <application>pg_dump</application> is
     normally collected by the statistics collector.  If this is
!    undesirable, you can set parameter <literal>track_counts</literal>
     to false via <envar>PGOPTIONS</envar> or the <literal>ALTER
     USER</literal> command.
    </para>
--- 864,870 ----
    <para>
     The database activity of <application>pg_dump</application> is
     normally collected by the statistics collector.  If this is
!    undesirable, you can set parameter <varname>track_counts</>
     to false via <envar>PGOPTIONS</envar> or the <literal>ALTER
     USER</literal> command.
    </para>