From: | Josh Kupershmidt <schmiddy(at)gmail(dot)com> |
---|---|
To: | pgsql-docs <pgsql-docs(at)postgresql(dot)org> |
Subject: | Confusing section of 'Setting Parameters' |
Date: | 2012-05-08 00:29:35 |
Message-ID: | CAK3UJRHyjfQmrEa4sONcmfi=Ah0-2Ncg-eVMoRnu6OYJzQ31OQ@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs |
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
Attachment | Content-Type | Size |
---|---|---|
include_if_exists.diff | text/x-patch | 1.1 KB |
setting_parameters_subsections.diff | text/x-patch | 16.7 KB |
From | Date | Subject | |
---|---|---|---|
Next Message | Josh Kupershmidt | 2012-05-08 01:29:34 | Re: misspellings & typofixes |
Previous Message | Josh Kupershmidt | 2012-05-05 00:37:09 | Capitalization of 'TimeZone' GUC |