URLs to manual pages change over time
Darktable manual on main site has a number of pages that can be linked to. So far so good.
URLs refer to chapter section, subsection numbers, not id.
URLs are stable over time, they are permalinks .
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
#1 Updated by Tobias Ellinghaus over 2 years ago
- % Done changed from 0 to 20
- Status changed from New to Triaged
- Category deleted (
- 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.