Re: stability of toc links

[TRS-80 <lists.trs-80@isnotmyreal.name>]

On 2020-12-08 20:39, Tom Gillespie wrote:
> It sounds like you are looking for the CUSTOM_ID property. See
> https://orgmode.org/manual/Handling-Links.html and
> https://orgmode.org/manual/Internal-Links.html. I don't remember
> whether there is a way to generate ids matching headlines within org
> itself, but there is
> https://github.com/alphapapa/unpackaged.el#export-to-html-with-useful-anchors.
> Best!
> Tom

I had set out to shave this particular yak just yesterday I think it
was.  I know I came across alphapapa's solution and maybe TEC's too, but
they were more complex than I could seem to get my feeble brain around
at the time.

Also, I was going for more of a deterministic result, trying to end up
with something like a Markdown style link id.  This coming up in the
course of my larger mission towards better support for exporting
README.org to Markdown (and ultimately, nicely rendered HTML) files over
at Sourcehut[0].

Finally, this operates by a totally different way than replacing some
part of Org export function(s).  My approach was simply to dynamically
assign a CUSTOM_ID property to every heading in current buffer (that did
not have one already) which would be generated according to some
deterministic method.  With the idea to then go on after that and do
whatever regular Org export you want.

Right off the bat I will say this is a very, VERY immature
implementation (literally yesterday).  And I have only done the very
lightest of testing (however it does basically work).  Therefore this is
not for consideration for inclusion into Orgmode but rather just my own
workaround in the meantime.  At best I might hope to add something
useful to the ongoing discussion (or perhaps become enlightened why this
is completely wrong approach).  ;)

I would like to point out the following problems which I have not (yet)
addressed in the following functions (#1 being most glaring probably) as
they are still too new:

1. The punctuation removal regexp needs to have many more characters
added (currently only containing {!.'}).  In fact, this strikes me as a
bit hacky, I am not even sure it's the best approach.

2. This function operates only on the current buffer.

3. Many things still need to be parameterized, in particular the TODO
state is hard coded to be included in the generated id and already I am
starting to think that's a bad idea (but it depends on context I
suppose, hence thinking to make it an option).

4. If I am trying to emulate Markdown (or any other spec) I really
should study and more properly and fully implement said spec.  I have
done /absolutely no such thing/ so far, only a (quite off the cuff)
"Markdown like" implementation.

5. Naming the function beginning with `my-ox-' is not meant that this
should be included in ox- package necessarily but rather that I am
associating it with exporting from Org within my own mind and personal
init files.

My plan (before stumbling across this thread ;) ) was to continue to use
and polish these functions (privately) and eventually publish them on my
(relatively new) sr.ht profile[1].  But since this came up, I guess I
will go ahead and put it out there for feedback here on the mailing
list.  I still plan to eventually publish somewhere more properly with
license, where patches can be accepted, etc...  However in the
meantime...

With the above disclaimers out of the way, I present the following
function (and another simple one it depends on) in the hope they are
useful to someone.

[0] https://sourcehut.org
[1] https://sr.ht/~trs-80/

#+begin_src emacs-lisp

(defun my-major-mode-insure (mode)
   "If we are not in MAJOR-MODE, exit with error."
   (unless (string= major-mode mode)
     (user-error "Buffer not in %s, exiting" mode)))

(defun my-ox-assign-custom-ids ()
   "Assign reliable CUSTOM_ID to each heading in current buffer.

CUSTOM_ID will only be assigned if one does not exist already.

The generated CUSTOM_ID roughly[0] follows (my very basic and
limited understanding of) the Markdown spec.  In other words, it
will be generated by taking the heading text plus TODO state (so
as not to break link) and:

1. Lower case it.
2. Remove all punctuation.[1]
3. Replace spaces with hyphens.

[0] Currently, likely VERY roughly...

[1] Currently this is a bit hacky `replace-regexp-in-string'
featuring only a few common punctuation (right now only
exclamation point, period, apostrophe (i.e., single quote).  Much
more will need to be added here, in fact I am not even sure this
is the best approach."
   (interactive)
   (my-major-mode-insure 'org-mode)
   (org-map-entries '(org-set-property
		     "CUSTOM_ID"
		     ;; replace space with hyphen
		     (replace-regexp-in-string
		      " " "-"
		      ;; remove punctuation
		      (replace-regexp-in-string
		       "\\\!\\|\\\.\\|'" ""
		       (downcase
			(substring-no-properties
			 (org-get-heading t nil t t))))))
		   nil
		   'file
		   ;; skip function
		   (lambda ()
		     (when (org-entry-get nil "CUSTOM_ID")
		       (point)))))

#+end_src