Received: from magus.postgresql.org (magus.postgresql.org [87.238.57.229]) by mail.postgresql.org (Postfix) with ESMTP id 8575DC2FBC7 for ; Sun, 27 May 2012 15:41:15 -0300 (ADT) Received: from mail-lpp01m010-f46.google.com ([209.85.215.46]) by magus.postgresql.org with esmtp (Exim 4.72) (envelope-from ) id 1SYiOu-00050O-2G for pgsql-www@postgresql.org; Sun, 27 May 2012 18:41:14 +0000 Received: by lahd3 with SMTP id d3so1525974lah.19 for ; Sun, 27 May 2012 11:40:58 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:x-gm-message-state; bh=3DSCikw77m24u9RavHVM+P6Y8LwSVaCZEKf46hgDTX4=; b=iU63aXZDDFMlaiI4nNe6uv2ud7ahOiugzItOTjZCs8B/Vf9Gy7vExt+43Yc3yLOpOQ s92iuNp/XrKcPsPfNOovSioRCkBRqtRB1fCenS4urns21EdkFOs5U7Taes5Xe0nU52iR pqC+Qq2EgjReUR2S0BoXLw0QKMYd8fer8cSiSFIJyNsxRKS4tEJ7zPAs5tnkVlYL0dnp eIY+VVJuk7jRxPBfNVgMIpnKN2tobCkkEi5uhQRDGvyM6zCTG9J86gwrIlACwgjwM/8M DF8cRJ61JQIs2cKuu68J1WsiRVAaUNRU1VJITgHqZOb/Ed/KJG+PalRykgeS2x9w+//j V67Q== MIME-Version: 1.0 Received: by 10.112.86.166 with SMTP id q6mr2554112lbz.6.1338144057854; Sun, 27 May 2012 11:40:57 -0700 (PDT) Received: by 10.152.21.234 with HTTP; Sun, 27 May 2012 11:40:57 -0700 (PDT) In-Reply-To: References: Date: Sun, 27 May 2012 20:40:57 +0200 Message-ID: Subject: Re: [PATCH] Cross-version navigation in documentation From: Magnus Hagander To: Marti Raudsepp Cc: pgsql-www , Andres Freund , Stefan Kaltenbrunner Content-Type: multipart/alternative; boundary=f46d0401faed3a0d4b04c108f1e6 X-Gm-Message-State: ALoCoQlgzmhRwWh5VgDnmAuql00AkQ3njYTDhG9yQ1uGca+8zt6CybRG3LWs8/6XGqkz65+8bJjq X-Pg-Spam-Score: -2.6 (--) X-Archive-Number: 201205/59 X-Sequence-Number: 20683 --f46d0401faed3a0d4b04c108f1e6 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable 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. 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 =B5Tidylib -- > 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. --=20 Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/ --f46d0401faed3a0d4b04c108f1e6 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable 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 r= ejected 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 cont= ain the same information but have been renamed (because the section was ren= amed). E.g. it's not a problem that there is no mapping for pg_baseback= up 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:
=A0 =A0alter table docs add unique (file, version);
<= br>
There was an index around, but it wasn't reflected in the= python code so it wouldn't be regenerated. Artifact of the migration. = =A0So that should obviously be fixed.
=A0
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 s= ee the point. If your editor can't be consistent about tabs/spaces, you= probably have a bigger problem, particularly when dealing with python ;) I= f 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.=A0


----
Attached are two patches:

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

Th= is I don't like at all. Maybe you should switch to a distro that includ= es some basic packages? ;)

More to the point thoug= h - 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.





--
=A0Magnus Hagan= der
=A0Me: http:/= /www.hagander.net/
=A0Work: http://www.redpill-linpro.com/
--f46d0401faed3a0d4b04c108f1e6--