pgsql: Doc: improve documentation of configuration settings that have u

From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: pgsql-committers(at)lists(dot)postgresql(dot)org
Subject: pgsql: Doc: improve documentation of configuration settings that have u
Date: 2019-10-26 16:31:03
Message-ID: E1iOOxz-0007Gw-Q9@gemulon.postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-committers

Doc: improve documentation of configuration settings that have units.

When we added the GUC units feature, we didn't make any great effort
to adjust the documentation of individual GUCs; they tended to still
say things like "this is the number of milliseconds that ...", even
though users might prefer to write some other units, and SHOW might
even show the value in other units. Commit 6c9fb69f2 made an effort
to improve this situation, but I thought it made things less readable
by injecting units information in mid-sentence. It also wasn't very
consistent, and did not touch all the GUCs that have units.

To improve matters, standardize on the phrasing "If this value is
specified without units, it is taken as <units>". Also, try to
standardize where this is mentioned, right before the specification
of the default. (In a couple of places, doing that would've required
more rewriting than seemed justified, so I wasn't 100% consistent
about that.) I also tried to use the phrases "amount of time",
"amount of memory", etc rather than describing the contents of GUCs
in other ways, as those were the majority usage in places that weren't
overcommitting to a particular unit. (I left "length of time" alone
in a couple of places, though.)

I failed to resist the temptation to copy-edit some awkward text, too.

Backpatch to v12, like 6c9fb69f2, mainly because v12 hasn't diverged
much from HEAD yet.

Discussion: https://postgr.es/m/15882.1571942223@sss.pgh.pa.us

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/cfb7559083436b802e7ecc5e3fa235057890265c

Modified Files
--------------
doc/src/sgml/config.sgml | 383 +++++++++++++++++++++++++++++------------------
1 file changed, 237 insertions(+), 146 deletions(-)

Browse pgsql-committers by date

  From Date Subject
Next Message Noah Misch 2019-10-26 19:57:14 pgsql: Update comment about __sync_lock_test_and_set() bug.
Previous Message Michael Paquier 2019-10-26 02:29:03 Re: pgsql: Make the order of the header file includes consistent in non-bac