Documentation: references to old versions

While reading some documentation, I noticed that we have references to
past releases. For example,
http://www.postgresql.org/docs/9.2/static/xfunc-c.html mentions "A
magic block is required as of PostgreSQL 8.2". Sure, this is true even
as of 9.2 or even 9.3. There are a few more such references that I
could spot with a simple grep in the doc/src/sgml directory. I wonder
if this is worth fixing. I don't know sgml enough, but if it supports
some sort of a meta-tag, then it might help to replace specific
version references with something like <CURRENT_MAJOR_RELEASE> so that
the current major version gets substituted when docs for that release
are built.

Thanks,
Pavan

--
Pavan Deolasee
http://www.linkedin.com/in/pavandeolasee

Hi

On Tue, Feb 12, 2013 at 9:14 AM, Pavan Deolasee <pavan(dot)deolasee(at)gmail(dot)com>wrote:

> While reading some documentation, I noticed that we have references to
> past releases. For example,
> http://www.postgresql.org/docs/9.2/static/xfunc-c.html mentions "A
> magic block is required as of PostgreSQL 8.2". Sure, this is true even
> as of 9.2 or even 9.3. There are a few more such references that I
> could spot with a simple grep in the doc/src/sgml directory. I wonder
> if this is worth fixing. I don't know sgml enough, but if it supports
> some sort of a meta-tag, then it might help to replace specific
> version references with something like <CURRENT_MAJOR_RELEASE> so that
> the current major version gets substituted when docs for that release
> are built.
>

The phrasing "as of 8.2" basically means "from 8.2 onwards". Changing the
version there would make the text incorrect.

--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Tue, Feb 12, 2013 at 2:49 PM, Dave Page <dpage(at)pgadmin(dot)org> wrote:
>
>
> The phrasing "as of 8.2" basically means "from 8.2 onwards". Changing the
> version there would make the text incorrect.
>

Ah Ok. Thanks for clarifying. My bad English.

Thanks,
Pavan

--
Pavan Deolasee
http://www.linkedin.com/in/pavandeolasee

Pavan Deolasee wrote:
> While reading some documentation, I noticed that we have references to
> past releases. For example,
> http://www.postgresql.org/docs/9.2/static/xfunc-c.html mentions "A
> magic block is required as of PostgreSQL 8.2". Sure, this is true even
> as of 9.2 or even 9.3. There are a few more such references that I
> could spot with a simple grep in the doc/src/sgml directory. I wonder
> if this is worth fixing. I don't know sgml enough, but if it supports
> some sort of a meta-tag, then it might help to replace specific
> version references with something like <CURRENT_MAJOR_RELEASE> so that
> the current major version gets substituted when docs for that release
> are built.

I believe that this should remain "8.2".
It tells the reader that the magic block is required for
PostgreSQL since version 8.2, which is saying more than that
it is required in the current release.

Maybe the wording could be changed:
Since PostgreSQL 8.2, a magic block is required.

On the other hand, since 8.2 is desupported, the whole
"as of PostgreSQL 8.2" could be discarded.

I am not sure if <CURRENT_MAJOR_RELEASE> would be very useful.
I think that the documentation should only mention a version number
if the information stays valid.
Otherwise, one should use "the current version" to emphasize that
the statement is not tied to a certain version number.

Yours,
Laurenz Albe

On Tue, Feb 12, 2013 at 10:19 AM, Dave Page <dpage(at)pgadmin(dot)org> wrote:
>
> Hi
>
> On Tue, Feb 12, 2013 at 9:14 AM, Pavan Deolasee <pavan(dot)deolasee(at)gmail(dot)com>
> wrote:
>>
>> While reading some documentation, I noticed that we have references to
>> past releases. For example,
>> http://www.postgresql.org/docs/9.2/static/xfunc-c.html mentions "A
>> magic block is required as of PostgreSQL 8.2". Sure, this is true even
>> as of 9.2 or even 9.3. There are a few more such references that I
>> could spot with a simple grep in the doc/src/sgml directory. I wonder
>> if this is worth fixing. I don't know sgml enough, but if it supports
>> some sort of a meta-tag, then it might help to replace specific
>> version references with something like <CURRENT_MAJOR_RELEASE> so that
>> the current major version gets substituted when docs for that release
>> are built.
>
>
> The phrasing "as of 8.2" basically means "from 8.2 onwards". Changing the
> version there would make the text incorrect.

In theory we could remove that reference completely since any versions
where it does not apply are out of support since years ago at this
point. But I don't see a point in doing that just for the sake of
removing - but if a section is reworded in general that contains such
references, it could be dropped.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Magnus Hagander <magnus(at)hagander(dot)net> writes:
> On Tue, Feb 12, 2013 at 10:19 AM, Dave Page <dpage(at)pgadmin(dot)org> wrote:
>> The phrasing "as of 8.2" basically means "from 8.2 onwards". Changing the
>> version there would make the text incorrect.

> In theory we could remove that reference completely since any versions
> where it does not apply are out of support since years ago at this
> point. But I don't see a point in doing that just for the sake of
> removing - but if a section is reworded in general that contains such
> references, it could be dropped.

The fact that pre-8.2 is out of support doesn't make this useless
information: many such installations are still out there in the wild,
and people may want to know what techniques will work with them.
I'd be inclined to leave the text as-is until it's been awhile since
we've heard of anyone using pre-8.2.

regards, tom lane

On Tue, Feb 12, 2013 at 4:22 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Magnus Hagander <magnus(at)hagander(dot)net> writes:
>> On Tue, Feb 12, 2013 at 10:19 AM, Dave Page <dpage(at)pgadmin(dot)org> wrote:
>>> The phrasing "as of 8.2" basically means "from 8.2 onwards". Changing the
>>> version there would make the text incorrect.
>
>> In theory we could remove that reference completely since any versions
>> where it does not apply are out of support since years ago at this
>> point. But I don't see a point in doing that just for the sake of
>> removing - but if a section is reworded in general that contains such
>> references, it could be dropped.
>
> The fact that pre-8.2 is out of support doesn't make this useless
> information: many such installations are still out there in the wild,
> and people may want to know what techniques will work with them.
> I'd be inclined to leave the text as-is until it's been awhile since
> we've heard of anyone using pre-8.2.

If you are using an earlier version, you should really be reading the
documentation that corresponds to the version that you are using.

That said, this general reason is why I say we shouldn't go remove it
intentionally. I'm just saying it's acceptable "collateral damage" if
it gets removed along with another patch, and that we shouldn't put
special efforts into maintaining it.

I'd rather see that special effort go into encouraging people to read
the version of the documentation that matches their version of
PostgreSQL...

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/