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

[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]

Dear maintainer,

I have an Org file with contents like the following:

    This is a test 1 [fn:n24aa:These are the contents] and here is more.

When I do an HTML export, the footnote's label (n24aa) is not preserved
in the exported HTML. Is this intended behaviour? I was expecting it to
keep the label as a user-defined unique identifier.

I looked into the ox.el and noticed that the export data does include
the labels. But 'org-html-footnote-reference' does not have a call to
get the label: it assigns a number outright. To experiment with
retrieving the data, I tried this:

    ;; PROOF-OF-CONCEPT that works for footnote references but not
    ;; footnote definitions
    (defun org-export-get-footnote-label (footnote)
      (org-element-property :label footnote))

    (defun org-html-footnote-reference (footnote-reference _contents info)
      "Transcode a FOOTNOTE-REFERENCE element from Org to HTML.
    CONTENTS is nil.  INFO is a plist holding contextual information."
      (concat
       ;; Insert separator between two footnotes in a row.
       (let ((prev (org-export-get-previous-element footnote-reference info)))
         (when (eq (org-element-type prev) 'footnote-reference)
           (plist-get info :html-footnote-separator)))
       (let* ((n (or
                  (org-export-get-footnote-label footnote-reference)
                  (org-export-get-footnote-number footnote-reference info)))
              (id (format "fnr.%s%s"
                          n
                          (if (org-export-footnote-first-reference-p
                               footnote-reference info)
                              ""
                            ".100"))))
         (format
          (plist-get info :html-footnote-format)
          (org-html--anchor
           id n (format " class=\"footref\" href=\"#fn.%s\" role=\"doc-backlink\"" n) info)))))

Can we have footnotes with their label preserved? Or maybe is this going
to break a lot of functionality? I am aware the above not work for
footnote definitions, as those also get the number.

I am happy to keep studying the export infrastructure if you give me
some pointers.

Thank you for your time and for maintaining this wonderful project!

All the best,
Protesilaos (or simply "Prot")

* *  *

Emacs  : GNU Emacs 30.0.50 (build 3, x86_64-pc-linux-gnu, GTK+ Version 3.24.38, cairo version 1.16.0)
 of 2024-04-03
Package: Org mode version 9.6.15 (release_9.6.15 @ /usr/local/share/emacs/30.0.50/lisp/org/)

-- 
Protesilaos Stavrou
https://protesilaos.com

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/)]

[Ihor Radchenko]

Protesilaos Stavrou <info@protesilaos.com> writes:

> I have an Org file with contents like the following:
>
>     This is a test 1 [fn:n24aa:These are the contents] and here is more.
>
> When I do an HTML export, the footnote's label (n24aa) is not preserved
> in the exported HTML. Is this intended behaviour? I was expecting it to
> keep the label as a user-defined unique identifier.

Yes, this is indented behaviour, AFAIU.

