Thread: [PATCH] Cross-version navigation in documentation
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
Attachment
On Sunday, May 27, 2012, Marti Raudsepp wrote:
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
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.
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...
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);
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.
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?
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.
----
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
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/
Hi All, On Sunday, May 27, 2012 08:40:57 PM Magnus Hagander wrote: > On Sunday, May 27, 2012, Marti Raudsepp wrote: > > 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. > > 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. 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
On Mon, May 28, 2012 at 2:44 PM, Andres Freund <andres@2ndquadrant.com> 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. 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 <magnus@hagander.net> wrote: > On Sunday, May 27, 2012, Marti Raudsepp wrote: >> PS: Python projects have a nearly universal style of using 4-space >> indents (PEP-0008). > I don't really see the point. If your editor can't be consistent about > tabs/spaces, you probably have a bigger problem Well I need to reconfigure my editor to edit these files. >> 0001-Allow-documentation-loading-without-tidy-Tidylib-for.patch > 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. Ok, agreed. Regards, Marti
On Wed, May 30, 2012 at 11:58 AM, Marti Raudsepp <marti@juffo.org> wrote:
> On Mon, May 28, 2012 at 2:44 PM, Andres Freund <andres@2ndquadrant.com> 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.
>
> 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.
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?
> On Sun, May 27, 2012 at 9:40 PM, Magnus Hagander <magnus@hagander.net> wrote:
>> On Sunday, May 27, 2012, Marti Raudsepp wrote:
>>> PS: Python projects have a nearly universal style of using 4-space
>>> indents (PEP-0008).
>
>> I don't really see the point. If your editor can't be consistent about
>> tabs/spaces, you probably have a bigger problem
>
> 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)
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Tuesday, June 05, 2012 10:59:54 AM Magnus Hagander wrote:
> On Wed, May 30, 2012 at 11:58 AM, Marti Raudsepp <marti@juffo.org> wrote:
> > On Mon, May 28, 2012 at 2:44 PM, Andres Freund <andres@2ndquadrant.com>
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.
> >
> > 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.
>
> Given that nobody has objecte,d I'm going to go ahead and do this.
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
> 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.
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.
-- Andres Freund http://www.2ndQuadrant.com/PostgreSQL Development, 24x7 Support, Training &
Services
On Tue, Jun 5, 2012 at 11:42 AM, Andres Freund <andres@2ndquadrant.com> wrote:
> On Tuesday, June 05, 2012 10:59:54 AM Magnus Hagander wrote:
>> On Wed, May 30, 2012 at 11:58 AM, Marti Raudsepp <marti@juffo.org> wrote:
>> > On Mon, May 28, 2012 at 2:44 PM, Andres Freund <andres@2ndquadrant.com>
> 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.
>> >
>> > 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.
>>
>> Given that nobody has objecte,d I'm going to go ahead and do this.
> 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
>> 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.
> 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.
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 :)
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Tue, Jun 5, 2012 at 11:02 AM, Magnus Hagander <magnus@hagander.net> wrote: > > 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 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
Attachment
On Wed, Jun 6, 2012 at 7:38 PM, Dave Page <dpage@pgadmin.org> wrote: > 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. I suspect your browser has cached the old version of the CSS. Does a refresh solve it? Regards, Marti
On Wed, Jun 6, 2012 at 5:49 PM, Marti Raudsepp <marti@juffo.org> wrote: > On Wed, Jun 6, 2012 at 7:38 PM, Dave Page <dpage@pgadmin.org> wrote: >> 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. > > I suspect your browser has cached the old version of the CSS. Does a > refresh solve it? Yes. It's been a long day :-(. Thanks! -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise PostgreSQL Company
>> I suspect your browser has cached the old version of the CSS. Does a >> refresh solve it? 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
On 07/06/2012 01:12, Josh Berkus wrote: > >>> I suspect your browser has cached the old version of the CSS. Does a >>> refresh solve it? > > Oh, wow, very nice! That should really help our "Google links to > ancient version of the docs" problem. +1 Thanks and well done! Ray. -- Raymond O'Donnell :: Galway :: Ireland rod@iol.ie
On Wed, Jun 6, 2012 at 5:12 PM, Josh Berkus <josh@agliodbs.com> wrote: > >>> I suspect your browser has cached the old version of the CSS. Does a >>> refresh solve it? > > Oh, wow, very nice! That should really help our "Google links to > 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
On Wed, Jun 13, 2012 at 1:18 AM, Josh Kupershmidt <schmiddy@gmail.com> wrote: > On Wed, Jun 6, 2012 at 5:12 PM, Josh Berkus <josh@agliodbs.com> wrote: >> >>>> I suspect your browser has cached the old version of the CSS. Does a >>>> refresh solve it? >> >> Oh, wow, very nice! That should really help our "Google links to >> 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? That seems both reasonable and easy - so, done. -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/