From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Vladimir Alexiev" Subject: Meaningful & stable anchors in HTML export Date: Fri, 1 Jul 2016 13:46:06 +0300 Message-ID: <020501d1d385$c59432b0$50bc9810$@ontotext.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53200) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bIvxd-0004kr-Ed for emacs-orgmode@gnu.org; Fri, 01 Jul 2016 06:46:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bIvxZ-0006OV-Ag for emacs-orgmode@gnu.org; Fri, 01 Jul 2016 06:46:12 -0400 Received: from mail.ontotext.com ([93.123.21.89]:44164) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bIvxY-0006OO-TR for emacs-orgmode@gnu.org; Fri, 01 Jul 2016 06:46:09 -0400 Received: from localhost (localhost [127.0.0.1]) by mail.ontotext.com (Postfix) with ESMTP id 8C20A132FB6 for ; Fri, 1 Jul 2016 13:46:04 +0300 (EEST) Received: from mail.ontotext.com ([127.0.0.1]) by localhost (localhost [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id UU2p3Wr8UMDo for ; Fri, 1 Jul 2016 13:46:04 +0300 (EEST) Received: from vladimir (unknown [82.118.248.245]) by mail.ontotext.com (Postfix) with ESMTPSA id 76639132FB3 for ; Fri, 1 Jul 2016 13:46:04 +0300 (EEST) Content-Language: en-us List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: emacs-orgmode@gnu.org Consider e.g. http://vladimiralexiev.github.io/Multisensor/#sec-3-2-2, which uses an anchor made from the section number. I much prefer a readable/meaningful anchor like github does: https://github.com/VladimirAlexiev/VladimirAlexiev.github.io/tree/master/Mul tisensor#322-normalization-problems Numbered anchors are bad because they are not stable: if I move the section, the anchor will change. Github makes anchors from the heading text, which in my experience are a lot more stable. In the above case it added the section number since I have #+OPTIONS: num:t in https://raw.githubusercontent.com/VladimirAlexiev/VladimirAlexiev.github.io/ master/Multisensor/index.org. But I'm willing to give up section numbering in favor of stable anchors. In the HTML exporter (ox-html.el) version org-plus-contrib-20150803, the following are tried in succession to obtain a preferred-id: (list (org-element-property :CUSTOM_ID headline) (concat "sec-" section-number) (org-element-property :ID headline)))) The first is manually set CUSTOM_ID property, the second a numbered secton (eg "sec-3-2-2") and the third an ID that's automatically inserted by org-store-link. The newest ox-html.el (http://orgmode.org/w/?p=org-mode.git;a=blob_plain;f=lisp/ox-html.el;hb=HEAD ) uses this (list (org-element-property :CUSTOM_ID headline) (org-export-get-reference headline info) (org-element-property :ID headline)))) You see the second line is changed. It uses org-export-get-reference from ox.el, which uses org-export-new-reference, which "Generates random 7 digits hexadecimal numbers". I don't know if that is stored (which would make it stable), but it's certainly not meaningful to any reader of the HTML file. So my request is: the HTML export should have an option org-export-anchors-use-title to generate section anchors from the section title. -- There is some code https://github.com/snosov1/toc-org that embeds a TOC inside the org file, which is very useful in github (github preview itself doesn't show a TOC). toc-org generates meaningful (Github-like) links when toc-org-hrefify-default is "gh". But as described in https://github.com/snosov1/toc-org/issues/29, Github keeps the section number, and doesn't strip the TODO and statistics-cookies. So a section headline like "3.2.2 TODO Normalization Problems [3/4]" will get this anchor #322-todo-normalization-problems-34. So it's best to include further options about which parts of a headline to use: - org-export-anchors-use-section-numbers "If org-export-with-section-numbers is also enabled, prepend the section number (without any dashes). This makes your anchors ugly and less stable, but you need to set this for Github preview compatibility" - org-export-anchors-use-todo "Prepend TODO/DONE keywords, in lowercase, to section anchors. This makes your anchors ugly and less stable, but you need to set this for Github preview compatibility" - org-export-anchors-use-title "Make section anchors from the words in the section title, converting to lowercase and replacing punctuation with dash. This makes your anchors stable (title changes less frequently than numbering) and readable. Set this for Github preview compatibility" - org-export-anchors-use-statistics-cookies "Append statistic cookies (e.g. [33%] or [1/3]) to section anchor, replacing punctuation with dash. This makes your anchors ugly and less stable, but you need to set this for Github preview compatibility"