DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;
	h=mime-version:in-reply-to:references:from:date:message-id:subject:to
	:cc:content-type:content-transfer-encoding;
	b=r1pw0kMdGLRmt7fn+WMhahl7Oan6kmozxBw1CpYcSBPsD8Lka9Q2kCvM79FqRFKCUS
	+AVHrs6We311hn/Xhbg0yA0CbPpA/TclbAr96YEkXwj5HrOHPAR+Bt5BQAN9dEF/AiVH
	xNFKQdMQy1fcJboA1qjiZ1LjR0qigLd6h1ZyI=
MIME-Version: 1.0
In-Reply-To: <20110427154840.GA22607@cns.vt.edu>
References: <20110427154840.GA22607@cns.vt.edu>
From: Josh Kupershmidt <schmiddy@gmail.com>
Date: Wed, 27 Apr 2011 18:42:33 -0400
Message-ID: <BANLkTi=kRA4zirWXmKfJZNXJXKi+BqebGQ@mail.gmail.com>
Subject: Re: configuration parameter descriptions
To: Ray Stell <stellr@cns.vt.edu>
Cc: pgsql-docs@postgresql.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Wed, Apr 27, 2011 at 11:48 AM, Ray Stell <stellr@cns.vt.edu> wrote:
> I'd like to make a general suggestion on configuration parameter
> documentation. =A0I'd like to see a high level entry as to whether the
> parameter can be changed on the fly or not. =A0I think the Oracle docs re=
fer
> to this as static/dynamic.

For a description of the "context" of various settings in Postgres, see:
http://developer.postgresql.org/pgdocs/postgres/view-pg-settings.html

> Currently, dynamic parameters, those that can be changed in a running
> cluster, can be identified by the fact that no statement is made. =A0This
> can be confusing.
>
> An example of the "static" entry follows:
>
> =A0listen_addresses (string)
>
> =A0 parmater description .........
> =A0 This parameter can only be set at server start.
>
> This might be communicated with something like:
>
> =A0listen_addresses (string) /static

We actually had a discussion recently about the best way to specify
the context of all the various settings, such as listen_addresses. I
think we had consensus that it'd be nice to have a standard way of
documenting this, but there were a few ways to do so, and no one
stepped up with a patch. That's where you might come in :-)

Reading through the thread again, I maybe like Alvaro's suggestion:
  http://archives.postgresql.org/pgsql-docs/2010-12/msg00017.php

of spelling out
|  "this setting has context foo"

in some standard way and place (e.g. as the last line of the
description for each setting) for all such settings.

> I'd be willing to work on this adaptation if you need help.
> I'd need some introduction to your text management.

Thanks for offering to help!