emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Tim Cross <theophilusx@gmail.com>
Cc: emacs-orgmode@gnu.org, Samuel Loury <konubinix@gmail.com>
Subject: Re: stability of toc links
Date: Sat, 01 May 2021 14:36:14 +0200	[thread overview]
Message-ID: <87tunmskap.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <875z03igpf.fsf@gmail.com> (Tim Cross's message of "Sat, 01 May 2021 07:12:34 +1000")

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


  reply	other threads:[~2021-05-01 12:37 UTC|newest]

Thread overview: 58+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-12-08 23:28 stability of toc links Samuel Wales
2020-12-08 23:30 ` Samuel Wales
2020-12-09  1:39   ` Tom Gillespie
2020-12-12 21:51     ` TRS-80
2020-12-12 22:47       ` TRS-80
2022-10-10  0:49     ` Samuel Wales
2022-10-10  1:37       ` Samuel Wales
2022-10-11  3:12         ` Robert Weiner
2022-10-11 11:25         ` Ihor Radchenko
2020-12-09  2:48 ` TEC
2020-12-09  8:45   ` Diego Zamboni
2020-12-09  9:15   ` Carsten Dominik
2020-12-09 21:25     ` Samuel Wales
2020-12-10  9:55       ` Carsten Dominik
2020-12-10 12:49         ` TEC
2020-12-10 14:36           ` TEC
2020-12-11  7:51             ` Carsten Dominik
2020-12-19  6:41               ` Carsten Dominik
2020-12-19 11:22                 ` Ihor Radchenko
2021-04-18 21:02   ` Samuel Wales
2020-12-14 10:46 ` Dominique Dumont
2021-04-18 10:32 ` Nicolas Goaziou
2021-04-20  0:58   ` Samuel Wales
2021-04-20 10:34     ` Nicolas Goaziou
2021-04-21  0:33       ` Samuel Wales
2021-04-21  8:32         ` Nicolas Goaziou
2021-04-21 13:32           ` Samuel Loury
2021-04-21 16:24             ` Nicolas Goaziou
2021-04-23 15:15               ` Maxim Nikulin
2021-04-23 20:46                 ` Samuel Wales
2021-04-23 20:48                   ` Samuel Wales
2021-04-23 20:51                     ` Samuel Wales
2021-04-24  3:05                 ` Timothy
2021-04-25 17:01               ` Dominique Dumont
2021-04-30  6:24                 ` Timothy
2021-04-30 12:20                   ` Maxim Nikulin
2021-04-21 23:20             ` Samuel Wales
2021-04-21 23:30               ` Samuel Wales
2021-04-29 21:40                 ` TRS-80
2021-04-29 22:18                   ` Samuel Wales
2021-04-30  1:48                     ` TRS-80
2021-04-30  5:13                     ` Tim Cross
2021-04-30 10:02                       ` Samuel Loury
2021-04-30 11:12                         ` Nicolas Goaziou
2021-04-30 21:12                           ` Tim Cross
2021-05-01 12:36                             ` Nicolas Goaziou [this message]
2021-05-01 12:48                               ` Timothy
2021-05-01 13:13                                 ` Nicolas Goaziou
2021-05-01 13:47                                   ` Timothy
2021-05-01 14:09                                     ` Nicolas Goaziou
2021-05-01 14:22                                       ` Timothy
2021-05-02 12:10                                         ` Nicolas Goaziou
2021-05-02 20:16                                           ` Timothy
2022-10-11 11:44                                             ` [FR] [Revived] Human readable / customizable link anchors during export (was: stability of toc links) Ihor Radchenko
2022-10-11 19:20                                               ` [FR] [Revived] Human readable / customizable link anchors during export Kévin Le Gouguec
2022-10-12  6:33                                                 ` Ihor Radchenko
2022-10-12 17:38                                                   ` Kévin Le Gouguec
2021-05-01  3:08                           ` stability of toc links Greg Minshall

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87tunmskap.fsf@nicolasgoaziou.fr \
    --to=mail@nicolasgoaziou.fr \
    --cc=emacs-orgmode@gnu.org \
    --cc=konubinix@gmail.com \
    --cc=theophilusx@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).