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
