varname for GUC variables

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

varname for GUC variables

От:
Bruce Momjian <bruce@momjian.us>
Дата:
I have applied the attached patch to use  SGML markup
consistently for GUC variables.  Should we be using  to link to
more GUC details in the docs?  E.g., change:

	standard_conforming_strings</>

to:

	

-- 
  Bruce Momjian          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 ****
     
  
     
!     timezone_abbreviations</> can be set to any file name
      found in .../share/timezonesets/</>, if the file's name
      is entirely alphabetic.  (The prohibition against non-alphabetic
!     characters in timezone_abbreviations</> prevents reading
      files outside the intended directory, as well as reading editor
      backup files and other extraneous files.)
     
--- 360,369 ----
     
  
     
!     timezone_abbreviations</> can be set to any file name
      found in .../share/timezonesets/</>, if the file's name
      is entirely alphabetic.  (The prohibition against non-alphabetic
!     characters in timezone_abbreviations</> prevents reading
      files outside the intended directory, as well as reading editor
      backup files and other extraneous files.)
     
***************
*** 420,426 ****
      according to the 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 timezone_abbreviations</> settings, because of
      the dot embedded in their names.
     
  
--- 420,426 ----
      according to the 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 timezone_abbreviations</> settings, because of
      the dot embedded in their names.
     
  
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 ****
  
        
         Parameters reported as of the current release include
!        server_version</>,
!        server_encoding</>,
!        client_encoding</>,
!        application_name</>,
!        is_superuser</>,
!        session_authorization</>,
!        DateStyle</>,
!        IntervalStyle</>,
!        TimeZone</>,
!        integer_datetimes</>, and
!        standard_conforming_strings</>.
!        (server_encoding</>, TimeZone</>, and
!        integer_datetimes</> were not reported by releases before 8.0;
!        standard_conforming_strings</> was not reported by releases
         before 8.1;
!        IntervalStyle</> was not reported by releases before 8.4;
!        application_name</> was not reported by releases before 9.0.)
         Note that
!        server_version</>,
!        server_encoding</> and
!        integer_datetimes</>
         cannot change after startup.
        
  
        
         Pre-3.0-protocol servers do not report parameter settings, but
         libpq</> includes logic to obtain values for
!        server_version</> and client_encoding</> anyway.
         Applications are encouraged to use PQparameterStatus</>
         rather than ad hoc</> code to determine these values.
         (Beware however that on a pre-3.0 connection, changing
!        client_encoding</> via SET</> after connection
         startup will not be reflected by PQparameterStatus</>.)
!        For server_version</>, see also
         PQserverVersion</>, which returns the information in a
         numeric form that is much easier to compare against.
        
  
        
!        If no value for standard_conforming_strings</> is reported,
         applications can assume it is 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 ----
  
        
         Parameters reported as of the current release include
!        server_version</>,
!        server_encoding</>,
!        client_encoding</>,
!        application_name</>,
!        is_superuser</>,
!        session_authorization</>,
!        DateStyle</>,
!        IntervalStyle</>,
!        TimeZone</>,
!        integer_datetimes</>, and
!        standard_conforming_strings</>.
!        (server_encoding</>, TimeZone</>, and
!        integer_datetimes</> were not reported by releases before 8.0;
!        standard_conforming_strings</> was not reported by releases
         before 8.1;
!        IntervalStyle</> was not reported by releases before 8.4;
!        application_name</> was not reported by releases before 9.0.)
         Note that
!        server_version</>,
!        server_encoding</> and
!        integer_datetimes</>
         cannot change after startup.
        
  
        
         Pre-3.0-protocol servers do not report parameter settings, but
         libpq</> includes logic to obtain values for
!        server_version</> and client_encoding</> anyway.
         Applications are encouraged to use PQparameterStatus</>
         rather than ad hoc</> code to determine these values.
         (Beware however that on a pre-3.0 connection, changing
!        client_encoding</> via SET</> after connection
         startup will not be reflected by PQparameterStatus</>.)
