Subject: [PATCH] Cross-version navigation in documentation

From: Marti Raudsepp <[email-masked]>
Date: Sun, 27 May 2012 21:06:03 +0300

Hi list,

It always bothers me that Google links to version-specific PostgreSQL
documentation pages, usually an obsolete version. This patch lets you
easily navigate to the version you want by adding a new line at the
top:

This page in other versions: 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 /
8.0 / 7.4 / 7.3 / 7.2 / devel

The same page in different versions is assumed to have the same file
name. No effort is done to track pages which have been
removed/added/split/renamed -- I think that would be lots of
complexity for little gain. For example, The 7.4 version contains 644
doc pages, and only 68 of those (~10%) aren't present in 9.2. In
actual relevant versions, the overlap is much greater.

I also noticed that the docs table isn't currently indexed at all.
docs/models.py now defines a new index/unique constraint, which
requires manual migration:
    alter table docs add unique (file, version);

PS: Python projects have a nearly universal style of using 4-space
indents (PEP-0008). I understand that PostgreSQL itself uses tabs, but
maybe a change is warranted here, since Python is particularly picky
about indentation?

----
Attached are two patches:

0001-Allow-documentation-loading-without-tidy-Tidylib-for.patch
Just a simple fallback so docs can be imported without µTidylib --
which is not packaged for Arch Linux

0002-Add-basic-version-navigation-support-for-documentati.patch
Actual implementation of cross-version navigation

Also available from my github fork: https://github.com/intgr/pgweb

Regards,
Marti

---

From: Magnus Hagander <[email-masked]>
Date: Sun, 27 May 2012 20:40:57 +0200

> actual relevant versions, the overlap is much greater.

Pretty sure this was discussed before, and rejected then as not being what
we wanted due to the lack of tracking cross-version changes (if it was just
the links, it could've been done a long time ago..)

It might wel be worth reopening that discussion though. I think the
important part is not missing pages - it's pages that contain the same
information but have been renamed (because the section was renamed). E.g.
it's not a problem that there is no mapping for pg_basebackup in versions
prior to 9.1 - because it simply did not exist.

So I'd invite those who were critical the last time to re-hash their
arguments...

>    alter table docs add unique (file, version);

There was an index around, but it wasn't reflected in the python code so it
wouldn't be regenerated. Artifact of the migration.  So that should
obviously be fixed.

> maybe a change is warranted here, since Python is particularly picky

I don't really see the point. If your editor can't be consistent about
tabs/spaces, you probably have a bigger problem, particularly when dealing
with python ;) If it was done from scratch, maybe that would've been a
better idea, but I don't see the point of changing it after the fact.

----
> which is not packaged for Arch Linux

This I don't like at all. Maybe you should switch to a distro that includes
some basic packages? ;)

More to the point though - if we want a feature like that, it should be
controlled by a parameter that turns it off, not by automatically doing it.
These scripts are run as part of larger load operations, and a warning
might easily be missed - and if something actually goes wrong with the tidy
install on those boxes, we *want* it to be an error.

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

---

From: Andres Freund <[email-masked]>
Date: Mon, 28 May 2012 13:44:51 +0200

Hi All,

> prior to 9.1 - because it simply did not exist.
The amount of pages actually having been renamed isn't that big. Marti opened 
up his version of the docs to me and I browsed along and even between 7.4 and 
9.1 I had a hard time finding pages where you would expect a link from 7.4 
forwards.
Except very minor cases (e.g. sql-createconstraint.html => sql-
createtrigger.html) the pagenames for the sql commands itself haven't changed 
in quite a while now. And imo that and some of the function references is 
where you most often want to switch between individual versions because you 
want to ensure youre back/forward compatible.
Sure, it won't be totally perfect, but the usability win already is so big in 
comparison with trying to change the version in the url all the time that I 
don't get why those few corner cases should block the imo large improvment.

If anything pages which changed their meaning but kept the name would be 
worrying, but I don't really see that happnening often enough to be relevant.

Greetings,

Andres
-- 
 Andres Freund	                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services

---

From: Marti Raudsepp <[email-masked]>
Date: Wed, 30 May 2012 12:58:26 +0300

> 9.1 I had a hard time finding pages where you would expect a link from 7.4

Exactly. And people rely on page names right now anyway -- they find
the page on Google and then just change the version number in the URL
and see if it works. Either that, or they will read the wrong version.
What I'm proposing solves >95% of the cases and I think that is good
enough.

In theory we could mine git history to extract page
renames/merges/splits, but it sounds like a lot of effort for little
gain.

On Sun, May 27, 2012 at 9:40 PM, Magnus Hagander <[email-masked]> wrote:
>> indents (PEP-0008).

