Opened 6 years ago

Closed 4 years ago

#17747 closed enhancement (wontfix)

Do not remove tutorials without deprecating and redirecting the related pages

Reported by: tmonteil Owned by:
Priority: major Milestone: sage-duplicate/invalid/wontfix
Component: documentation Keywords:
Cc: ncohen, vdelecroix, fbissey, dcoudert, kcrisman Merged in:
Authors: Reviewers: Jeroen Demeyer
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description

Recent moves in the tutorials removed some pages in the tutorials, which creates dead links both in worksheets (e.g. pointers to the local live doc) and webpages (e.g. pages pointing to http://www.sagemath.org/doc).

The removed pages should be replaced by a small page containing:

  • a line explaining that the page is obsolete (kind of deprecation warning)
  • a link to its replacement

Concerned tickets seem to be: #17615 #17614 #17555

Change History (10)

comment:1 Changed 6 years ago by ncohen

More importantly, we should not compile the doc without the --warn-links flag. Otherwise all we can do is fix what we break, instead of not breaking anything in the first place :-/

comment:2 Changed 6 years ago by vbraun

  • Priority changed from blocker to major
  • Type changed from defect to enhancement

Not a blocker.

It would be nice to have stable links, but its not even clear how to do this without making progress impossible. As one data point, Python just has all versions of the docs online. So you can link to a fixed version (stable forever) or to the latest (which might change without notice).

comment:3 Changed 6 years ago by tmonteil

I am not speaking about keeping links stable forever, but indicating where is the follow-up. My point was just to re-create moved tutorial pages (bordeaux2008.rst, etc) with a reference to their new location.

Without such a fix, the recent changes in the doc (which were necessary to clean things up) create dead links all over the web (e.g. any webpage pointing to the bordeaux2008 thematic tutorial will point to a non-existing page) as well as on worksheets (this happens when you write links to some live tutorial within a worksheet, e.g. `LP tutorial </doc/live/thematic_tutorials/linear_programming.html>`__), which is why i consider this as blocker, at least a very annoying defect, since it actually breaks things.

comment:4 follow-up: Changed 6 years ago by vbraun

I agree that its annoying, but

  • creating auxiliary files by hand does not scale, it'll just break again
  • name one other large project that does it by sprinkling auxiliary doc files around
  • is delaying Sage-6.5 going to fix any of this?

comment:5 in reply to: ↑ 4 Changed 6 years ago by tmonteil

Replying to vbraun:

I agree that its annoying, but

  • creating auxiliary files by hand does not scale, it'll just break again

There could be a deprecation period : "This page does not exist anymore, please refer to that page. The current page will disappear on XXX.".

  • name one other large project that does it by sprinkling auxiliary doc files around

Name one other large project that knows about broken links and just don't care. If there is a better solution, let us take it.

  • is delaying Sage-6.5 going to fix any of this?

The problem is introduced in Sage-6.5, it is not a bad policy to fight against regression from a release to the next one.

comment:6 Changed 6 years ago by vbraun

We have no policy on preserving links, and no automatic system to avoid breaking links. I don't agree that we have a regression here, you just haven't noticed the current state of affairs before. We had broken documentation links with every previous release, just not one that you noticed.

Also, all kinds of file types might move (html, pdf, images, ...). How should we handle them and/or how do we make the web server hand out 301?

I already mentioned the IMHO correct solution: Version the docs on the web server just like Python does (see http://docs.python.org). There is nothing in the Sage repo that can do it, its just a web server configuration issue.

comment:7 Changed 6 years ago by ncohen

The next great thing we should do about the doc is try to make this --warn-links option the default one. Actually... Volker: wouldn't it be possible/easy to enable this option by default (in the 'make doc') for "some" folders at least ?

At some point the graph folder did not contain any broken link, and it would be good to keep it this way. On the other hand some folders contain a LOT of broken links, and we would need quite some work before being able to build their doc with this flag.

What would you think of enabling it for some folders right now so that we do not introduce new broken links there, and add new folders to this restricted list from time to time so that someday we do not have any broken link (that we can detect) ?

Nathann

comment:8 Changed 4 years ago by jdemeyer

  • Milestone changed from sage-6.5 to sage-duplicate/invalid/wontfix
  • Status changed from new to needs_review

Too much time has passed. It's pointless to fix this now.

comment:9 Changed 4 years ago by jdemeyer

  • Reviewers set to Jeroen Demeyer
  • Status changed from needs_review to positive_review

comment:10 Changed 4 years ago by embray

  • Resolution set to wontfix
  • Status changed from positive_review to closed

Closing tickets in the sage-duplicate/invalid/wontfix module with positive_review (i.e. someone has confirmed they should be closed).

Note: See TracTickets for help on using tickets.