Re: stability of toc links

[Tim Cross]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Samuel Loury <konubinix@gmail.com> writes:
>
>> The publish feature only means exporting several files at once. 
>
> You can publish a single file, too. It makes sense when a file is always
> exported to the same location, possibly with the same configuration.
>
>> IIUC, what was written was that when using the publish feature, the exported
>> html pages will be coherent and a link in one document pointing to
>> another document of the same publish call won't be broken.
>>
>> But IIUC, publishing the whole stuff again will result in totally
>> different links. They will still be coherent and no broken link from one
>> document of the whole to another. But a browser bookmark pointing the
>> published lot the first time won't work with the same lot the second
>> time.
>>
>> Did I understand correctly?
>
> That's correct. 
>
> Org provides a mechanism, called `org-export-get-reference', for
> creating internal references, which relies on randomness + cache. But it
> explicitly removes internal references not actually used from there (see
> `org-publish--store-crossrefs'). Keeping those references instead would
> make all links stable, of course.
>

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!

- If you need stability in TOC links between generated versions, use
  Org's publish facility rather than plain HTML export.

- Publish can be used to publish a single file.

- 'something' in the published output needs to reference the TOC links
  to ensure consistency.

HTML export lacks the internal caching/tracking necessary to have
internal link consistency across exported versions. Adding such
capability would significantly complicate the HTML export code base.
This is hard to justify when this export facility is also used for
things like HTML fragments and because internal link stability is only
required in a sub-set of use cases.

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.

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. 

-- 
Tim Cross