> tabs/spaces, you probably have a bigger problem

Well I need to reconfigure my editor to edit these files.

> controlled by a parameter that turns it off, not by automatically doing it.

Ok, agreed.

Regards,
Marti

---

From: Magnus Hagander <[email-masked]>
Date: Tue, 5 Jun 2012 10:59:54 +0200

> What I'm proposing solves >95% of the cases and I think that is good

Given that nobody has objecte,d I'm going to go ahead and do this.

However - should we perhaps just list supported versions? Turns the query into:
	versions = DocPage.objects.filter(file=fullname).extra(where=['version
IN (SELECT tree FROM core_version WHERE
supported)']).order_by('-version').only('version', 'file')

or if we do want to list all versions, we should somehow indicate
which versions are supported and not on this list as well, I think.
But I'm happy to just listed supported versions for now.

Thoughts?

> Well I need to reconfigure my editor to edit these files.

I'm sure you can instruct it to reconfigure itself once you know it
though ;) (based on pathname or such)

---

From: Andres Freund <[email-masked]>
Date: Tue, 5 Jun 2012 11:42:33 +0200

On Tuesday, June 05, 2012 10:59:54 AM Magnus Hagander wrote:
> >> The amount of pages actually having been renamed isn't that big. Marti
> >> opened up his version of the docs to me and I browsed along and even
> >> between 7.4 and 9.1 I had a hard time finding pages where you would
> >> expect a link from 7.4 forwards.
> > 
Great!

> However - should we perhaps just list supported versions? Turns the query
> into: versions =
> DocPage.objects.filter(file=fullname).extra(where=['version IN (SELECT
> tree FROM core_version WHERE
I personally would like to see older versions there because every now and then 
I need to look something up for them, but its infrequent enough that I don't 
especially care.

Thanks!

Andres

PS: Sorry Magnus, youve got the email twice. I recently reconfigured my mail 
client to disassociate reply-all from its previous key combination and I 
havent fully retrained myself.

---

From: Magnus Hagander <[email-masked]>
Date: Tue, 5 Jun 2012 12:02:27 +0200

> I need to look something up for them, but its infrequent enough that I don't

Well, I'm happy to include those *IF* we add some sort of indication
that they aren't supported. Hmm. maybe just "this page in other
version" and "this page in unsupported versions".

I'll do some experimenting :)

---

From: Dave Page <[email-masked]>
Date: Wed, 6 Jun 2012 17:38:02 +0100

> version" and "this page in unsupported versions".

I see this got committed. Unfortunately on Chrome (on Mac) the layout
is a little messed up. Can you fix the alignment please, and maybe add
a blank line between the breadcrumbs and the new text?

Screenshot attached.

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

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

---

From: Marti Raudsepp <[email-masked]>
Date: Wed, 6 Jun 2012 19:49:00 +0300

On Wed, Jun 6, 2012 at 7:38 PM, Dave Page <[email-masked]> wrote:
> Unfortunately on Chrome (on Mac) the layout

I suspect your browser has cached the old version of the CSS. Does a
refresh solve it?

Regards,
Marti

---

From: Dave Page <[email-masked]>
Date: Wed, 6 Jun 2012 17:51:24 +0100

> I suspect your browser has cached the old version of the CSS. Does a

Yes. It's been a long day :-(.

Thanks!

---

From: Josh Berkus <[email-masked]>
Date: Wed, 06 Jun 2012 17:12:17 -0700

>> I suspect your browser has cached the old version of the CSS. Does a

Oh, wow, very nice!  That should really help our "Google links to
ancient version of the docs" problem.

-- 
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

---

From: Raymond O'Donnell <[email-masked]>
Date: Thu, 07 Jun 2012 10:22:55 +0100

> ancient version of the docs" problem.

+1

Thanks and well done!

Ray.

-- 
Raymond O'Donnell :: Galway :: Ireland
[email-masked]

---

From: Josh Kupershmidt <[email-masked]>
Date: Tue, 12 Jun 2012 16:18:24 -0700

> ancient version of the docs" problem.

I've been finding the feature quite useful, so thanks. One gripe I
just noticed: if I wind up on an /interactive/... link, e.g.
  http://www.postgresql.org/docs/9.2/interactive/sql-createtable.html

and try to go to the -devel version from there, I'll always get a 404,
presumably since we don't have an interactive version of the -devel
docs. Would it be possible to redirect all the "/devel/interactive/"
links to their "/devel/static/" equivalents?

Josh

---

From: Magnus Hagander <[email-masked]>
Date: Wed, 13 Jun 2012 09:01:22 +0200

> links to their "/devel/static/" equivalents?

That seems both reasonable and easy - so, done.