> I looked into the ox.el and noticed that the export data does include
> the labels. But 'org-html-footnote-reference' does not have a call to
> get the label: it assigns a number outright. To experiment with
> retrieving the data, I tried this:
> ...
>        (let* ((n (or
>                   (org-export-get-footnote-label footnote-reference)
>                   (org-export-get-footnote-number footnote-reference info)))
> ...
> Can we have footnotes with their label preserved? Or maybe is this going
> to break a lot of functionality? I am aware the above not work for
> footnote definitions, as those also get the number.

The problem arises when only some footnotes have a label:

    This is a test 1 [fn:n24aa:These are the contents] and here is more[fn::another one].

What to do with the unlabelled ones? Assign a number? If yes, what kind
of number? `org-export-get-footnote-number' counts all the footnotes,
including labelled ones; so that returned number will be 2 in the above
example, leading to awkward ^n24aa followed by ^2 footnote.
But even without `org-export-get-footnote-number', ^n24aa ^1 mixture
might be awkward.

One way could be only using footnote labels when _all_ the footnotes
are labelled.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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]

Thank you Ihor for looking into this!

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Fri,  5 Apr 2024 14:33:49 +0000

> [... 13 lines elided]

>> I looked into the ox.el and noticed that the export data does include
>> the labels. But 'org-html-footnote-reference' does not have a call to
>> get the label: it assigns a number outright. To experiment with
>> retrieving the data, I tried this:
>> ...
>>        (let* ((n (or
>>                   (org-export-get-footnote-label footnote-reference)
>>                   (org-export-get-footnote-number footnote-reference info)))
>> ...
>> Can we have footnotes with their label preserved? Or maybe is this going
>> to break a lot of functionality? I am aware the above not work for
>> footnote definitions, as those also get the number.
>
> The problem arises when only some footnotes have a label:
>
>     This is a test 1 [fn:n24aa:These are the contents] and here is more[fn::another one].
>
> What to do with the unlabelled ones? Assign a number? If yes, what kind
> of number? `org-export-get-footnote-number' counts all the footnotes,
> including labelled ones; so that returned number will be 2 in the above
> example, leading to awkward ^n24aa followed by ^2 footnote.
> But even without `org-export-get-footnote-number', ^n24aa ^1 mixture
> might be awkward.
>
> One way could be only using footnote labels when _all_ the footnotes
> are labelled.

I think it is fine to have an all or nothing approach, if this is easier
to do.

Though I should have clarified my intent earlier: the idea is to use the
label as a fixed reference to the footnote, so that the link does not
change between exports. This is the same principle as what we do with
links to headings that have a CUSTOM_ID.

As such, the anchor text can still be the way it is now as an
automatically generated number sequence (^1, ^2, etc.), but the HTML
"id" and "href" values will be constructed based on the label of the
footnote, NOT its number in the sequence.

What do you think?

Thank you again for your time and efforts!

-- 
Protesilaos Stavrou
https://protesilaos.com

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/)]

[Ihor Radchenko]

Protesilaos Stavrou <info@protesilaos.com> writes:

> Though I should have clarified my intent earlier: the idea is to use the
> label as a fixed reference to the footnote, so that the link does not
> change between exports. This is the same principle as what we do with
> links to headings that have a CUSTOM_ID.
>
> As such, the anchor text can still be the way it is now as an
> automatically generated number sequence (^1, ^2, etc.), but the HTML
> "id" and "href" values will be constructed based on the label of the
> footnote, NOT its number in the sequence.
>
> What do you think?

That may work. One may simply change the anchors for footnote references
and footnotes when they are labeled. However, we should be careful when
labels are duplicated (multiple references to the same named footnote) -
only a single back-reference is possible from the footnote definition
back to footnote reference.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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]

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Wed, 10 Apr 2024 14:31:22 +0000
>
> Protesilaos Stavrou <info@protesilaos.com> writes:
>
>> Though I should have clarified my intent earlier: the idea is to use the
>> label as a fixed reference to the footnote, so that the link does not
>> change between exports. This is the same principle as what we do with
>> links to headings that have a CUSTOM_ID.
>>
>> As such, the anchor text can still be the way it is now as an
>> automatically generated number sequence (^1, ^2, etc.), but the HTML
>> "id" and "href" values will be constructed based on the label of the
>> footnote, NOT its number in the sequence.
>>
>> What do you think?
>
> That may work. One may simply change the anchors for footnote references
> and footnotes when they are labeled. However, we should be careful when
> labels are duplicated (multiple references to the same named footnote) -
> only a single back-reference is possible from the footnote definition
> back to footnote reference.

I think the issue of labelling the footnotes is separate from
disambiguating them and avoiding duplicates. Of course, having the
latter is nice. But the part about the labels should be limited to the
use of the data we already have to keep the patch/change small (maybe
subject to an opt-in user option to not disrupt any existing workflow).

With regard to the disambiguation scheme, I am playing around with
various scenaria to see how Org HTML export behaves. Using the
following:

    * Heading

    This is test 1 [fn:hello]
    This is test 2 [fn:hello]
    This is another test [fn:1]
    This is test 3 [fn:hello]

    * Footnotes

    [fn:1]
    [fn:hello] Hello 

We get this excerpt from the HTML output:

    This is test 1 <sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
    This is test 2 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
    This is another test <sup><a id="fnr.2" class="footref" href="#fn.2" role="doc-backlink">2</a></sup>
    This is test 3 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>

Notice that the 100 in the ID is not incremented further. I guess this
is something that can be worked on but, again, I think it is separate
from the issue of using the label for the ID and HREF.

Any thoughts?

-- 
Protesilaos Stavrou
https://protesilaos.com

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/)]

