Subject: configuration parameter descriptions

From: Ray Stell <[email-masked]>
Date: Wed, 27 Apr 2011 11:48:40 -0400

I'd like to make a general suggestion on configuration parameter
documentation.  I'd like to see a high level entry as to whether the
parameter can be changed on the fly or not.  I think the Oracle docs refer
to this as static/dynamic.  

Currently, dynamic parameters, those that can be changed in a running
cluster, can be identified by the fact that no statement is made.  This
can be confusing.  

An example of the "static" entry follows:

 listen_addresses (string)

   parmater description .........
   This parameter can only be set at server start.

This might be communicated with something like:

  listen_addresses (string) /static

The current entry for maintenance_work_mem looks like this:

 maintenance_work_mem (integer)

     Specifies the maximum amount of memory...

which might look something like this:

 maintenance_work_mem (integer)  /dynamic

     Specifies the maximum amount of memory

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

Thanks,
Ray

---

From: Josh Kupershmidt <[email-masked]>
Date: Wed, 27 Apr 2011 18:42:33 -0400

> 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

>  listen_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 need some introduction to your text management.

Thanks for offering to help!