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 [EMAIL PROTECTED] > 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 [EMAIL PROTECTED] > [ Decrypting message... End of raw data. ] -- Bruce Momjian | http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania 19073 ---------------------------(end of broadcast)--------------------------- TIP 6: Have you searched our list archives? http://archives.postgresql.org
