From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0r.migadu.com with LMTPS id iP4uGIRLjWDNcAEALuJCtg (envelope-from ) for ; Sat, 01 May 2021 14:37:24 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id 6IfvE4RLjWD0VwAA1q6Kng (envelope-from ) for ; Sat, 01 May 2021 12:37:24 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id C41D7117D8 for ; Sat, 1 May 2021 14:37:23 +0200 (CEST) Received: from localhost ([::1]:40644 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lcos5-000438-Vf for larch@yhetil.org; Sat, 01 May 2021 08:37:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:49908) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lcorH-00041v-SU for emacs-orgmode@gnu.org; Sat, 01 May 2021 08:36:32 -0400 Received: from relay8-d.mail.gandi.net ([217.70.183.201]:60087) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lcor7-0000KO-2u for emacs-orgmode@gnu.org; Sat, 01 May 2021 08:36:31 -0400 X-Originating-IP: 185.131.40.67 Received: from localhost (40-67.ipv4.commingeshautdebit.fr [185.131.40.67]) (Authenticated sender: admin@nicolasgoaziou.fr) by relay8-d.mail.gandi.net (Postfix) with ESMTPSA id 67AA81BF203; Sat, 1 May 2021 12:36:15 +0000 (UTC) From: Nicolas Goaziou To: Tim Cross Subject: Re: stability of toc links References: <877dkzg9y2.fsf@nicolasgoaziou.fr> <87wnsx9rcj.fsf@nicolasgoaziou.fr> <87y2dc82ct.fsf@nicolasgoaziou.fr> <87sg3j4vbl.fsf@gmail.com> <33fd87ff1332b56114909973804df669@isnotmyreal.name> <87h7joibxc.fsf@gmail.com> <87pmycay41.fsf@gmail.com> <87h7jouiuk.fsf@nicolasgoaziou.fr> <875z03igpf.fsf@gmail.com> Mail-Followup-To: Tim Cross , emacs-orgmode@gnu.org, Samuel Loury Date: Sat, 01 May 2021 14:36:14 +0200 In-Reply-To: <875z03igpf.fsf@gmail.com> (Tim Cross's message of "Sat, 01 May 2021 07:12:34 +1000") Message-ID: <87tunmskap.fsf@nicolasgoaziou.fr> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=217.70.183.201; envelope-from=mail@nicolasgoaziou.fr; helo=relay8-d.mail.gandi.net X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: emacs-orgmode@gnu.org, Samuel Loury Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1619872644; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post; bh=WDXYnBkh8XTYkyxK3WG1+6FzJEMQwUUplA3+aMq2Ufc=; b=Q1nDNQ3ewbxkFNCNgTMQ749cRIIa+y5wrZTBTz+bBgVY0dab2Z0VYNu41DHJlh4LgQbZX7 tTqO0ryoj0m2TvQjqEcCMY/SMLFYuPiA2zTyFjiRruRLfOcdsrnRbYDIv0WrxLpypsp3qa xQ7edGGyZFJfY6oKkboAj0g1E3g/JzCrwMrxuYWl4vA4YYPxIkOIUi5EMJaPnXhmWmvUya VEkU5B8RBedE/tUrR7Dvy835jiYTZ4rVAO/TjckUrT7dbHg7a5SIYztgMpbv2yO6N/r+yi VAN9xbz+1kbM5gXSOGr5oyxleevanz+3YLzC+CpD45rQW5HXivrg+5oC3T4jDA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1619872644; a=rsa-sha256; cv=none; b=j69vSa09AVL72U09XNPNiGQiB8n+SnEugGyUAv3j6HWXHv1dD9Z0Gnh8Wyvfq2hCmGqj22 FML6iu4BgKbEnaUbNquy/ELkMbxV8ujx4MXzNzoWPOKxDGb7u+raBhWAk/4LKfL00YUKal wA5+pLJP4nOqVvnapbnLPfJDqMyS2zY4mhOrea+JzNzVW0KnL1ZjA96/FODsXzTi3Sky0t WtAXUOMYI480wLo6pyIXVILHv2SffAo9GHOjnavWChbkmKKPrXj1g6vDb83OKQfVznWKaD 4oAaaXvW9JuI8F0W96sLmMmIU9hvTKYSYWhGNhgyhSj0ajzjTqoOngkfnDAiYg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Spam-Score: -2.46 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Queue-Id: C41D7117D8 X-Spam-Score: -2.46 X-Migadu-Scanner: scn0.migadu.com X-TUID: hgQqbT8977VM Hello, Tim Cross 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