Обсуждение: Confusing section of 'Setting Parameters'
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
Вложения
Josh Kupershmidt <schmiddy@gmail.com> writes: > This bit of "Section 18.1. Setting Parameters"[1] is highly confusing: Yeah, that's badly in need of editing. > 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. I think this is a good idea, but I didn't like your section division at all. I broke it up like this instead: Parameter Names and Values Setting Parameters via the Configuration File Other Ways to Set Parameters Examining Parameter Settings See what you think. > 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). Yeah, the discussion on the pg_settings page maybe should be moved here. On the other hand, this is very introductory material, so it might not be the best place for anything too detailed. regards, tom lane
On Thu, May 10, 2012 at 8:05 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > I think this is a good idea, but I didn't like your section division > at all. I broke it up like this instead: > > Parameter Names and Values > Setting Parameters via the Configuration File > Other Ways to Set Parameters > Examining Parameter Settings > > See what you think. Looks much better now, thanks. Josh