Project

General

Profile

Bug #11406

URLs to manual pages change over time

Added by Stéphane Gourichon over 2 years ago. Updated over 2 years ago.

Status:
Triaged
Priority:
Low
Assignee:
-
Start date:
12/30/2016
Due date:
% Done:

20%


Description

Context

Darktable manual on main site has a number of pages that can be linked to. So far so good.

Example: https://www.darktable.org/usermanual/ch02s02s07.html.php 2.2.7. Sidecar files | user manual | darktable

URLs refer to chapter section, subsection numbers, not id.

Expected behavior

URLs are stable over time, they are permalinks .

Observed behavior

Links from any site to darktable manual rot over time.

As the manual is reworked and expanded, operations that change numbers (insert/remove/reorder chapter/section) break URLs and sites linking to darktable.

For example, "8.3. Session options" might have been numbered 7.3 until "6. Slideshow" was introduced. Link to https://www.darktable.org/usermanual/ch07s03.html.php yields 404.

Example observed in the field of old URLs pointing to different documents reported on: Feature #9402: Darktable-cli: Work without sidecar files - darktable - darktable - photography workflow application .

Hint about possible implementation

The good news are: URLs are close to being permalink. Only the chapter/section/subsection generation logic introduces the flaw.

Looking at a random source file, I see that there are IDs, e.g. in https://redmine.darktable.org/projects/darktable/repository/revisions/master/entry/doc/usermanual/slideshow/slideshow.xml

<chapter status="final" id="slideshow_chapter">

Generating links based on id would make links resilient to section insertion/deletion/reordering.

I see in doc that doc is in DocBook format processed by Saxon. There is probably some option there to choose how URLs are generated.

Canonical reference: Hypertext Style: Cool URIs don't change. see also Tim Berners-Lee: Cool URIs don't change (1998) | Hacker News

History

#1 Updated by Tobias Ellinghaus over 2 years ago

  • % Done changed from 0 to 20
  • Status changed from New to Triaged
  • Category deleted (Usermanual)
  • Project changed from darktable to website

Yes, URLs that don't change and are not cryptic would be nice. It probably requires someone knowing saxon and docbook though. I am not even able to build the manual for the website so I won't be of any use here.

Also available in: Atom PDF