Skip site navigation (1) Skip section navigation (2)

Re: Documentation of configuration settings

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: Thomas Lockhart <lockhart(at)alumni(dot)caltech(dot)edu>
Cc: pgsql-docs(at)postgresql(dot)org
Subject: Re: Documentation of configuration settings
Date: 2000-06-03 22:44:26
Message-ID: Pine.LNX.4.21.0006040022220.348-100000@localhost.localdomain (view raw or flat)
Thread:
Lists: pgsql-docs
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


In response to

Responses

pgsql-docs by date

Next:From: Peter EisentrautDate: 2000-06-04 01:46:53
Subject: Re: child table doesn't inherit PRIMARY KEY?
Previous:From: Louis-David MitterrandDate: 2000-06-03 15:51:56
Subject: Re: child table doesn't inherit PRIMARY KEY?

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group