Skip site navigation (1) Skip section navigation (2)

Confusing section of 'Setting Parameters'

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 (view raw or flat)
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: setting_parameters_subsections.diff
Description: text/x-patch (16.7 KB)
Attachment: include_if_exists.diff
Description: text/x-patch (1.1 KB)

Responses

pgsql-docs by date

Next:From: Josh KupershmidtDate: 2012-05-08 01:29:34
Subject: Re: misspellings & typofixes
Previous:From: Josh KupershmidtDate: 2012-05-05 00:37:09
Subject: Capitalization of 'TimeZone' GUC

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group