Re: Documentation of configuration settings

Thomas Lockhart writes:

> > Comments?
>
> All good. Go fer it dude!

Well, I felt a little ambitious and am now rewriting half the
administrator's guide. In particular I extended the chapter "Runtime
environment" to contain treatment of initdb, added a section on the
configuration options, starting up the server (command line, boot time),
also one on shutting down the server (smart/fast, etc.). The sections on
client authentication and on users and groups have also lost touch with
reality a little.

All the while it occurred to me that the administrator's guide is really
isomorphic to the installation instructions (or what the installation
instructions should be): building, installing, backup and restore,
creating database cluster, starting server, automatic server startup,
creating databases, connecting to databases, managing users, regression
tests. Of course we can't dump half the administrator's guide into the
INSTALL file. If we, as we do now, cut out a chapter of the book and put
it in the INSTALL file then we're going to continue to have two problems:

1) Those wanting to improve the INSTALL file have to be careful not to be
too terse or create duplicate documentation because it's used on the other
end as a narative chapter in the administrator's guide.

2) Those wanting to add more insights and details to the administrator's
guide have to be careful not to be too verbose and not create any outside
references because this chapter is used as the INSTALL file.

In short, the literary quality is going to suffer on both ends. Thus I
though it might be worth considering maintaining the INSTALL file as a
separate document (in DocBook, of course). It would in some sense be an
abbreviated version of the administrator's guide. Then those users that
are new to Postgres are not overwhelmed with information, and those that
already have an installation can read the administrator's guide on how to
fine-tune their setup.

What do you think?

> (and kill those ENABLE_xxx keywords while you're at it ;)

If I replace `ENABLE_xxx' with `xxx' then we have one option named `SORT',
which seems overly general. I think the best naming scheme would be
`SEQSCAN_PLANS', `SORT_PLANS', but that's a pretty deep cut that we'd have
to think about.

--
Peter Eisentraut Sernanders väg 10:115
peter_e(at)gmx(dot)net 75262 Uppsala
http://yi.org/peter-e/ Sweden