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