[Ihor Radchenko]

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

Protesilaos Stavrou <info@protesilaos.com> writes:

> With regard to the disambiguation scheme, I am playing around with
> various scenaria to see how Org HTML export behaves. Using the
> following:
> ...
>     This is test 2 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
> ...
>     This is test 3 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
>
> Notice that the 100 in the ID is not incremented further. I guess this
> is something that can be worked on but, again, I think it is separate
> from the issue of using the label for the ID and HREF.
>
> Any thoughts?

Duplicate IDs are against HTML spec:
https://softwareengineering.stackexchange.com/questions/127178/two-html-elements-with-same-id-attribute-how-bad-is-it-really

So, this is a bug.

>>> Though I should have clarified my intent earlier: the idea is to use the
>>> label as a fixed reference to the footnote, so that the link does not
>>> change between exports. This is the same principle as what we do with
>>> links to headings that have a CUSTOM_ID.
>>>
>>> As such, the anchor text can still be the way it is now as an
>>> automatically generated number sequence (^1, ^2, etc.), but the HTML
>>> "id" and "href" values will be constructed based on the label of the
>>> footnote, NOT its number in the sequence.

See the attached tentative patch.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-html-Use-non-number-footnote-names-as-link-anchor.patch --]
[-- Type: text/x-patch, Size: 5823 bytes --]

From 446bfc8c8afb5b2e09d0e0acf7b136b9f0780f5a Mon Sep 17 00:00:00 2001
Message-ID: <446bfc8c8afb5b2e09d0e0acf7b136b9f0780f5a.1713016519.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sat, 13 Apr 2024 16:53:48 +0300
Subject: [PATCH] ox-html: Use non-number footnote names as link anchors

* lisp/ox-html.el (org-html-footnote-section):
* lisp/ox-html.el (org-html-footnote-reference): When footnote has a
non-number name, build link anchors using this name.
* etc/ORG-NEWS (=ox-html=: When exporting footnotes with custom
non-number names, the names are used as link anchors): Announce the
change.

Link: https://orgmode.org/list/875xwngiwx.fsf@protesilaos.com
---
 etc/ORG-NEWS    |  8 +++++
 lisp/ox-html.el | 77 +++++++++++++++++++++++++++++--------------------
 2 files changed, 53 insertions(+), 32 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index e61bd6988..1b7040815 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -13,6 +13,14 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
 
 * Version 9.7 (not released yet)
 ** Important announcements and breaking changes
+*** =ox-html=: When exporting footnotes with custom non-number names, the names are used as link anchors
+
+Previously, link anchors for footnote references and footnote
+definitions were based on the footnote number: =fn.1=, =fnr.15=, etc.
+
+Now, when the footnote has a non-number name, it is used as an anchor:
+=fn.name=, =fnr.name=.
+
 *** Underline syntax now takes priority over subscript when both are applicable
 
 Previously, Org mode interpreted =(_text_)= as subscript.
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 0471a573b..1262da1aa 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -1873,36 +1873,42 @@ (defun org-html-footnote-section (info)
   (pcase (org-export-collect-footnote-definitions info)
     (`nil nil)
     (definitions
+     (format
+      (plist-get info :html-footnotes-section)
+      (org-html--translate "Footnotes" info)
       (format
-       (plist-get info :html-footnotes-section)
-       (org-html--translate "Footnotes" info)
-       (format
-	"\n%s\n"
-	(mapconcat
-	 (lambda (definition)
-	   (pcase definition
-	     (`(,n ,_ ,def)
-	      ;; `org-export-collect-footnote-definitions' can return
-	      ;; two kinds of footnote definitions: inline and blocks.
-	      ;; Since this should not make any difference in the HTML
-	      ;; output, we wrap the inline definitions within
-	      ;; a "footpara" class paragraph.
-	      (let ((inline? (not (org-element-map def org-element-all-elements
-				    #'identity nil t)))
-		    (anchor (org-html--anchor
-			     (format "fn.%d" n)
-			     n
-			     (format " class=\"footnum\" href=\"#fnr.%d\" role=\"doc-backlink\"" n)
-			     info))
-		    (contents (org-trim (org-export-data def info))))
-		(format "<div class=\"footdef\">%s %s</div>\n"
-			(format (plist-get info :html-footnote-format) anchor)
-			(format "<div class=\"footpara\" role=\"doc-footnote\">%s</div>"
-				(if (not inline?) contents
-				  (format "<p class=\"footpara\">%s</p>"
-					  contents))))))))
-	 definitions
-	 "\n"))))))
+       "\n%s\n"
+       (mapconcat
+	(lambda (definition)
+	  (pcase definition
+	    (`(,n ,label ,def)
+             ;; Do not assign number labels as they appear in Org mode
+             ;; - the footnotes are re-numbered by
+             ;; `org-export-get-footnote-number'.  If the label is not
+             ;; a number, keep it.
+             (when (equal label (number-to-string (string-to-number label)))
+               (setq label nil))
+	     ;; `org-export-collect-footnote-definitions' can return
+	     ;; two kinds of footnote definitions: inline and blocks.
+	     ;; Since this should not make any difference in the HTML
+	     ;; output, we wrap the inline definitions within
+	     ;; a "footpara" class paragraph.
+	     (let ((inline? (not (org-element-map def org-element-all-elements
+				 #'identity nil t)))
+		   (anchor (org-html--anchor
+			    (format "fn.%d" n)
+			    n
+			    (format " class=\"footnum\" href=\"#fnr.%s\" role=\"doc-backlink\"" (or label n))
+			    info))
+		   (contents (org-trim (org-export-data def info))))
+	       (format "<div class=\"footdef\">%s %s</div>\n"
+		       (format (plist-get info :html-footnote-format) anchor)
+		       (format "<div class=\"footpara\" role=\"doc-footnote\">%s</div>"
+			       (if (not inline?) contents
+				 (format "<p class=\"footpara\">%s</p>"
+					 contents))))))))
+	definitions
+	"\n"))))))
 
 \f
 ;;; Template
