Manuals for old versions of packages

[olexandr-konovalov]

When a new release is published, the main GAP manuals are replaced by their newer versions (it would be nice to have something like readthedocs which would allow to access older versions in some consistent way, but that's the today's reality).

However, we handle packages differently: at the moment, under www.gap-system.org/Manuals/pkg we have:

4ti2Interface
4ti2Interface-2017.01.05
4ti2Interface-2017.10.04
4ti2Interface-2018.07.06
ace
ace-5.2
aclib
aclib-1.3
alnuth
Alnuth-3.0.0
alnuth-3.1.0
anupq
anupq-3.1.1
anupq-3.1.3
anupq-3.1.4
anupq-3.1.5
anupq-3.2
atlasrep
AutoDoc
AutoDoc-2016.02.16
AutoDoc-2016.03.08
AutoDoc-2016.12.04
AutoDoc-2017.09.08
AutoDoc-2018.02.14
automata
automgrp
autpgrp
autpgrp-1.10
autpgrp-1.9
browse
Browse
CAP
CAP-2016.02.19
CAP-2017.07.25
CAP-2017.09.25
carat
circle
circle-1.6.1
citrus-0.4
citrus-0.5
citrus-0.6
citrus-0.9
citrus-0.99
citrus-0.999
citrus-0.9999
cohomolo
cohomolo-1.6.4
cohomolo-1.6.6
congruence
congruence-1.2.1
congruence-1.2.2
Convex
corelg
crime
crisp
crisp-1.4.3
crisp-1.4.4
crypting-0.6
crypting-0.7
crypting-0.8
...
example
Example-3.5.1
Example-4.1.0
Example-4.1.1
...

etc.

As one can guess from directory names, when the name of the package directory in a new package release includes its version, then a new directory will appear. When name of the package directory coincides with the name of a package, then the manual from the new release will overwrite the old version of the manual. The name of the directory is case-sensitive, so if the spelling was changed at some point, you will see both variants, like in browse and Browse.

Keeping older older package manuals is useful in case anyone shared a link to them elsewhere. However, it may cause problems like the one reported in gap-system/gap#1305.

OTOH, package websites (can't speak for all packages, but at least those using ReleaseTools and GitHubPagesForGAP) do not keep former versions of their manuals. Their website provide the manual from the latest release, and the URL is not version-dependent, e.g. http://gap-packages.github.io/example/doc/chap0.html.

The current setup is not consistent. Shall we remove directories for old package releases and packages that are not redistributed with GAP any more (should anyone require their manuals, they could do this by downloading the archive with the corresponding release)?

[fingolfin]

For the sake of preventing people from using google to search for a manual, and accidentally ending up with an old version, I'd be radical and remove all the old manuals.

But this then would break existing bookmarks and links left and right (even on our own pages if we are not careful), so it is a bit too radical...

One "solution" for this would be to add redirect from the old dirs to the new ones. Another would be to normalize the director names: don't use the name from the archive or whatever, just use the bare package name, converted to all-lowercase.

I am tempted to suggest we combine the two: for future additions, we normalize the dir names. For existing dirs only, we add a .htaccess file with 301 or 302 redirects for the existing dirs with names that include a version; such a .htaccess file could easily be generated by a script. (This assumes that we are using Apache as web server, which I believe used to be the case, but I haven't checked recently; but other web servers offer similar features). Unfortunately, I don't know how to access our web server via SSH, or wether I even have permissions to do so, so I can't take a closer look to see how feasible this is.

(Incidentally: I notice that these file are not in the GapWWW repository. Do we have a backup plan for this data then, in case the current server crashes and burns?)

[olexandr-konovalov]

That solution may break cross-references from one package manual to another package manual, but that's probably a lesser evil in this case...

[fingolfin]

OK, so if we add suitable redirects (resp wildcard redirects), it won't break any references