!        For server_version</>, see also
         PQserverVersion</>, which returns the information in a
         numeric form that is much easier to compare against.
        
  
        
!        If no value for standard_conforming_strings</> is reported,
         applications can assume it is 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,
!     autovacuum_vacuum_cost_delay and
!     autovacuum_vacuum_cost_limit, are used to set
      table-specific values for the cost-based vacuum delay feature
      (see ).
!     autovacuum_freeze_min_age,
!     autovacuum_freeze_max_age and
!     autovacuum_freeze_table_age are used to set
      values for ,
       and
       respectively.
--- 670,682 ----
      autovacuum will only touch the table if it must do so
      to prevent transaction ID wraparound.
      Another two parameters,
!     autovacuum_vacuum_cost_delay</> and
!     autovacuum_vacuum_cost_limit</>, are used to set
      table-specific values for the cost-based vacuum delay feature
      (see ).
!     autovacuum_freeze_min_age</>,
!     autovacuum_freeze_max_age</> and
!     autovacuum_freeze_table_age</> are used to set
      values for ,
       and
       respectively.
*************** analyze threshold = analyze base thresho
*** 764,770 ****
     A better approach is to send the server's
     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 logging_collector</> to
     true</> in postgresql.conf</>.  The control
     parameters for this program are described in . You can also use this approach
--- 764,770 ----
     A better approach is to send the server's
     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 logging_collector</> to
     true</> in postgresql.conf</>.  The control
     parameters for this program are described in . 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 syslog</> and let
     syslog</> deal with file rotation. To do this, set the
!    configuration parameter log_destination</> to syslog</>
     (to log to syslog</> only) in
     postgresql.conf</>. Then you can send a SIGHUP
     signal to the syslog</> daemon whenever you want to force it
--- 794,800 ----
     Another production-grade approach to managing log output is to
     send it to syslog</> and let
     syslog</> deal with file rotation. To do this, set the
!    configuration parameter log_destination</> to syslog</>
     (to log to syslog</> only) in
     postgresql.conf</>. Then you can send a SIGHUP
     signal to the 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'
  
     where the archive directory is physically located on the standby server,
!    so that the archive_command</> is accessing it across NFS,
     but the files are local to the standby.
     This will:
    
--- 111,117 ----
  archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>cleanup.log'
  
     where the archive directory is physically located on the standby server,
!    so that the archive_command</> is accessing it across NFS,
     but the files are local to the standby.
     This will:
    
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 ****
  
   
    pg_standby</> is designed to be a waiting
!   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 ).
--- 15,21 ----
  
   
    pg_standby</> is designed to be a waiting
!   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 ).
*************** restore_command = 'pg_standby 
  pg_standby  option</> ...  archivelocation</> nextwalfile</> xlogfilepath</>  restartwalfile</> 
  
!    When used within restore_command, the %f</> and
     %p</> macros should be specified for nextwalfile</>
     and xlogfilepath</> respectively, to provide the actual file
     and path required for the restore.
--- 61,67 ----
  
  pg_standby  option</> ...  archivelocation</> nextwalfile</> xlogfilepath</>  restartwalfile</> 
  
!    When used within restore_command</>, the %f</> and
     %p</> macros should be specified for nextwalfile</>
     and 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'
  
     where the archive directory is physically located on the standby server,
!    so that the archive_command</> is accessing it across NFS,
     but the files are local to the standby (enabling use of ln</>).
     This will:
    
--- 241,247 ----
  recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'
  
     where the archive directory is physically located on the standby server,
!    so that the archive_command</> is accessing it across NFS,
     but the files are local to the standby (enabling use of ln</>).
     This will:
    
*************** restore_command = 'pg_standby -d -s 5 -t
*** 285,292 ****
  recovery_end_command = 'del C:\pgsql.trigger.5442'
  
     Note that backslashes need to be doubled in the
