Improving ox-hugo exported Org "info:" links

After writing my previous post, I had shared its link on the Org mode mailing list  For folks who don’t know, you can email the Org mode mailing list (emacs-orgmode@gnu.org) about pretty much anything Org mode related: any help you want, a bug you want to report, a patch you want to submit, or just share your positive or negative experiences with Org mode or thank someone for their awesome work. here, and received some helpful feedback from Max Nikulin.

This post is a response to his feedback, and it also describes a few improvements made for info: link exports in ox-hugo based on that.

💪¹ 1: Exported links now point to separate pages in the manual #

Feedback

  For <info:emacs#Browse-URL> export to html produces the following link:
      https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Browse_002dURL
  I think, a better variant is
      https://www.gnu.org/software/emacs/manual/html_node/emacs/Browse_002dURL.html
  even though for the Org manual I often prefer single-page HTML version.

I really liked this suggestion!

• Earlier, the Info node references were exporting to an anchor on a huge single-page HTML manual e.g. emacs.html#Browse_002dURL
• After implementing this fix, the exported link points to a separate HTML page for that node e.g. emacs/Browse_002dURL.html.

Now, [[info:emacs#Screen]] exports and renders to Emacs Info: Screen, and a Top level node like [[info:emacs#Top]] exports and renders to Emacs Info.

For consistency, all info: links will now be exported to URLs pointing to the separate node HTML pages, even for Org manual links.

💪 2: Export Org manual links to orgmode.org URLs #

Feedback

(About an example info: link pointing to Org manual: [[info:org#Top]])

And the link target ideally should be https://orgmode.org/manual/index.html

This was another great suggestion!

By default, the Org manual info: links will export to URLs pointing to the Org manual shipped with Emacs. That manual will be associated with the Org mode version that shipped with the last stable version of Emacs. So depending on how long it has been since the last Emacs release, you could be referring to quite an older version of the Org manual.

If you install Org from GNU Elpa, you can get an update of the latest stable Org version every week !  There’s a related post on Org mode’s Release Flow that might interest you. And the manual hosted on https://orgmode.org gets updated every week as well. I would like to always refer to the latest Org manual with the latest fixes and documentation improvements, and so I agree with Max’s suggestion above.

Now [[info:org#Top]] exports and renders as Org Info and the Org manual nodes like [[info:org#Working with Source Code]] also export as a link to a page in that manual: Org Info: Working with Source Code.

💪 3: Link hover text shows the elisp code for accessing the Info node #

Feedback

  I would prefer
      info "(org) Top"
  to
      Org Info: Top
  since the former may be pasted to M-x : or to shell command prompt.

I wanted the link descriptions in the exported markdown to be more “English” and understandable to people not familiar with the Emacs Info interface. So I decided to keep this mostly unchanged ..

I did not change the link description, but I did add a new HTML title attribute to the link. This attribute contains the Emacs Lisp code needed to access the Info manual from Emacs. The user will see the text from this attribute when they hover the mouse over the links. If you haven’t already discovered this feature, try hovering the mouse over that last link above and you should see this 😃 :

Of course, the user will still not be able to copy that text and paste in Emacs. But it will still provide them enough hint on how to access Info nodes in Emacs.

Final code in ox-hugo that exports the info: links #

Here’s the version of the org-hugo--org-info-export function that handles the exports of info: links as of today (<2022-04-15 Fri>):

888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912

(defun org-hugo--org-info-export (path desc format)
  "Add support for exporting [[info:..]] links for `hugo' format."
  (let* ((parts (split-string path "#\\|::"))
         (manual (car parts))
         (node (or (nth 1 parts) "Top"))
         (title (format "Emacs Lisp: (info \\\"(%s) %s\\\")" manual node))
         (desc (or desc
                   (if (string= node "Top")
                       (format "%s Info" (capitalize manual))
                     (format "%s Info: %s" (capitalize manual) node))))
         ;; `link' below is mostly derived from the code in
         ;; `org-info-map-html-url'.
         (link (cond ((member manual org-info-emacs-documents)
                      (let ((manual-url (if (string= (downcase manual) "org")
                                            "https://orgmode.org/manual"
                                          (format "https://www.gnu.org/software/emacs/manual/html_node/%s" manual)))
                            (node-url (if (string= node "Top")
                                          "index.html"
                                        (concat (org-info--expand-node-name node) ".html"))))
                        (format "%s/%s" manual-url node-url)))
                     ((cdr (assoc manual org-info-other-documents)))
                     (t
                      (concat manual ".html")))))
    (when (member format '(md hugo))
      (format "[%s](%s \"%s\")" desc link title))))

Link to code in the repo

I will leave it as an exercise for the reader to map the lines in above code snippet to the features described in this post 🍀.