Обсуждение: Ready for admin guide and INSTALL

OK, I'm about ready to freeze the admin guide and installation info. I'd
like to put the TODO list into the release notes, along with a few
paragraphs highlighting feature improvements/changes which might affect
users.

Do you want to write something, or should I go ahead? Also, I'd like to
clean up/consolidate some of the entries in the TODO list; should I do
that and commit it or do it and just send it directly to you?
                   - Tom

"Thomas G. Lockhart" <lockhart@alumni.caltech.edu> writes:
> OK, I'm about ready to freeze the admin guide and installation info.

Can the peanut gallery get a look first?
        regards, tom lane

> OK, I'm about ready to freeze the admin guide and installation info. I'd
> like to put the TODO list into the release notes, along with a few
> paragraphs highlighting feature improvements/changes which might affect
> users.
> 
> Do you want to write something, or should I go ahead? Also, I'd like to
> clean up/consolidate some of the entries in the TODO list; should I do
> that and commit it or do it and just send it directly to you?

I have updated the TODO list, and it will probably not change before 6.4
is released.  You can use the copy in the distribution, or on the web
page.  The web page copy has HTML markups.

If you want to clean up the TODO list, please do.  E-mail me an ASCII
copy back, and I will update it here.  If you want the markups of your
changes in html, change the ASCII, and I will run it through to get
html.

As far as a highlights, I can't think of some good words for it, so
please go ahead and write something.  In previous releases, certain
items clearly came to me, but not with 6.4.

--  Bruce Momjian                        |  http://www.op.net/~candle maillist@candle.pha.pa.us            |  (610)
853-3000+  If your life is a hard drive,     |  830 Blythe Avenue +  Christ can be your backup.        |  Drexel Hill,
Pennsylvania19026
 

> > OK, I'm about ready to freeze the admin guide and installation info.
> Can the peanut gallery get a look first?

I've posted almost-final installation instructions in html format on the
web site at
 ftp://postgresql.org/pub/patches/installation.tar.gz

These will replace INSTALL *as plain text* for v6.4. The Admin Guide
will also have this info in both html and Postscript formats.

If you have comments let me know; I will need to freeze this stuff this
evening.
                - Tom

"Thomas G. Lockhart" <lockhart@alumni.caltech.edu> writes:
> I've posted almost-final installation instructions in html format on the
> web site at
>   ftp://postgresql.org/pub/patches/installation.tar.gz

It's looking pretty good.  I have a few more suggestions...


Major suggestion: chapter 3 (detailed discussion of configure options)
probably ought to be placed after the step-by-step install, not before.
A person who doesn't already know what configure is would be pretty lost
upon hitting the first page of chapter 3, I think.

Minor stuff:

Install step 9 says:
 Note: There are two places in this installation procedure where you will have an opportunity to specify installation
locationsfor programs, libraries, documentation, and other files. Usually it is sufficient to specify these at the make
installstage of installation.
 

Make install??  I think it is much safer to tell people to select these
locations during configure.  I would not want to bet that you can change
the install target just by tweaking make parameters at the install step.
On HPUX, for example, that will definitely fail, because the path to the
shared libraries in /usr/local/pgsql/lib (eg) is embedded into the
binaries for psql and friends at build time, not install time.


In the lengthier discussion of configure options, I recommend not listing --datadir=DIR           read-only
architecture-independentdata in DIR                         [PREFIX/share] --sysconfdir=DIR        read-only
single-machinedata in DIR [PREFIX/etc] --sharedstatedir=DIR    modifiable architecture-independent data in DIR
              [PREFIX/com] --srcdir=DIR            find the sources in DIR [configure dir or ..] --with-x
use the X Window System
 
These are generic configure options that are not actually used by our
setup, so they're hardly worth listing.  Also, I suggest adding --without-CXX           do not try to build C++ code
(which is mentioned inline in the install procedure, but it's missing
in the allegedly more complete discussion of options...)


And in the trivia category: ports list refers to HPUX "9.0.x", but it
should say "9.0x".
        regards, tom lane

Argh!  Forgot the most important point --- the install procedure is
still missing anything about installing the Perl module.  Recommend
adding the following, or something much like it, just after the
primary install step (between items 15 and 16, currently):


<Step Performance="optional">
<Para>
If you used the <option>--with-perl</option> option to configure, check
the install log to see whether the Perl module was actually installed.
If you've followed our advice to make the Postgres files be owned by
an unprivileged userid, then the Perl module won't have been installed,
for lack of write privileges on the Perl library directories.  You can
complete its installation, either now or later, by su'ing to the user that
does own the Perl library (often root) and doing
<ProgramListing>
$ cd /usr/src/pgsql/src/interfaces/perl5
$ gmake install
</ProgramListing>
</Para>
</Step>

        regards, tom lane

> It's looking pretty good.  I have a few more suggestions...

OK, but save some for v6.5. As you can see there are some parts of these
docs which are just hanging together with baling wire and gum, and could
really use a cleanup/update/normalization.

> Major suggestion: chapter 3 (detailed discussion of configure options)
> probably ought to be placed after the step-by-step install, not 
> before.

Yeah. I'll put a mention in beforehand and in the procedure and move the
text to afterwards. I already said something about "plain vanilla"
installations not needing many/any options.

> Install step 9 says:
>   Note: There are two places in this installation procedure where...

> Make install??  I think it is much safer to tell people to select 
> these locations during configure.

In testing the standalone ODBC stuff, I found that some parameters had
to be specified during the make stage for some reason. The stuff was
stolen from the main configure, so shares a lot of traits.

I can't write a definitive installation doc given that I should have
frozen all of this several days ago. So I'm inclined to mention both,
and we can hash it out _early_ in the v6.5 cycle. The good news is that
the installation stuff is more accurate than it used to be. The bad news
is that it pretty clearly isn't perfect. Thank god for mailing lists,
eh?

> In the lengthier discussion of configure options, I recommend not 
> listing...

OK.

> And in the trivia category: ports list refers to HPUX "9.0.x", but it
> should say "9.0x".

Fixed. And frozen. I'm going to take Bruce's ToDo/release list, put it
into a new file current.sgml, add a few paragraphs of notes, and be done
with it.
                    - Tom^H^H^HThomas