From: | Josh Kupershmidt <schmiddy(at)gmail(dot)com> |
---|---|
To: | Ray Stell <stellr(at)cns(dot)vt(dot)edu> |
Cc: | pgsql-docs(at)postgresql(dot)org |
Subject: | Re: configuration parameter descriptions |
Date: | 2011-04-27 22:42:33 |
Message-ID: | BANLkTi=kRA4zirWXmKfJZNXJXKi+BqebGQ@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs |
On Wed, Apr 27, 2011 at 11:48 AM, Ray Stell <stellr(at)cns(dot)vt(dot)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
From | Date | Subject | |
---|---|---|---|
Next Message | Fujii Masao | 2011-04-28 05:30:15 | document about pg_ctl kill |
Previous Message | Ray Stell | 2011-04-27 15:48:40 | configuration parameter descriptions |