Re: [PATCH] Cross-version navigation in documentation

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 µ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/