Re: Links for upgraders

The attached patch aims to help upgraders find the relevant information
important to their upgrade.

I would have liked to link the version number instead of adding more
text, but I didn't find a way to do that.

This patch was generated with the following command:

doc$ find . -type f -print0 | xargs -0 sed -i -e "s/release notes for
\([0-9]\+\)\.\([0-9]\+\)\.\([0-9]\+\)/release note for \1.\2.\3 in <xref
linkend=\"release-\1-\2-\3\">/g"

--
Vik

Vik Fearing <vik(dot)fearing(at)dalibo(dot)com> writes:
> The attached patch aims to help upgraders find the relevant information
> important to their upgrade.

This seems like a good idea, but bad implementation.

Why didn't you follow the existing style for the major-version links?
That is, a pattern like

However, if you are upgrading from a version earlier than 9.0.6,
see <xref linkend="release-9-0-6">.

What you've got is not just inconsistent with that nearby usage, but
redundant (especially in the plain-text output format) and bad grammar.

regards, tom lane

On 01/20/2014 08:35 AM, Tom Lane wrote:
> Vik Fearing <vik(dot)fearing(at)dalibo(dot)com> writes:
>> The attached patch aims to help upgraders find the relevant information
>> important to their upgrade.
> This seems like a good idea, but bad implementation.
>
> Why didn't you follow the existing style for the major-version links?
> That is, a pattern like
>
> However, if you are upgrading from a version earlier than 9.0.6,
> see <xref linkend="release-9-0-6">.
>
> What you've got is not just inconsistent with that nearby usage, but
> redundant (especially in the plain-text output format) and bad grammar.

I believe to have addressed your concerns in this new patch. I did not
do "make postgres.txt" on the previous version, but I did do it on this
one and it looks okay to me.

--
Vik

On 01/20/2014 04:42 PM, Vik Fearing wrote:
> On 01/20/2014 08:35 AM, Tom Lane wrote:
>> Vik Fearing <vik(dot)fearing(at)dalibo(dot)com> writes:
>>> The attached patch aims to help upgraders find the relevant information
>>> important to their upgrade.
>> This seems like a good idea, but bad implementation.
>>
>> [...]
> I believe to have addressed your concerns in this new patch. I did not
> do "make postgres.txt" on the previous version, but I did do it on this
> one and it looks okay to me.

I was hoping this could just be committed for the next batch of updates,
but since it hasn't been I have added it to CommitFest 2014-06 to
hopefully get it at least into 9.5.

https://commitfest.postgresql.org/action/patch_view?id=1405

--
Vik

On Mon, 2014-01-20 at 16:42 +0100, Vik Fearing wrote:
> I believe to have addressed your concerns in this new patch. I did
> not
> do "make postgres.txt" on the previous version, but I did do it on
> this
> one and it looks okay to me.

I think it would be even better to link directly to the migration notes,
not to the top-level section of the release notes. I suggest to add a
link target like

<sect2 id="release-9-2-4-migration">
<title>Migration to Version 9.2.4</title>

and then link to that.

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> I think it would be even better to link directly to the migration notes,
> not to the top-level section of the release notes. I suggest to add a
> link target like

> <sect2 id="release-9-2-4-migration">
> <title>Migration to Version 9.2.4</title>

> and then link to that.

I experimented with this and didn't really find that it improved the
browsing experience any compared to what Vik did. It might be noticeably
better if we had any significant amount of text above the "migration"
section, but we never do.

I'd prefer *not* to add yet another place where the version number
has to be manually adjusted each time one makes a new release-notes
section. (This is a task we've failed at a few times in the past ;-),
so I'm not just hypothecating.) So I'm -1 for this unless there's
really, really strong contrary opinion.

regards, tom lane

On 02/12/2014 03:40 PM, Tom Lane wrote:
> Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
>> I think it would be even better to link directly to the migration notes,
>> not to the top-level section of the release notes. I suggest to add a
>> link target like
>
>> <sect2 id="release-9-2-4-migration">
>> <title>Migration to Version 9.2.4</title>
>
>> and then link to that.
>
> I experimented with this and didn't really find that it improved the
> browsing experience any compared to what Vik did. It might be noticeably
> better if we had any significant amount of text above the "migration"
> section, but we never do.
>
> I'd prefer *not* to add yet another place where the version number
> has to be manually adjusted each time one makes a new release-notes
> section. (This is a task we've failed at a few times in the past ;-),
> so I'm not just hypothecating.) So I'm -1 for this unless there's
> really, really strong contrary opinion.

Not to hijack the thread but after a decade and a half of writing
release notes one would think that we would have a parser that goes
through and automatically updates the version number :P

jD

>
> regards, tom lane
>
>

--
Command Prompt, Inc. - http://www.commandprompt.com/ 509-416-6579
PostgreSQL Support, Training, Professional Services and Development
High Availability, Oracle Conversion, Postgres-XC, @cmdpromptinc
For my dreams of your image that blossoms
a rose in the deeps of my heart. - W.B. Yeats

Vik Fearing <vik(dot)fearing(at)dalibo(dot)com> writes:
> On 01/20/2014 08:35 AM, Tom Lane wrote:
>> Why didn't you follow the existing style for the major-version links?
>> That is, a pattern like
>> However, if you are upgrading from a version earlier than 9.0.6,
>> see <xref linkend="release-9-0-6">.

> I believe to have addressed your concerns in this new patch. I did not
> do "make postgres.txt" on the previous version, but I did do it on this
> one and it looks okay to me.

Committed. Thanks for doing what sure looks like a mind-numbingly
tedious bit of editing.

regards, tom lane

On 02/13/2014 01:25 AM, Tom Lane wrote:
> Committed. Thanks for doing what sure looks like a mind-numbingly
> tedious bit of editing.

Thank you for committing it!

--
Vik