[FR] stable literal hrefs in HTML export of direct links and usage of link description instead of numbered links in case of shortend link syntax

[FR] stable literal hrefs in HTML export of direct links and usage of link description instead of numbered links in case of shortend link syntax

[Gregor Zattler]

Dear org-mode developers, this is
a twofold feature request:

I write a piece documentation with a
glossary in form of a description list
and want to able to link to the
descriptions.  The thing is then
exported to HTML.

The only way to do that I found was with
direct links, but this

1. does not allow for stable hrefs
2. and numbers the link text if the
   abbreviated org link syntax [[link]]
   is used:


This

  An Emacs [[frame]] may be
  opened...

  - <<frame>> frame :: This is ancient
    terminology...


This renders into (among other things):

<div id="content" class="content">
<p>
An Emacs <a href="#orgc6125eb">1</a> may be
opened&#x2026;
</p>

<dl class="org-dl">
<dt><a id="orgc6125eb"></a> frame</dt><dd>This is ancient
terminology&#x2026;</dd>
</dl>
</div>


Since in the org-mode document the
author has to care for the
unambiguousness of the link anyway I
would expect:

1. that instead of a random id the link
   description is used as a href and
   therefore be stable between different
   exports, and
2. the link description is used instead
   of a number in case of a shortened
   [[link]].


The second effect does not show up, if
[[link][link]] is used instead of
[[link]] but this  is tedious to type
and IMHO unneccesary.

If this feature request are not / cannot
be met: Is there a workaround to at
least achive the goal of stable href
links?

Thanks for org-mode and your attention, Gregor

Re: [FR] stable literal hrefs in HTML export of direct links and usage of link description instead of numbered links in case of shortend link syntax

[Ihor Radchenko]

Gregor Zattler <telegraph@gmx.net> writes:

> The second effect does not show up, if
> [[link][link]] is used instead of
> [[link]] but this  is tedious to type
> and IMHO unneccesary.

See https://list.orgmode.org/orgmode/m2il81n2e6.fsf@me.com/
We can discuss this part of your proposal there.

-- 
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: [FR] stable literal hrefs in HTML export of direct links and usage of link description instead of numbered links in case of shortend link syntax

[Ihor Radchenko]

Gregor Zattler <telegraph@gmx.net> writes:

> I write a piece documentation with a
> glossary in form of a description list
> and want to able to link to the
> descriptions.  The thing is then
> exported to HTML.
>
> The only way to do that I found was with
> direct links, but this
>
> 1. does not allow for stable hrefs
>
> This
>
>   An Emacs [[frame]] may be
>   opened...
>
>   - <<frame>> frame :: This is ancient
>     terminology...
>
>
> This renders into (among other things):
>
> <div id="content" class="content">
> <p>
> An Emacs <a href="#orgc6125eb">1</a> may be
> opened&#x2026;
> </p>
>
> <dl class="org-dl">
> <dt><a id="orgc6125eb"></a> frame</dt><dd>This is ancient
> terminology&#x2026;</dd>
> </dl>
> </div>

You can customize `org-html-prefer-user-labels' to suppress
automatically generated IDs in your scenario.

> 1. that instead of a random id the link
>    description is used as a href and
>    therefore be stable between different
>    exports, and

A more general question is whether we can default references to targets
in HTML export to use the target value.

I think that the answer for such a default is a no - IDs in HTML cannot
contain spaces, while Org mode targets can have spaces inside. Moreover,
in HTML4 spec, IDs are limited to latin characters, while Org mode
documents may not be latin-only.

Of course, we might also go into previously discussed idea to generate
valid IDs based on the text (we usually talk about it in the context of
headline IDs), but that will simply be a repetition of the previous
threads like
https://list.orgmode.org/orgmode/87wnrhl7z7.fsf@catern.com/
https://list.orgmode.org/orgmode/CAJcAo8tXVW39h18FUXLtwoDYNKQsFHqCp+YDiyWfLee29B1PRw@mail.gmail.com/

-- 
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: [FR] stable literal hrefs in HTML export of direct links and usage of link description instead of numbered links in case of shortend link syntax

[Gregor Zattler]

Hi Ihor,
* Ihor Radchenko <yantar92@posteo.net> [2024-08-21; 16:51 GMT]:
> Gregor Zattler <telegraph@gmx.net> writes:
>> I write a piece documentation with a
>> glossary in form of a description list
>> and want to able to link to the
>> descriptions.  The thing is then
>> exported to HTML.
>>
>> The only way to do that I found was with
>> direct links, but this
>>
>> 1. does not allow for stable hrefs
[...]
> You can customize `org-html-prefer-user-labels' to suppress
> automatically generated IDs in your scenario.

thanks, that helps.

>> 1. that instead of a random id the link
>>    description is used as a href and
>>    therefore be stable between different
>>    exports, and
[...]
> Of course, we might also go into previously discussed idea to generate
> valid IDs based on the text (we usually talk about it in the context of
> headline IDs), but that will simply be a repetition of the previous
> threads like
> https://list.orgmode.org/orgmode/87wnrhl7z7.fsf@catern.com/
> https://list.orgmode.org/orgmode/CAJcAo8tXVW39h18FUXLtwoDYNKQsFHqCp+YDiyWfLee29B1PRw@mail.gmail.com/

thanks, interesting read, mostly above
my level of knowledge, but FWIW I agree with
your proposal
https://yhetil.org/87fsfutwin.fsf@localhost
to generate links from
(washed/sanitized) text plus additional
randomization added.

Regards, Gregor