Thread: Documentation of configuration settings

Now that we have the Grand Unified Configuration system we still need to
get rid of the Greatly Sprinkled Documentation thereof. Therefore my plan
for your approval:

* Make SET TRANSACTION and SET CONSTRAINTS each separate reference pages,
as their behaviour is really quite different.

* Make a comprehensive list of everything you can set and how somewhere in
the administrator guide.

* Remove the (then redundant) list of parameters from the SET reference
page and replace it with something to the effect of "This command lets you
set run-time parameters, a complete list of which can be found
<somewhere>."

Comments?

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

> Comments?

All good. Go fer it dude!

                  - Thomas

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

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@gmx.net                   75262 Uppsala
http://yi.org/peter-e/            Sweden

> > All good. Go fer it dude!
> Well, I felt a little ambitious and am now rewriting half the
> administrator's guide.
...
> What do you think?

Great! Your points on the differences between installation and
administration are spot-on, and I agree that decoupling the two makes
sense.

                 - Thomas