Bug #11406

URLs to manual pages change over time

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

Start date:
Due date:
% Done:


Estimated time:



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

Example: 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 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

<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


#1 Updated by Tobias Ellinghaus over 3 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

Go to top