Date: Sun, 27 Mar 2005 20:19:46 -0600
From: "Jim C. Nasby" <decibel@decibel.org>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-docs@postgresql.org
Subject: Re: Version information in docs
Message-ID: <20050328021946.GT51784@decibel.org>
References: <20050327212050.GP51784@decibel.org>
	<4301.1111974862@sss.pgh.pa.us>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <4301.1111974862@sss.pgh.pa.us>
User-Agent: Mutt/1.5.6i

On Sun, Mar 27, 2005 at 08:54:22PM -0500, Tom Lane wrote:
> "Jim C. Nasby" <decibel@decibel.org> writes:
> > ISTM it would be very useful if the docs specified what version a
> > feature that would break in older versions was implemented in. The
> > example that comes to mind is argument names in CREATE FUNCTION, which
> > was added in 8.0. The 8.0 docs (http://lnk.nu/postgresql.org/1y3.html)
> > mention the ability to name arguments, but it doesn't mention that the
> > feature was added in 8.0 and can not be used in prior versions. Anyone
> > who's trying to write code that will run on multiple versions of
> > PostgreSQL would want to know this.
> 
> The release notes cover that; or you can compare the docs for the oldest
> and newest versions you want to work with.  I think it would be more
> confusing than helpful for the reference pages to try to cover all the
> changes from version to version.

Well, it might not need to cover all changes, just ones that might be
easy to overlook. Besides, are there really that many syntax changes
from one version to another?

Another idea I had is that if there was actual metadata in the document
source about the version info, it would be possible to output different
amounts or kinds of information depending on how old the change was. For
example, I doubt anyone would possibly care about changes prior to 7.0
at this point, and most people probably wouldn't care about changes
prior to 7.3 or even 7.4, so the default documentation wouldn't need to
show that info. Another alternative is providing a history link on
features that takes you to appropriate documentation about what changes
have occured and when. In this case, it would just mention that argument
names first appeared in 8.0.
-- 
Jim C. Nasby, Database Consultant               decibel@decibel.org 
Give your computer some brain candy! www.distributed.net Team #1828

Windows: "Where do you want to go today?"
Linux: "Where do you want to go tomorrow?"
FreeBSD: "Are you guys coming, or what?"