Re: stability of toc links

[Nicolas Goaziou]

Hello,

Tim Cross <theophilusx@gmail.com> writes:

> Given this is not the first time we have seen a similar discussion
> regarding link stability for external references, perhaps it would be
> good to summarise and put it on worg for reference?
>
> First attempt - let me know if I've got it close!
>

[...]

> The org publish facility already includes the necessary internal
> facilities to support internal link consistency across published
> versions. You can use publish to publish a single file. Currently, the
> internal links need to be referenced/used in order to ensure consistency
> across published versions.

This is currently true.

> If stability of TOC links across versions is required, using publish is
> the preferred mechanism. If we would want to make it easier for the user
> to create published pages with consistent internal TOC links, we would
> be better off enhancing the publish mechanism rather than trying to add
> such facilities to the HTML export function. 

I would nuance the latter.

In a nutshell, Org provides a reference generation mechanism, with the
function `org-export-get-reference', which has with some interesting
properties. Major ones are:

  - references consist of alphanumeric characters only, so they are /de
    facto/ compatible with any target format;

  - references are guaranteed to be unique in the document;

  - cross-references between documents are stable.

It has obvious drawbacks, as noted already:

  - references themselves are not informative;

  - dangling links (i.e., not being cross-referenced) are not stable.

So, it was implemented as an adequate fall-back mechanism, one that
would not let down export back-end developers. It is clearly not
suitable for every need; I don't think such a system exists (but I would
love to be wrong).

It is important to understand that relying on `org-export-get-reference'
is optional, when a better local solution exists. For example, Texinfo
exporter relies on that function only as a last resort, and will
circumvent it whenever it can. See `org-texinfo--get-node'.

With the above in mind, I think there are two ways to "improve TOC links
stability":

1. Improve the system behind `org-export-get-reference', e.g., so it
   behaves better during plain export. But please keep in mind that
   current major properties must be preserved.

2. Use an hybrid system in HTML exporter, much like Texinfo's.

Those two ways are orthogonal; both may solve the current issue
independently on the other. My gut feeling is the second way is easier
to achieve, at least on the short term.

Regards,
-- 
Nicolas Goaziou