!    archive_command</>, but not in the
!    restore_command</> or recovery_end_command</>.
     This will:
    
     
--- 285,292 ----
  recovery_end_command = 'del C:\pgsql.trigger.5442'
  
     Note that backslashes need to be doubled in the
!    archive_command</>, but not in the
!    restore_command</> or recovery_end_command</>.
     This will:
    
     
*************** recovery_end_command = 'del C:\pgsql.tri
*** 357,363 ****
    
    
     PostgreSQL</> 8.4 provides the
!    recovery_end_command option.  Without this option
     a leftover trigger file can be hazardous.
    
   
--- 357,363 ----
    
    
     PostgreSQL</> 8.4 provides the
!    recovery_end_command</> option.  Without this option
     a leftover trigger file can be hazardous.
    
   
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 ****
     
      At present there is a hard-wired set of parameters for which
      ParameterStatus will be generated: they are
!     server_version</>,
!     server_encoding</>,
!     client_encoding</>,
!     application_name</>,
!     is_superuser</>,
!     session_authorization</>,
!     DateStyle</>,
!     IntervalStyle</>,
!     TimeZone</>,
!     integer_datetimes</>, and
!     standard_conforming_strings</>.
!     (server_encoding</>, TimeZone</>, and
!     integer_datetimes</> were not reported by releases before 8.0;
!     standard_conforming_strings</> was not reported by releases
      before 8.1;
!     IntervalStyle</> was not reported by releases before 8.4;
!     application_name</> was not reported by releases before 9.0.)
      Note that
!     server_version</>,
!     server_encoding</> and
!     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 ----
     
      At present there is a hard-wired set of parameters for which
      ParameterStatus will be generated: they are
!     server_version</>,
!     server_encoding</>,
!     client_encoding</>,
!     application_name</>,
!     is_superuser</>,
!     session_authorization</>,
!     DateStyle</>,
!     IntervalStyle</>,
!     TimeZone</>,
!     integer_datetimes</>, and
!     standard_conforming_strings</>.
!     (server_encoding</>, TimeZone</>, and
!     integer_datetimes</> were not reported by releases before 8.0;
!     standard_conforming_strings</> was not reported by releases
      before 8.1;
!     IntervalStyle</> was not reported by releases before 8.4;
!     application_name</> was not reported by releases before 9.0.)
      Note that
!     server_version</>,
!     server_encoding</> and
!     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 ****
    
     The database activity of pg_dump is
     normally collected by the statistics collector.  If this is
!    undesirable, you can set parameter track_counts
     to false via PGOPTIONS or the ALTER
     USER command.
    
--- 864,870 ----
    
     The database activity of pg_dump is
     normally collected by the statistics collector.  If this is
!    undesirable, you can set parameter track_counts</>
     to false via PGOPTIONS or the ALTER
     USER command.
    

Re: varname for GUC variables

От:
Tom Lane <tgl@sss.pgh.pa.us>
Дата:
Bruce Momjian  writes:
> I have applied the attached patch to use  SGML markup
> consistently for GUC variables.  Should we be using  to link to
> more GUC details in the docs?

For the most part I think we do have enough links.  In particular I do
*not* want to see multiple references to the same variable in the same
paragraph all turned into links; that's just distracting.

			regards, tom lane

Re: varname for GUC variables

От:
Bruce Momjian <bruce@momjian.us>
Дата:
Tom Lane wrote:
> Bruce Momjian  writes:
> > I have applied the attached patch to use  SGML markup
> > consistently for GUC variables.  Should we be using  to link to
> > more GUC details in the docs?
> 
> For the most part I think we do have enough links.  In particular I do
> *not* want to see multiple references to the same variable in the same
> paragraph all turned into links; that's just distracting.

True on the multiple instances in a paragraph.  I will drop it unless
someone feels we need more.  Thanks.

-- 
  Bruce Momjian          http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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