Re: [BUG] HTML export does not preserve footnote label [9.6.15 (release_9.6.15 @ /usr/local/share/emacs/30.0.50/lisp/org/)]

[Protesilaos Stavrou <info@protesilaos.com>]

[-- Attachment #1: Type: text/plain, Size: 1768 bytes --]

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Sun, 28 Apr 2024 10:37:58 +0000
>
> Protesilaos Stavrou <info@protesilaos.com> writes:
>
>> Since we are now using labels for the HTML export, I think it makes
>> sense to optionally use those for the anchor tags as well.
>>
>> See the attached patch for a possible way of doing this.
>>
>> As always, you are welcome to make any further changes.
>
> We can indeed add such option, but is it of any practical use?
> Do you have examples of workflows when such new option will be useful?

An important purpose of using labels is sustainability. If the document
changes, the labels remain (as would CUSTOM_ID). The problem when
numbers are used in the anchor text is that if others want to make a
reference to the footnote (cite it), they will use what they see (not
the ID, which appears in the source only). And if the document changes,
their references will be broken.

Now, the problem with labels is that their are not visually appealing,
especially the longer they get. Another approach is to have a string for
the anchor text of the footnote references. Something like "[^]" with a
hover/tooltip effect, which shows the full label.

[ Of course, the hover/tooltip text can be further enhanced with CSS and
  JavaScript, but we are keeping it simple for now. Though I think that
  would ultimately be the best user experience. ]

For a proof of concept, see the attached patch, which expands on the
previous proposal.

While clicking around the footnotes, I noticed that we can also improve
the user experience by adding a CSS ":focus" state so that it is easier
to spot where we are after following an internal link. I can send this
as a separate patch/thread.

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-option-on-how-to-format-of-HTML-footnote-anchor-.patch --]
[-- Type: text/x-diff, Size: 4075 bytes --]

From c6c0aebec12ee19da6ebf7daa972af5b23119358 Mon Sep 17 00:00:00 2001
Message-Id: <c6c0aebec12ee19da6ebf7daa972af5b23119358.1714725893.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Fri, 3 May 2024 11:44:34 +0300
Subject: [PATCH] Add option on how to format of HTML footnote anchor text

* lisp/ox-html.el (org-html-footnote-anchor-text): Define new user option.
(org-html-footnote-section): Use the new option for the footnote definitions.
(org-html-footnote-reference): Use the new option for the footnote references.
---
 lisp/ox-html.el | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index b35a31865..bbad21a7b 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -766,6 +766,25 @@ (defcustom org-html-prefer-user-labels nil
   :type 'boolean
   :safe #'booleanp)
 
+(defcustom org-html-footnote-anchor-text nil
+  "Choose how to format HTML footnotes.
+
+When the value is nil, automatically number footnotes and use the number
+for the anchor text in both references and definitions.
+
+When the value is non-nil, use the footnote label as the anchor text for
+both the references and definitions.
+
+When the value is a string, use it for the anchor text of references.
+For the anchor text of definitions use either the label, if present, or
+an automatically assigned number."
+  :group 'org-export-html
+  :version "30.1"
+  :package-version '(Org . "9.7")
+  :type '(choice (const :tag "Do not show labels in HTML anchor text; use numbers" nil)
+                 (const :tag "Use labels in HTML anchor text for both references and definitions" t)
+                 (string :tag "Use custom string for HTML anchor text for references and labels for definitions")))
+
 ;;;; Inlinetasks
 
 (defcustom org-html-format-inlinetask-function
@@ -1898,7 +1917,12 @@ (defun org-html-footnote-section (info)
 				 #'identity nil t)))
 		   (anchor (org-html--anchor
                             (format "fn.%s" (or label n))
-			    n
+                            (cond
+                             ((and org-html-footnote-anchor-text label)
+                              label)
+                             ((and org-html-footnote-anchor-text (null label))
+                              (user-error "All footnotes must have labels for `org-html-footnote-anchor-text' to work"))
+                             (t n))
 			    (format " class=\"footnum\" href=\"#fnr.%s\" role=\"doc-backlink\"" (or label n))
 			    info))
 		   (contents (org-trim (org-export-data def info))))
@@ -2757,6 +2781,7 @@ (defun org-html-footnote-reference (footnote-reference _contents info)
                           (equal label (number-to-string (string-to-number label))))
                           nil
                    label))
+          (anchor-is-string (stringp org-html-footnote-anchor-text))
 	  (id (format "fnr.%s%s"
 		      (or label n)
 		      (if (org-export-footnote-first-reference-p
@@ -2774,7 +2799,21 @@ (defun org-html-footnote-reference (footnote-reference _contents info)
      (format
       (plist-get info :html-footnote-format)
       (org-html--anchor
-       id n (format " class=\"footref\" href=\"#fn.%s\" role=\"doc-backlink\"" (or label n)) info)))))
+       id
+       (cond
+        ((string-blank-p org-html-footnote-anchor-text)
+         (user-error "`org-html-footnote-anchor-text' cannot be an empty string"))
+        (anchor-is-string
+         org-html-footnote-anchor-text)
+        ((and org-html-footnote-anchor-text label)
+         label)
+        ((and org-html-footnote-anchor-text (null label))
+         (user-error "All footnotes must have labels for `org-html-footnote-anchor-text' to work"))
+        (t n))
+       (if (and anchor-is-string label)
+           (format " class=\"footref\" href=\"#fn.%s\" title=\"%s\" role=\"doc-backlink\"" label label)
+         (format " class=\"footref\" href=\"#fn.%s\" role=\"doc-backlink\"" (or label n)))
+       info)))))
 
 ;;;; Headline
 
-- 
2.39.2