Thread: configuration parameter descriptions

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

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.  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.

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.  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

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!

From a git checkout [1], you'll want to modify primarily
./doc/src/sgml/config.sgml. If you're familiar with HTML, the SGML
syntax should be easy enough to pick up. See the doc building guide
[2] for how to build the resulting HTML pages locally and see the
results of your changes.

[1] http://wiki.postgresql.org/wiki/Working_with_Git
[2] http://www.postgresql.org/docs/current/static/docguide-build.html