pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedvarname for GUC variables
3+ messages / 2 participants
[nested] [flat]
* varname for GUC variables
@ 2011-02-02 23:10 Bruce Momjian <bruce@momjian.us>
2011-02-02 23:14 ` Re: varname for GUC variables Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 3+ messages in thread
From: Bruce Momjian @ 2011-02-02 23:10 UTC (permalink / raw)
To: 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. +
Attachments:
/rtmp/varname.diff (text/x-diff, 18.5K) download
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>
* Re: varname for GUC variables
2011-02-02 23:10 varname for GUC variables Bruce Momjian <bruce@momjian.us>
@ 2011-02-02 23:14 ` Tom Lane <tgl@sss.pgh.pa.us>
2011-02-02 23:17 ` Re: varname for GUC variables Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 3+ messages in thread
From: Tom Lane @ 2011-02-02 23:14 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs
Bruce Momjian <bruce@momjian.us> writes:
> 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?
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
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: varname for GUC variables
2011-02-02 23:10 varname for GUC variables Bruce Momjian <bruce@momjian.us>
2011-02-02 23:14 ` Re: varname for GUC variables Tom Lane <tgl@sss.pgh.pa.us>
@ 2011-02-02 23:17 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 3+ messages in thread
From: Bruce Momjian @ 2011-02-02 23:17 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > 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?
>
> 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 <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2011-02-02 23:17 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2011-02-02 23:10 varname for GUC variables Bruce Momjian <bruce@momjian.us>
2011-02-02 23:14 ` Tom Lane <tgl@sss.pgh.pa.us>
2011-02-02 23:17 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox