Thread: bitten by docs

bitten by docs

From
Alfred Perlstein
Date:
Hey I just got bitten by something in the docs: http://www.postgresql.org/docs/user/datatype1029.htm

specifically:
 Note: To ensure compatibility to earlier versions of PostgreSQL we also continue to provide datetime (equivalent to
timestamp)and timespan (equivalent to interval). The types abstime and reltime are lower precision types which are used
internally.You are discouraged from using any of these types in new applications and move any old ones over when
appropriate.Any or all of these type might disappear in a future release.
 

after reading this I quickly converted all my datetime into timestamp
then I got bitten because a lot of my scripts were using date functions
that don't seem to support timestamp as an argument, specifically
date_part().

Now if date_part() doesn't take timestamps in 7.0 that needs to be
addressed, however it seems that this change took place some time
after the 6.5 release.

I also realized that my changes to the docs in re async libpq functions
probably are confusing the hell out of people using the 'stable' 6.5.

Getting to the point, wouldn't it be easier on the users if either:

a) at release time the www docs are frozen but a link is made to the  HEAD branch of the docs so people can see what's
goingon in   current development.
 
b) maintain a -stable (off the 6.5 branch) of the docs that gets   fixes put into it relative to the release while
stillhaving a link  to the most current docs.  I know the inconvience of maintaining  a branch is annoying but this is
thebest way imo.
 

I think providing for this when 7.0 comes out would really assist
users, as the next release rolls around it's going to be just too
easy to get confused.

thanks,
-- 
-Alfred Perlstein - [bright@wintelcom.net|alfred@freebsd.org]


Re: [HACKERS] bitten by docs

From
Tom Lane
Date:
Alfred Perlstein <bright@wintelcom.net> writes:
> Getting to the point, wouldn't it be easier on the users if either:

> a) at release time the www docs are frozen but a link is made to the
>    HEAD branch of the docs so people can see what's going on in 
>    current development.
> b) maintain a -stable (off the 6.5 branch) of the docs that gets 
>    fixes put into it relative to the release while still having a link
>    to the most current docs.  I know the inconvience of maintaining
>    a branch is annoying but this is the best way imo.

This was discussed a while ago.  I thought we had agreed that we needed
to keep two sets of docs on the website, one for the last stable release
(ie, 6.5 currently) and one for the current development tip.  But I
guess nothing's been done about it yet...
        regards, tom lane


Re: [HACKERS] bitten by docs

From
Thomas Lockhart
Date:
>   Note: To ensure compatibility to earlier versions of PostgreSQL
>   we also continue to provide datetime (equivalent to timestamp)
>   and timespan (equivalent to interval).
>   The types abstime and reltime are lower precision types which
>   are used internally. You are discouraged from using any of these
>   types in new applications and move any old ones over when
>   appropriate. Any or all of these type might disappear in a future
>   release.

I'll probably rephrase this to emphasize that datetime et al are now
deprecated and will eventually disappear.
                 - Thomas

-- 
Thomas Lockhart                lockhart@alumni.caltech.edu
South Pasadena, California


Re: [HACKERS] bitten by docs

From
Thomas Lockhart
Date:
> This was discussed a while ago.  I thought we had agreed that we needed
> to keep two sets of docs on the website, one for the last stable release
> (ie, 6.5 currently) and one for the current development tip.  But I
> guess nothing's been done about it yet...

Perhaps we agreed what should be done, but I'm not sure anyone agreed
to actually do it.

Vince, could you take ownership of this issue (at least to get it on a
ToDo list so we don't forget)? I'm happy to help (will probably need
to redirect the nightly html production to another area of the web
site) but I'm reluctant to muck around with the overall structure of
the site, at least without some adult supervision...
                - Thomas

-- 
Thomas Lockhart                lockhart@alumni.caltech.edu
South Pasadena, California


Re: [HACKERS] bitten by docs

From
Vince Vielhaber
Date:
On Thu, 2 Mar 2000, Thomas Lockhart wrote:

> > This was discussed a while ago.  I thought we had agreed that we needed
> > to keep two sets of docs on the website, one for the last stable release
> > (ie, 6.5 currently) and one for the current development tip.  But I
> > guess nothing's been done about it yet...
> 
> Perhaps we agreed what should be done, but I'm not sure anyone agreed
> to actually do it.
> 
> Vince, could you take ownership of this issue (at least to get it on a
> ToDo list so we don't forget)? I'm happy to help (will probably need
> to redirect the nightly html production to another area of the web
> site) but I'm reluctant to muck around with the overall structure of
> the site, at least without some adult supervision...

Actually I had planned on doing it with the 7.0 release.  I have a number
of website changes to do and things like two sets of docs are considered
a major change - or at least I consider it one.  If you can redirect any
release docs to the release-doc directory I just created on the website
that'd help - otherwise it'll hafta wait till 7.0 goes to release.

Vince.
-- 
==========================================================================
Vince Vielhaber -- KA8CSH    email: vev@michvhf.com    http://www.pop4.net  128K ISDN: $24.95/mo or less - 56K Dialup:
$17.95/moor less at Pop4       Online Campground Directory    http://www.camping-usa.com      Online Giftshop
Superstore   http://www.cloudninegifts.com
 
==========================================================================





Re: [HACKERS] bitten by docs

From
Alfred Perlstein
Date:
* Vince Vielhaber <vev@michvhf.com> [000302 03:45] wrote:
> On Thu, 2 Mar 2000, Thomas Lockhart wrote:
> 
> > > This was discussed a while ago.  I thought we had agreed that we needed
> > > to keep two sets of docs on the website, one for the last stable release
> > > (ie, 6.5 currently) and one for the current development tip.  But I
> > > guess nothing's been done about it yet...
> > 
> > Perhaps we agreed what should be done, but I'm not sure anyone agreed
> > to actually do it.
> > 
> > Vince, could you take ownership of this issue (at least to get it on a
> > ToDo list so we don't forget)? I'm happy to help (will probably need
> > to redirect the nightly html production to another area of the web
> > site) but I'm reluctant to muck around with the overall structure of
> > the site, at least without some adult supervision...
> 
> Actually I had planned on doing it with the 7.0 release.  I have a number
> of website changes to do and things like two sets of docs are considered
> a major change - or at least I consider it one.  If you can redirect any
> release docs to the release-doc directory I just created on the website
> that'd help - otherwise it'll hafta wait till 7.0 goes to release.

Having it happen at the 7.0 release would be optimal and most appreciated.

thanks,
-Alfred


Re: [HACKERS] bitten by docs

From
Bruce Momjian
Date:
]> > This was discussed a while ago.  I thought we had agreed that we needed
> > to keep two sets of docs on the website, one for the last stable release
> > (ie, 6.5 currently) and one for the current development tip.  But I
> > guess nothing's been done about it yet...
> 
> Perhaps we agreed what should be done, but I'm not sure anyone agreed
> to actually do it.
> 
> Vince, could you take ownership of this issue (at least to get it on a
> ToDo list so we don't forget)? I'm happy to help (will probably need
> to redirect the nightly html production to another area of the web
> site) but I'm reluctant to muck around with the overall structure of
> the site, at least without some adult supervision...

I can update the HTML now.  No problem.

--  Bruce Momjian                        |  http://www.op.net/~candle pgman@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