Thread: 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