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
include_if_exists
in configuration file
! 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
--- 94,101
include_if_exists
in configuration file
! The include_if_exists directive uses 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
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
Setting Parameters
!
! 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 on,
! off, true,
! false, yes,
! no, 1, 0
! (all case-insensitive) or any unambiguous prefix of these.
!
!
! 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 pg_settings.unit.
! For convenience,
! a different unit can also be specified explicitly. Valid memory units
! are kB (kilobytes), MB
! (megabytes), and GB (gigabytes); valid time units
! are ms (milliseconds), s
! (seconds), min (minutes), h
! (hours), and d (days). Note that the multiplier
! for memory units is 1024, not 1000.
!
!
! Parameters of type 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 pg_settings.enumvals.
! Enum parameter values are case-insensitive.
!
!
! One way to set these parameters is to edit the file
! postgresql.confpostgresql.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:
# This is a comment
log_connections = yes
--- 18,65
Setting Parameters
!
! Parameter Names and Values
!
! 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 on,
! off, true,
! false, yes,
! no, 1, 0
! (all case-insensitive) or any unambiguous prefix of these.
!
!
! 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 pg_settings.unit.
! For convenience,
! a different unit can also be specified explicitl