@@ -2736,8 +2742,15 @@ (defun org-html-footnote-reference (footnote-reference _contents info)
      (when (org-element-type-p prev 'footnote-reference)
        (plist-get info :html-footnote-separator)))
    (let* ((n (org-export-get-footnote-number footnote-reference info))
-	  (id (format "fnr.%d%s"
-		      n
+          (label (org-element-property :label footnote-reference))
+          ;; Do not assign number labels as they appear in Org mode -
+          ;; the footnotes are re-numbered by
+          ;; `org-export-get-footnote-number'.  If the label is not a
+          ;; number, keep it.
+          (label (if (equal label (number-to-string (string-to-number label)))
+                     nil label))
+	  (id (format "fnr.%s%s"
+		      (or label n)
 		      (if (org-export-footnote-first-reference-p
 			   footnote-reference info)
 			  ""
@@ -2745,7 +2758,7 @@ (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.%d\" role=\"doc-backlink\"" n) info)))))
+       id n (format " class=\"footref\" href=\"#fn.%s\" role=\"doc-backlink\"" (or label n)) info)))))
 
 ;;;; Headline
 
-- 
2.44.0


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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]

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

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Sat, 13 Apr 2024 14:00:48 +0000
>
> Protesilaos Stavrou <info@protesilaos.com> writes:
>
>> With regard to the disambiguation scheme, I am playing around with
>> various scenaria to see how Org HTML export behaves. Using the
>> following:
>> ...
>>     This is test 2 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
>> ...
>>     This is test 3 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
>>
>> Notice that the 100 in the ID is not incremented further. I guess this
>> is something that can be worked on but, again, I think it is separate
>> from the issue of using the label for the ID and HREF.
>>
>> Any thoughts?
>
> Duplicate IDs are against HTML spec:
> https://softwareengineering.stackexchange.com/questions/127178/two-html-elements-with-same-id-attribute-how-bad-is-it-really
>
> So, this is a bug.

Indeed! We can look into this separately.

>>>> Though I should have clarified my intent earlier: the idea is to use the
>>>> label as a fixed reference to the footnote, so that the link does not
>>>> change between exports. This is the same principle as what we do with
>>>> links to headings that have a CUSTOM_ID.
>>>>
>>>> As such, the anchor text can still be the way it is now as an
>>>> automatically generated number sequence (^1, ^2, etc.), but the HTML
>>>> "id" and "href" values will be constructed based on the label of the
>>>> footnote, NOT its number in the sequence.
>
> See the attached tentative patch.

> [... 144 lines elided]

Thank you! I just tried it. I encountered two problems with it, which I
am addressing with the two attached patches (feel free to modify as
needed). In short:

1. The footnote definitions at the bottom of the file were still using
the ordinal HTML id, which did not correspond to the href with the
label.

2. If the file had a mixture of labeled and anonymous/unlabeled
footnotes, then the export would break as it would be passing a nil
value to 'string-to-number'.

Please let me know how to proceed.

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Use-the-label-if-present-in-footnote-definition.patch --]
[-- Type: text/x-diff, Size: 1056 bytes --]

From 0fb81645aafb780116465e13758601ff1183e043 Mon Sep 17 00:00:00 2001
Message-Id: <0fb81645aafb780116465e13758601ff1183e043.1714117826.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Fri, 26 Apr 2024 10:41:51 +0300
Subject: [PATCH 1/2] Use the label, if present, in footnote definition

* lisp/ox-html.el (org-html-footnote-section): Account for a non-nil
  label value.
---
 lisp/ox-html.el | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index aa0f891..95ecb44 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -1896,7 +1896,9 @@ (defun org-html-footnote-section (info)
 	     (let ((inline? (not (org-element-map def org-element-all-elements
 				 #'identity nil t)))
 		   (anchor (org-html--anchor
-			    (format "fn.%d" n)
+                            (if label
+			        (format "fn.%s" label)
+			      (format "fn.%d" n))
 			    n
 			    (format " class=\"footnum\" href=\"#fnr.%s\" role=\"doc-backlink\"" (or label n))
 			    info))
-- 
2.39.2


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-Guard-against-nil-label-value-for-footnotes.patch --]
[-- Type: text/x-diff, Size: 2191 bytes --]

From 112c5671e5f55ea1d9e5e9fb6dd647e6a739c9ac Mon Sep 17 00:00:00 2001
Message-Id: <112c5671e5f55ea1d9e5e9fb6dd647e6a739c9ac.1714117826.git.info@protesilaos.com>
In-Reply-To: <0fb81645aafb780116465e13758601ff1183e043.1714117826.git.info@protesilaos.com>
References: <0fb81645aafb780116465e13758601ff1183e043.1714117826.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Fri, 26 Apr 2024 10:49:26 +0300
Subject: [PATCH 2/2] Guard against nil label value for footnotes

* lisp/ox-html.el (org-html-footnote-section)
(org-html-footnote-reference): Check if label is a string before
passing it to 'string-to-number'.

This fixes the case where we are exporting some footnotes with a label
and some without a label.
---
 lisp/ox-html.el | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 95ecb44..0237e61 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -1886,7 +1886,8 @@ (defun org-html-footnote-section (info)
              ;; - the footnotes are re-numbered by
              ;; `org-export-get-footnote-number'.  If the label is not
              ;; a number, keep it.
-             (when (equal label (number-to-string (string-to-number label)))
+             (when (and (stringp label)
+                        (equal label (number-to-string (string-to-number label))))
                (setq label nil))
 	     ;; `org-export-collect-footnote-definitions' can return
 	     ;; two kinds of footnote definitions: inline and blocks.
@@ -2754,8 +2755,10 @@ (defun org-html-footnote-reference (footnote-reference _contents info)
           ;; the footnotes are re-numbered by
           ;; `org-export-get-footnote-number'.  If the label is not a
           ;; number, keep it.
-          (label (if (equal label (number-to-string (string-to-number label)))
-                     nil label))
+          (label (if (and (stringp label)
+                          (equal label (number-to-string (string-to-number label))))
+                          nil
+                   label))
 	  (id (format "fnr.%s%s"
 		      (or label n)
 		      (if (org-export-footnote-first-reference-p
-- 
2.39.2

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]

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

Hello again!

A follow-up on the patches below:

> From: Protesilaos Stavrou <info@protesilaos.com>
> Date: Fri, 26 Apr 2024 10:55:50 +0300

> [... 41 lines elided]

> Thank you! I just tried it. I encountered two problems with it, which I
> am addressing with the two attached patches (feel free to modify as
> needed). In short:
>
> 1. The footnote definitions at the bottom of the file were still using
> the ordinal HTML id, which did not correspond to the href with the
> label.
>
> 2. If the file had a mixture of labeled and anonymous/unlabeled
> footnotes, then the export would break as it would be passing a nil
> value to 'string-to-number'.
>
> Please let me know how to proceed.

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.

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Provide-option-to-use-footnote-label-as-the-HTML-anc.patch --]
[-- Type: text/x-diff, Size: 2314 bytes --]

From 681db0934e55ae6c2971ccfbfd9de7c0828506c9 Mon Sep 17 00:00:00 2001
Message-Id: <681db0934e55ae6c2971ccfbfd9de7c0828506c9.1714119282.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Fri, 26 Apr 2024 11:14:28 +0300
Subject: [PATCH] Provide option to use footnote label as the HTML anchor text

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

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 0237e61..804a464 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -699,6 +699,17 @@ (defcustom org-html-footnote-separator "<sup>, </sup>"
   :group 'org-export-html
   :type 'string)
 
+(defcustom org-html-footnote-use-label-for-anchor-text nil
+  "When non-nil, use the footnote label as the anchor text.
+When nil, use the number of the footnote as the anchor text.
+
+- For footnotes, this is the format: [fn:LABEL].
+- For inline footnotes, it is this: [fn:LABEL: Some text]."
+  :group 'org-export-html
+  :version "30.1"
+  :package-version '(Org . "9.7")
+  :type 'boolean)
+
 ;;;; Headline
 
 (defcustom org-html-toplevel-hlevel 2
@@ -1900,7 +1911,9 @@ (defun org-html-footnote-section (info)
                             (if label
 			        (format "fn.%s" label)
 			      (format "fn.%d" n))
-			    n
+                            (if (and org-html-footnote-use-label-for-anchor-text label)
+                                label
+                              n)
 			    (format " class=\"footnum\" href=\"#fnr.%s\" role=\"doc-backlink\"" (or label n))
 			    info))
 		   (contents (org-trim (org-export-data def info))))
@@ -2768,7 +2781,11 @@ (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
+       (if (and org-html-footnote-use-label-for-anchor-text label)
+           label
+         n)
+       (format " class=\"footref\" href=\"#fn.%s\" role=\"doc-backlink\"" (or label n)) info)))))
 
 ;;;; Headline
 
-- 
2.39.2

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/)]

[Max Nikulin]

On 26/04/2024 15:17, Protesilaos Stavrou wrote:
> 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.
[...]

> +(defcustom org-html-footnote-use-label-for-anchor-text nil

Another option may be to rely on the existing one: 
`org-html-prefer-user-labels'

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/)]

[Ihor Radchenko]

Protesilaos Stavrou <info@protesilaos.com> writes:

>> See the attached tentative patch.
>
>> [... 144 lines elided]
>
> Thank you! I just tried it. I encountered two problems with it, which I
> am addressing with the two attached patches (feel free to modify as
> needed). In short:
>
> 1. The footnote definitions at the bottom of the file were still using
> the ordinal HTML id, which did not correspond to the href with the
> label.
>
> 2. If the file had a mixture of labeled and anonymous/unlabeled
> footnotes, then the export would break as it would be passing a nil
> value to 'string-to-number'.
>
> Please let me know how to proceed.

Applied, onto main, after squashing the patches together.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=065af4b42
Handled.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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/)]

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> Protesilaos Stavrou <info@protesilaos.com> writes:
>
>> With regard to the disambiguation scheme, I am playing around with
>> various scenaria to see how Org HTML export behaves. Using the
>> following:
>> ...
>>     This is test 2 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
>> ...
>>     This is test 3 <sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
>>
>> Notice that the 100 in the ID is not incremented further. I guess this
>> is something that can be worked on but, again, I think it is separate
>> from the issue of using the label for the ID and HREF.
>>
>> Any thoughts?
>
> Duplicate IDs are against HTML spec:
> https://softwareengineering.stackexchange.com/questions/127178/two-html-elements-with-same-id-attribute-how-bad-is-it-really
>
> So, this is a bug.

Fixed, on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=e0f24a3f6

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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/)]

[Ihor Radchenko]

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?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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]

> From: Max Nikulin <manikulin@gmail.com>
> Date: Fri, 26 Apr 2024 16:53:23 +0700
>
> On 26/04/2024 15:17, Protesilaos Stavrou wrote:
>> 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.
> [...]
>
>> +(defcustom org-html-footnote-use-label-for-anchor-text nil
>
> Another option may be to rely on the existing one: 
> `org-html-prefer-user-labels'

Yes, sure. It is fine to reuse an existing user option. Though reading
through its docstring and the code, I cannot tell what this is doing
exactly. Is it applying to all HTML elements, or just headings?

On my end, I have that option set to nil, but exported headings do use
their CUSTOM_ID.

-- 
Protesilaos Stavrou
https://protesilaos.com

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]

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Sun, 28 Apr 2024 10:22:50 +0000
>
> Protesilaos Stavrou <info@protesilaos.com> writes:
>
>>> See the attached tentative patch.
>>
>>> [... 144 lines elided]
>>
>> Thank you! I just tried it. I encountered two problems with it, which I
>> am addressing with the two attached patches (feel free to modify as
>> needed). In short:
>>
>> 1. The footnote definitions at the bottom of the file were still using
>> the ordinal HTML id, which did not correspond to the href with the
>> label.
>>
>> 2. If the file had a mixture of labeled and anonymous/unlabeled
>> footnotes, then the export would break as it would be passing a nil
>> value to 'string-to-number'.
>>
>> Please let me know how to proceed.
>
> Applied, onto main, after squashing the patches together.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=065af4b42
> Handled.

Thank you!

-- 
Protesilaos Stavrou
https://protesilaos.com

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]

[-- 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

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/)]

[Max Nikulin]

On 03/05/2024 13:59, Protesilaos Stavrou wrote:
>> From: Max Nikulin Fri, 26 Apr 2024 16:53:23 +0700
>>
>> Another option may be to rely on the existing one:
>> `org-html-prefer-user-labels'
> 
> Yes, sure. It is fine to reuse an existing user option. Though reading
> through its docstring and the code, I cannot tell what this is doing
> exactly. Is it applying to all HTML elements, or just headings?
> 
> On my end, I have that option set to nil, but exported headings do use
> their CUSTOM_ID.

It seems it was broken by
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=5e9953fa0e

`user-label' is set to CUSTOM_ID when it is set, so checking the 
variable is not effective any more.

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/)]

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> Yes, sure. It is fine to reuse an existing user option. Though reading
>> through its docstring and the code, I cannot tell what this is doing
>> exactly. Is it applying to all HTML elements, or just headings?
>> 
>> On my end, I have that option set to nil, but exported headings do use
>> their CUSTOM_ID.
>
> It seems it was broken by
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=5e9953fa0e
>
> `user-label' is set to CUSTOM_ID when it is set, so checking the 
> variable is not effective any more.

Nothing is broken. CUSTOM_IDs for _headings_ were used unconditionally.

org-html-prefer-user-labels
    ...
    Independently of this variable, however, CUSTOM_ID are always
    used as a reference.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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/)]

[Ihor Radchenko]

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.
>> ...
>> 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.

Sorry, but I am not convinced.
I can make the same argument, say, for headline titles:
It is very natural to refer to a headline when referencing a document,
but when headline changes, such reference is no longer going to work.

For headline titles, it is well-known that a more reliable way is to use
#anchor in the URL. Anchors are much less likely to change compared to
headline titles.

With your previous patch, footnote anchors became more stable and people
can now reliably link to footnotes using #anchor semantics, given that
the page author took care about naming the footnotes.
I find it good enough.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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/)]

[Max Nikulin]

On 03/05/2024 18:14, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>>> Yes, sure. It is fine to reuse an existing user option. Though reading
>>> through its docstring and the code, I cannot tell what this is doing
>>> exactly. Is it applying to all HTML elements, or just headings?
>>>
>>> On my end, I have that option set to nil, but exported headings do use
>>> their CUSTOM_ID.
>>
>> It seems it was broken by
>> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=5e9953fa0e
>>
>> `user-label' is set to CUSTOM_ID when it is set, so checking the
>> variable is not effective any more.
> 
> Nothing is broken. CUSTOM_IDs for _headings_ were used unconditionally.
> 
> org-html-prefer-user-labels
>      ...
>      Independently of this variable, however, CUSTOM_ID are always
>      used as a reference.

My bad. I believed that this option is (or was) necessary to get anchor 
names as CUSTOM_ID, but I have tried Org-9.1.9 and I see elements having 
id attribute with CUSTOM_ID values.