Automate updating the manuals on docs.gap-system.org

[fingolfin]

Installing the manuals of a new GAP release is currently the manual step
ssh gap-docs; ./download_manuals.sh X.Y.Z, described in dev/releases/README.md
in the GAP repository. This adds etc/mirror-manuals.py plus a systemd timer that
runs it hourly on the docs host, so the manuals of a new release appear by
themselves once the release stops being a pre-release.

It reuses extract_manuals.py and utils.download_with_sha256() from this
directory, which is why it lives here.

Compared to download_manuals.sh, which it replaces and which remains available
as a fallback, it also:

• verifies both downloads against the .sha256 files published beside them,
  which the old script fetched but never checked;
• installs the manuals with a single rename, so a half-extracted tree is never
  served;
• replaces the latest symlink by renaming a new one over it, so latest --
  and the doc and pkg symlinks that resolve through it -- is never briefly
  missing;
• cleans up afterwards. The old script only cleaned at the start of the next
  run, so 1.9 GB from the 4.16.0 release has been sitting on the docs host since
  June.

Verified on the docs host: a dry run against the live document root correctly
reports nothing to do, and a full build of 4.16.0 into a scratch directory
produced a tree identical to the live v4.16.0 -- same 10417 files, same
312 MB, diff -r reporting no differences -- in about 11 minutes, cleaning up
its 2 GB work directory afterwards. The live site was not touched.

This also updates etc/docs.htaccess to match the file actually deployed on the
docs host, which had gained a redirect from the bare domain to
https://www.gap-system.org/doc/ that was never brought back here. Since the
deployed file is a hand-made copy, the two had silently drifted.

Once this is merged the timer still has to be enabled on the host:

mkdir -p ~/.config/systemd/user
cp ~/data/GapWWW/etc/gap-mirror-manuals.* ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now gap-mirror-manuals.timer

AI disclosure: prepared with Claude Code, which drafted the script, units and
this description; reviewed by the pull request author.

[fingolfin]

Added a second commit with the renaming and the documentation.

Units renamed to gap-docs-manuals.{service,timer}. Worth flagging that the existing units were not in fact called gap-files* — the ones I deployed on the archive server were gap-mirror-packages and gap-mirror-releases, so there was nothing to mirror. I have taken the naming convention you describe and applied it to those too: they are now gap-files-packages and gap-files-releases (gap-system/gap-files@4fa8957), already renamed and re-enabled on the host, both verified running. The website's gap-website.* units predate all of this and I left them alone; say if you want them renamed to gap-www-* for full consistency.

Documentation is now split per site, since the hosting spans three virtual hosts driven by two repositories:

• etc/README.server.md is now the overview and the entry point: which site is served by which account and repository, the SSH aliases, the conventions all three share (the ~/data and ~/http symlinks, the NFS storage, RZ-managed Apache, lingering, units installed as copies), a rebuild-from-nothing checklist, and troubleshooting that applies anywhere.
• etc/README.gap-www.md — the website: webhook, trigger file, path/service units, update.sh, how the secret is kept out of git, and the file-ownership repair that is the usual cause of trouble.
• etc/README.gap-docs.md — the manuals: layout, how a release is picked up, forcing a rebuild, the .htaccess copy, and setup from scratch.
• The archive server stays documented in the gap-files repository, where its scripts live; the overview links to it and its README links back.

While writing this I found and fixed two pieces of wrong information that would have cost real time during a rebuild:

• README.md gave the archive server's document root as /srv/www/www-gap-docs/files/http. The actual path is /srv/www/www-gap-files/data/http — wrong account and wrong shape.
• The setup instructions said to run ln -s /srv/www/www-gap-systems/data/http ~/data/http. No such symlink exists on any of the three accounts; the convention is ~/data (ours) plus ~/http (created by the RZ, root owned). I checked all three hosts and they are consistent.

I also recorded the thing that seemed most important for a disaster: everything except the package archives can be rebuilt from GitHub, but files.gap-system.org is the archive of record for old package releases — if it is lost, the only copies are RZ backups and whatever developers happen to have locally.