Re: Improving postgresql.conf

I understand your points below. However, the group has weighed in the
direction of clearly showing non-default values and not duplicating
documentation. We can change that, but you will need more folks
agreeing with your direction.

---------------------------------------------------------------------------

Greg Sabino Mullane wrote:
[ There is text before PGP section. ]
>
[ PGP not available, raw data follows ]
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
> > We discussed this and thought that it would end up duplicating stuff
> > already in the docs
>
> Which is fine. Keeping some documentation in the file itself is a
> necessity. For example, we've changed "sort_mem" to "work_mem".
> There should at the least be a note to this effect in the postgresql.conf
> file. Better yet, there should be a brief explanation of what each of
> the parameters _means_ and what each one _does_. It does not have to go
> into detail, but there should be enough language to remind somebody what
> exactly the sometimes cryptically named parameter does. The name alone
> is not enough. When in doubt, it is always better to err on the side
> of more verbose documentation.
>
> > and removing the comments means that you have no way to know which are
> > being set to non-default values.
>
> This seems a non-issue to me. The end-user does not really care so much
> about what is "default" so much as what it is right now. We are overloading
> the "#" operator, so to speak, by making it not only a documentation
> markup, but by making it a "set default because it is commented out." What
> happens when somebody changes the sort_mem to something, and then comments
> it out to "turn it back to the default"? The next person looking at the file
> is not going to know what the setting is, because instead of the default being
> in the documentation part of the file, it is in the commented-out parameter,
> and it is now wrong. Far better to explicitly set every parameter. You can
> then go into the file and know exactly what each parameter is set to.
>
> > Are people saying the Apache config files are easier to use? I actually
> > find it quite hard to understand, especially httpd.conf.
>
> It is certainly well documented. You can step into it for the first time
> and have a relatively complete understanding of what each setting does.
> It's also laid out logically, but we have mostly addressed this in the
> last big rearrangement of postgresql.conf that happened a few months ago.
>
> > One idea that has been floated around is to pull the docs automatically
> > from SGML and put them in postgresql.conf. We do that for psql's use of
> > \help now, so it seems this is possible.
>
> I'm not sure this is the way to go. The SGML should be more detailed, and
> also assumes that you are reading it in a different context than from within
> the configuration file.
>
> - --
> Greg Sabino Mullane greg(at)turnstep(dot)com
> PGP Key: 0x14964AC8 200406100751
>
> -----BEGIN PGP SIGNATURE-----
>
> iD8DBQFAyE0rvJuQZxSWSsgRAqL3AJ0eR28O8LyWV3Kn5wgMtggqJi8/nACeI/JC
> onWV778+vewEdBeAI+EYOkw=
> =/wqn
> -----END PGP SIGNATURE-----
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 1: subscribe and unsubscribe commands go to majordomo(at)postgresql(dot)org
>
[ Decrypting message... End of raw data. ]

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073