public inbox for [email protected]
help / color / mirror / Atom feedVersion information in docs
7+ messages / 4 participants
[nested] [flat]
* Version information in docs
@ 2005-03-27 21:20 Jim C. Nasby <[email protected]>
0 siblings, 1 reply; 7+ messages in thread
From: Jim C. Nasby @ 2005-03-27 21:20 UTC (permalink / raw)
To: pgsql-docs
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.
--
Jim C. Nasby, Database Consultant [email protected]
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?"
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Version information in docs
@ 2005-03-28 01:54 Tom Lane <[email protected]>
parent: Jim C. Nasby <[email protected]>
0 siblings, 2 replies; 7+ messages in thread
From: Tom Lane @ 2005-03-28 01:54 UTC (permalink / raw)
To: Jim C. Nasby <[email protected]>; +Cc: pgsql-docs
"Jim C. Nasby" <[email protected]> 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.
regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Version information in docs
@ 2005-03-28 02:19 Jim C. Nasby <[email protected]>
parent: Tom Lane <[email protected]>
1 sibling, 0 replies; 7+ messages in thread
From: Jim C. Nasby @ 2005-03-28 02:19 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: pgsql-docs
On Sun, Mar 27, 2005 at 08:54:22PM -0500, Tom Lane wrote:
> "Jim C. Nasby" <[email protected]> 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 [email protected]
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?"
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Version information in docs
@ 2005-03-28 16:03 Thomas F.O'Connell <[email protected]>
parent: Tom Lane <[email protected]>
1 sibling, 1 reply; 7+ messages in thread
From: Thomas F.O'Connell @ 2005-03-28 16:03 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Jim C. Nasby <[email protected]>; pgsql-docs
For comparison, the MySQL docs seem to stay monolithic, at least
online. As in, they don't provide a different version of the manual for
3.23, 4.0, 4.1, 5.0, etc.
They have a single manual that seems to be pretty thorough about the
version in which various features came online.
I haven't concluded which style of documentation is more intuitive, but
when I've had to use MySQL, it has been nice to be able to go to one
document and look to see whether something has been implemented and
also when it was implemented. I suppose the same thing could be
achieved if the manual itself were versioned rather than individual
features being versioned, but you do have to look through various
versions of the manual if you're tracking features in PostgreSQL. If
you were dealing with multiple versions, it could become tedious. I've
dealt with many different versions of MySQL, and it is definitely handy
to have a history in single pages for features. Granted, the feature
set and SQL compatibility for MySQL have been much more volatile than
for PostgreSQL in the past few years, so maybe it's more striking and
necessary for them.
-tfo
--
Thomas F. O'Connell
Co-Founder, Information Architect
Sitening, LLC
Strategic Open Source — Open Your i™
http://www.sitening.com/
110 30th Avenue North, Suite 6
Nashville, TN 37203-6320
615-260-0005
On Mar 27, 2005, at 7:54 PM, Tom Lane wrote:
> "Jim C. Nasby" <[email protected]> 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.
>
> regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Version information in docs
@ 2005-03-28 20:54 Jim C. Nasby <[email protected]>
parent: Thomas F.O'Connell <[email protected]>
0 siblings, 1 reply; 7+ messages in thread
From: Jim C. Nasby @ 2005-03-28 20:54 UTC (permalink / raw)
To: Thomas F.O'Connell <[email protected]>; +Cc: Tom Lane <[email protected]>; pgsql-docs
Something else that comes to mind... going back to older versions of the
manual wouldn't be nearly as tedeous if there were links to older
versions somewhere on the pages. Maybe at every section header?
--
Jim C. Nasby, Database Consultant [email protected]
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?"
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Version information in docs
@ 2005-03-28 22:52 Bruce Momjian <[email protected]>
parent: Jim C. Nasby <[email protected]>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2005-03-28 22:52 UTC (permalink / raw)
To: Jim C. Nasby <[email protected]>; +Cc: Thomas F.O'Connell <[email protected]>; Tom Lane <[email protected]>; pgsql-docs
Jim C. Nasby wrote:
> Something else that comes to mind... going back to older versions of the
> manual wouldn't be nearly as tedeous if there were links to older
> versions somewhere on the pages. Maybe at every section header?
The good thing about our current setup is that all changes are
centralized in the release notes.
--
Bruce Momjian | http://candle.pha.pa.us
[email protected] | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Version information in docs
@ 2005-03-29 19:17 Jim C. Nasby <[email protected]>
parent: Bruce Momjian <[email protected]>
0 siblings, 0 replies; 7+ messages in thread
From: Jim C. Nasby @ 2005-03-29 19:17 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: Thomas F.O'Connell <[email protected]>; Tom Lane <[email protected]>; pgsql-docs
On Mon, Mar 28, 2005 at 05:52:30PM -0500, Bruce Momjian wrote:
> Jim C. Nasby wrote:
> > Something else that comes to mind... going back to older versions of the
> > manual wouldn't be nearly as tedeous if there were links to older
> > versions somewhere on the pages. Maybe at every section header?
>
> The good thing about our current setup is that all changes are
> centralized in the release notes.
I don't see how my suggestion would necessarily change that. But if
you're trying to figure out when a feature was introduced sifting
through a bunch of release notes seems as bad as sifting through old
versions of the manuals. Or maybe even worse; at least with the manuals
you know what section to look in.
--
Jim C. Nasby, Database Consultant [email protected]
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?"
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2005-03-29 19:17 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2005-03-27 21:20 Version information in docs Jim C. Nasby <[email protected]>
2005-03-28 01:54 ` Tom Lane <[email protected]>
2005-03-28 02:19 ` Jim C. Nasby <[email protected]>
2005-03-28 16:03 ` Thomas F.O'Connell <[email protected]>
2005-03-28 20:54 ` Jim C. Nasby <[email protected]>
2005-03-28 22:52 ` Bruce Momjian <[email protected]>
2005-03-29 19:17 ` Jim C. Nasby <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox