Hi all,
This bit of "Section 18.1. Setting Parameters"[1] is highly confusing:
[Some discussion about the 'include' directive, then jump immediately
to this next paragraph with no explanatory section header.]
| Use the same approach as the include directive, continuing normally if
| the file does not exist. A regular include will stop with an error
if the referenced
| file is missing, while include_if_exists does not. A warning about
the missing
| file will be logged.
IMO the paragraph above needs to clarify that it's talking about the
"include_if_exists" directive. "include_if_exists" is not even
mentioned in the first sentence of the paragraph, and I had to look at
the SGML for that section to be sure that the paragraph was indeed
describing "include_if_exists".
Attached are two possible fixes. First is a small patch
(include_if_exists.diff) to clarify the first sentence of that
paragraph.
Second, I think Section 18.1 as a whole could be much improved by
breaking it up into sub-sections; it seems too long and disjointed
as-is. I gave this reorganization a shot with a larger patch
(setting_parameters_subsections.diff) which includes the
include_if_exists clarification, and also breaks the page up into
three sub-sections. This is my preferred fix (for now -- I'll try to
send in some further explanation/consolidation of GUC contexts
relevant to that page later).
Josh
[1] http://www.postgresql.org/docs/devel/static/config-setting.html
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
new file mode 100644
index e58dc18..881f0c4
*** a/doc/src/sgml/config.sgml
--- b/doc/src/sgml/config.sgml
*************** include 'filename'
*** 94,100 ****
<primary><literal>include_if_exists</></primary>
<secondary>in configuration file</secondary>
</indexterm>
! Use the same approach as the <literal>include</> directive, continuing
normally if the file does not exist. A regular <literal>include</>
will stop with an error if the referenced file is missing, while
<literal>include_if_exists</> does not. A warning about the missing
--- 94,101 ----
<primary><literal>include_if_exists</></primary>
<secondary>in configuration file</secondary>
</indexterm>
! The <literal>include_if_exists</> directive uses the same approach
! as the <literal>include</> directive, continuing
normally if the file does not exist. A regular <literal>include</>
will stop with an error if the referenced file is missing, while
<literal>include_if_exists</> does not. A warning about the missing
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
new file mode 100644
index e58dc18..50f6806
*** a/doc/src/sgml/config.sgml
--- b/doc/src/sgml/config.sgml
***************
*** 18,62 ****
<sect1 id="config-setting">
<title>Setting Parameters</title>
! <para>
! All parameter names are case-insensitive. Every parameter takes a
! value of one of five types: Boolean, integer, floating point,
! string or enum. Boolean values can be written as <literal>on</literal>,
! <literal>off</literal>, <literal>true</literal>,
! <literal>false</literal>, <literal>yes</literal>,
! <literal>no</literal>, <literal>1</literal>, <literal>0</literal>
! (all case-insensitive) or any unambiguous prefix of these.
! </para>
! <para>
! Some settings specify a memory or time value. Each of these has an
! implicit unit, which is either kilobytes, blocks (typically eight
! kilobytes), milliseconds, seconds, or minutes. Default units can be
! found by referencing <structname>pg_settings</>.<structfield>unit</>.
! For convenience,
! a different unit can also be specified explicitly. Valid memory units
! are <literal>kB</literal> (kilobytes), <literal>MB</literal>
! (megabytes), and <literal>GB</literal> (gigabytes); valid time units
! are <literal>ms</literal> (milliseconds), <literal>s</literal>
! (seconds), <literal>min</literal> (minutes), <literal>h</literal>
! (hours), and <literal>d</literal> (days). Note that the multiplier
! for memory units is 1024, not 1000.
! </para>
! <para>
! Parameters of type <quote>enum</> are specified in the same way as string
! parameters, but are restricted to a limited set of values. The allowed
! values can be found
! from <structname>pg_settings</>.<structfield>enumvals</>.
! Enum parameter values are case-insensitive.
! </para>
! <para>
! One way to set these parameters is to edit the file
! <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
! which is normally kept in the data directory. (A default copy is
! installed there when the database cluster directory is
! initialized.) An example of what this file might look like is:
<programlisting>
# This is a comment
log_connections = yes
--- 18,65 ----
<sect1 id="config-setting">
<title>Setting Parameters</title>
! <sect2 id="config-setting-param-names-values">
! <title>Parameter Names and Values</title>
! <para>
! All parameter names are case-insensitive. Every parameter takes a
! value of one of five types: Boolean, integer, floating point,
! string or enum. Boolean values can be written as <literal>on</literal>,
! <literal>off</literal>, <literal>true</literal>,
! <literal>false</literal>, <literal>yes</literal>,
! <literal>no</literal>, <literal>1</literal>, <literal>0</literal>
! (all case-insensitive) or any unambiguous prefix of these.
! </para>
! <para>
! Some settings specify a memory or time value. Each of these has an
! implicit unit, which is either kilobytes, blocks (typically eight
! kilobytes), milliseconds, seconds, or minutes. Default units can be
! found by referencing <structname>pg_settings</>.<structfield>unit</>.
! For convenience,
! a different unit can also be specified explicitly. Valid memory units
! are <literal>kB</literal> (kilobytes), <literal>MB</literal>
! (megabytes), and <literal>GB</literal> (gigabytes); valid time units
! are <literal>ms</literal> (milliseconds), <literal>s</literal>
! (seconds), <literal>min</literal> (minutes), <literal>h</literal>
! (hours), and <literal>d</literal> (days). Note that the multiplier
! for memory units is 1024, not 1000.
! </para>
! <para>
! Parameters of type <quote>enum</> are specified in the same way as string
! parameters, but are restricted to a limited set of values. The allowed
! values can be found
! from <structname>pg_settings</>.<structfield>enumvals</>.
! Enum parameter values are case-insensitive.
! </para>
!
! <para>
! One way to set these parameters is to edit the file
! <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
! which is normally kept in the data directory. (A default copy is
! installed there when the database cluster directory is
! initialized.) An example of what this file might look like is:
<programlisting>
# This is a comment
log_connections = yes
*************** log_destination = 'syslog'
*** 64,195 ****
search_path = '"$user", public'
shared_buffers = 128MB
</programlisting>
! One parameter is specified per line. The equal sign between name and
! value is optional. Whitespace is insignificant and blank lines are
! ignored. Hash marks (<literal>#</literal>) designate the rest of the
! line as a comment. Parameter values that are not simple identifiers or
! numbers must be single-quoted. To embed a single quote in a parameter
! value, write either two quotes (preferred) or backslash-quote.
! </para>
! <para>
! <indexterm>
! <primary><literal>include</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! In addition to parameter settings, the <filename>postgresql.conf</>
! file can contain <firstterm>include directives</>, which specify
! another file to read and process as if it were inserted into the
! configuration file at this point. Include directives simply look like:
<programlisting>
include 'filename'
</programlisting>
! If the file name is not an absolute path, it is taken as relative to
! the directory containing the referencing configuration file.
! Inclusions can be nested.
! </para>
! <para>
! <indexterm>
! <primary><literal>include_if_exists</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! Use the same approach as the <literal>include</> directive, continuing
! normally if the file does not exist. A regular <literal>include</>
! will stop with an error if the referenced file is missing, while
! <literal>include_if_exists</> does not. A warning about the missing
! file will be logged.
! </para>
! <para>
! <indexterm>
! <primary>SIGHUP</primary>
! </indexterm>
! The configuration file is reread whenever the main server process receives a
! <systemitem>SIGHUP</> signal (which is most easily sent by means
! of <literal>pg_ctl reload</>). The main server process
! also propagates this signal to all currently running server
! processes so that existing sessions also get the new
! value. Alternatively, you can send the signal to a single server
! process directly. Some parameters can only be set at server start;
! any changes to their entries in the configuration file will be ignored
! until the server is restarted. Invalid parameter settings in the
! configuration file are likewise ignored (but logged) during
! <systemitem>SIGHUP</> processing.
! </para>
! <para>
! A second way to set these configuration parameters is to give them
! as a command-line option to the <command>postgres</command> command, such as:
<programlisting>
postgres -c log_connections=yes -c log_destination='syslog'
</programlisting>
! Command-line options override any conflicting settings in
! <filename>postgresql.conf</filename>. Note that this means you won't
! be able to change the value on-the-fly by editing
! <filename>postgresql.conf</filename>, so while the command-line
! method might be convenient, it can cost you flexibility later.
! </para>
! <para>
! Occasionally it is useful to give a command line option to
! one particular session only. The environment variable
! <envar>PGOPTIONS</envar> can be used for this purpose on the
! client side:
<programlisting>
env PGOPTIONS='-c geqo=off' psql
</programlisting>
! (This works for any <application>libpq</>-based client application, not
! just <application>psql</application>.) Note that this won't work for
! parameters that are fixed when the server is started or that must be
! specified in <filename>postgresql.conf</filename>.
! </para>
! <para>
! Furthermore, it is possible to assign a set of parameter settings to
! a user or a database. Whenever a session is started, the default
! settings for the user and database involved are loaded. The
! commands <xref linkend="sql-alterrole">
! and <xref linkend="sql-alterdatabase">,
! respectively, are used to configure these settings. Per-database
! settings override anything received from the
! <command>postgres</command> command-line or the configuration
! file, and in turn are overridden by per-user settings; both are
! overridden by per-session settings.
! </para>
! <para>
! Some parameters can be changed in individual <acronym>SQL</acronym>
! sessions with the <xref linkend="SQL-SET">
! command, for example:
<screen>
SET ENABLE_SEQSCAN TO OFF;
</screen>
! If <command>SET</> is allowed, it overrides all other sources of
! values for the parameter. Some parameters cannot be changed via
! <command>SET</command>: for example, if they control behavior that
! cannot be changed without restarting the entire
! <productname>PostgreSQL</productname> server. Also,
! some <command>SET</command> or <command>ALTER</> parameter modifications
! require superuser permission.
! </para>
! <para>
! The <xref linkend="SQL-SHOW">
! command allows inspection of the current values of all parameters.
! </para>
! <para>
! The virtual table <structname>pg_settings</structname> also allows
! displaying and updating session run-time parameters; see <xref
! linkend="view-pg-settings"> for details and a description of the
! different variable types and when they can be changed.
! <structname>pg_settings</structname> is equivalent to <command>SHOW</>
! and <command>SET</>, but can be more convenient
! to use because it can be joined with other tables, or selected from using
! any desired selection condition. It also contains more information about
! what values are allowed for the parameters.
! </para>
</sect1>
<sect1 id="runtime-config-file-locations">
--- 67,210 ----
search_path = '"$user", public'
shared_buffers = 128MB
</programlisting>
! One parameter is specified per line. The equal sign between name and
! value is optional. Whitespace is insignificant and blank lines are
! ignored. Hash marks (<literal>#</literal>) designate the rest of the
! line as a comment. Parameter values that are not simple identifiers or
! numbers must be single-quoted. To embed a single quote in a parameter
! value, write either two quotes (preferred) or backslash-quote.
! </para>
! </sect2>
! <sect2 id="config-setting-include-directives">
! <title>Include Directives</title>
! <para>
! <indexterm>
! <primary><literal>include</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! In addition to parameter settings, the <filename>postgresql.conf</>
! file can contain <firstterm>include directives</>, which specify
! another file to read and process as if it were inserted into the
! configuration file at this point. Include directives simply look like:
<programlisting>
include 'filename'
</programlisting>
! If the file name is not an absolute path, it is taken as relative to
! the directory containing the referencing configuration file.
! Inclusions can be nested.
! </para>
! <para>
! <indexterm>
! <primary><literal>include_if_exists</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! The <literal>include_if_exists</> directive uses the same approach
! as the <literal>include</> directive, continuing
! normally if the file does not exist. A regular <literal>include</>
! will stop with an error if the referenced file is missing, while
! <literal>include_if_exists</> does not. A warning about the missing
! file will be logged.
! </para>
! </sect2>
! <sect2 id="config-setting-ways-to-set">
! <title>Ways to Set Parameters</title>
! <para>
! <indexterm>
! <primary>SIGHUP</primary>
! </indexterm>
! The configuration file is reread whenever the main server process
! receives a
! <systemitem>SIGHUP</> signal (which is most easily sent by means
! of <literal>pg_ctl reload</>). The main server process
! also propagates this signal to all currently running server
! processes so that existing sessions also get the new
! value. Alternatively, you can send the signal to a single server
! process directly. Some parameters can only be set at server start;
! any changes to their entries in the configuration file will be ignored
! until the server is restarted. Invalid parameter settings in the
! configuration file are likewise ignored (but logged) during
! <systemitem>SIGHUP</> processing.
! </para>
!
! <para>
! A second way to set these configuration parameters is to give them
! as a command-line option to the <command>postgres</command> command,
! such as:
<programlisting>
postgres -c log_connections=yes -c log_destination='syslog'
</programlisting>
! Command-line options override any conflicting settings in
! <filename>postgresql.conf</filename>. Note that this means you won't
! be able to change the value on-the-fly by editing
! <filename>postgresql.conf</filename>, so while the command-line
! method might be convenient, it can cost you flexibility later.
! </para>
! <para>
! Occasionally it is useful to give a command line option to
! one particular session only. The environment variable
! <envar>PGOPTIONS</envar> can be used for this purpose on the
! client side:
<programlisting>
env PGOPTIONS='-c geqo=off' psql
</programlisting>
! (This works for any <application>libpq</>-based client application, not
! just <application>psql</application>.) Note that this won't work for
! parameters that are fixed when the server is started or that must be
! specified in <filename>postgresql.conf</filename>.
! </para>
! <para>
! Furthermore, it is possible to assign a set of parameter settings to
! a user or a database. Whenever a session is started, the default
! settings for the user and database involved are loaded. The
! commands <xref linkend="sql-alterrole">
! and <xref linkend="sql-alterdatabase">,
! respectively, are used to configure these settings. Per-database
! settings override anything received from the
! <command>postgres</command> command-line or the configuration
! file, and in turn are overridden by per-user settings; both are
! overridden by per-session settings.
! </para>
! <para>
! Some parameters can be changed in individual <acronym>SQL</acronym>
! sessions with the <xref linkend="SQL-SET">
! command, for example:
<screen>
SET ENABLE_SEQSCAN TO OFF;
</screen>
! If <command>SET</> is allowed, it overrides all other sources of
! values for the parameter. Some parameters cannot be changed via
! <command>SET</command>: for example, if they control behavior that
! cannot be changed without restarting the entire
! <productname>PostgreSQL</productname> server. Also,
! some <command>SET</command> or <command>ALTER</> parameter modifications
! require superuser permission.
! </para>
! <para>
! The <xref linkend="SQL-SHOW">
! command allows inspection of the current values of all parameters.
! </para>
! <para>
! The virtual table <structname>pg_settings</structname> also allows
! displaying and updating session run-time parameters; see <xref
! linkend="view-pg-settings"> for details and a description of the
! different variable types and when they can be changed.
! <structname>pg_settings</structname> is equivalent to <command>SHOW</>
! and <command>SET</>, but can be more convenient
! to use because it can be joined with other tables, or selected from using
! any desired selection condition. It also contains more information about
! what values are allowed for the parameters.
! </para>
!
! </sect2>
</sect1>
<sect1 id="runtime-config-file-locations">
--
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
