[FR] [Revived] Human readable / customizable link anchors during export (was: stability of toc links)

[Ihor Radchenko]

Timothy <tecosaur@gmail.com> writes:

>> Link stability is still an issue, even if the proposal gives a false
>> sense of security in that area. I don't think we can solve it without
>> creating a cache for export, where you store all previous references for
>> a given file. Even this is not sufficient, because you can export
>> buffers not attached to files.
>
> To me this is a case of "don't let the perfect be the enemy of the
> good", though I do see that a false sense of security may be
> problematic, I consider the benefits to outweigh this.

I would like to revive this thread as we now have an important
development happened after this discussion -- org-persist library. It
can handle caching without a need to have a dedicated cache
implementation for every use-case.

To summarize the previous discussion:

- Org export currently generates ugly link anchors, which degrade the
  export output quality. In particular, html export can generate link
  anchors like
  
https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-ditaa.html#org96b5528
  Note that randomly generated #org96b5528 anchor

- The anchors are not just unreadable, but also change on every single
  export. (Except for ox-publish, which maintains anchor cache; but not
  all the people use or need publishing)

- The random anchors are there for a reason: it is difficult to
  derive anchors based on the heading title/contents and avoid
  duplicates and also keep track of the same heading being modified.

  If we have

  * duplicated heading
  Text
  * duplicated heading
  Text

  we cannot usefully derive the anchor from the identical headings

  even worse

  * unique heading
  * duplicated heading

  can be changed to

  * duplicated heading
  * duplicated heading

  and we cannot find out which old anchor was for which heading

- Further, there appears to be no suitable _universal_ algorithm to
  generate human-readable anchors. Timothy proposed one, but it does not
  work well for non-Latin text.

----------------------------

Proposal:

1. To avoid collisions, we can add randomness to the anchors:

   * This is headline

   will be #this-is-headline-<4 random letters>

2. The generated anchors will be cached according to headline text +
   headline contents + headline number in the document via org-persist.
   During consequent exports, if two out of the three keys match, we
   take the cached anchor.

3. Instead of trying to find a silver bullet for human-readable anchor
   generator, we allow users to customize it. The default will be
   constant "org" yielding "org-Ajjq"-type anchors, just like we have
   now. But we can also provide other generators, like the one Timothy
   proposed, or better versions contributed in future if there is
   demand.

WDYT?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>