Re: Improving postgresql.conf - Mailing list pgsql-hackers

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@turnstep.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@postgresql.org
> 
[ Decrypting message... End of raw data. ]

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