Texinfo: Custom navigation and links in headings

["Rudolf Adamkovič" <rudolf@adamkovic.org>]

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

Howdy!

I would like to contribute two patches for the Texinfo exporter:

1. Custom, or disabled, Texinfo navigation.

   This enables the user to, e.g.
   
   - put a top-level tree to a wider "Up" context, or
   - hide "Next" and "Previous" for a group of unrelated headings, or
   - build deeper hierarchies if needed.

2. Links in Texinfo section names.

   Importantly, this also applies to

     sub-`h:' headings,

   which are exported as plain lists.
   
   (Note: Links are a bit buggy on the Texinfo side, but that is not an
   Org issue; they are supported, and I find them useful.)
   
Thank you.

Rudy


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-texinfo-Add-support-for-custom-navigation-hierarc.patch --]
[-- Type: text/x-patch, Size: 8523 bytes --]

From 1c4fc3979ea26ca93742b16d9c135ec62a8b4d0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <rudolf@adamkovic.org>
Date: Thu, 22 Aug 2024 12:27:01 +0200
Subject: [PATCH 1/2] ox-texinfo: Add support for custom navigation hierarchies

* doc/org-manual.org (Headings and sectioning structure): Describe the
new functionality in detail.
* etc/ORG-NEWS (Texinfo exports can have custom navigation
hierarchies): Inform end users about the new functionality.
* lisp/org.el (org-default-properties): Offer the `ALT_TITLE' and
`ALT_NAVIGATION' properties for completion.
* lisp/ox-texinfo.el (org-texinfo-headline): Use the `ALT_NAVIGATION'
property when generating Texinfo notes to set the Next, Previous, and
Up pointers of the relevant Texinfo node.
* testing/lisp/test-ox-texinfo.el (test-ox-texinfo/alt-title):
(test-ox-texinfo/alt-navigation/all-directions):
(test-ox-texinfo/alt-navigation/one-direction):
(test-ox-texinfo/alt-navigation/no-directions):
(test-ox-texinfo/alt-navigation/with-alt-title): Test the new
functionality to avoid regressions in the future.
---
 doc/org-manual.org              | 23 ++++++++
 etc/ORG-NEWS                    |  7 +++
 lisp/org.el                     |  3 +-
 lisp/ox-texinfo.el              |  5 +-
 testing/lisp/test-ox-texinfo.el | 99 +++++++++++++++++++++++++++++++++
 5 files changed, 135 insertions(+), 2 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 9365c66b1..9b53c13c1 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -15999,6 +15999,29 @@ the node in which a reader enters an Info manual.  As such, it is
 expected not to appear in printed output generated from the =.texi=
 file.  See [[info:texinfo::The Top Node]], for more information.
 
+#+cindex: @samp{ALT_NAVIGATION}, property
+By default, Texinfo automatically sets the /Next/, /Previous/, and
+/Up/ pointers, reflecting the hierarchy of your document.  If you want
+it to reflect a different hierarchy, or no hierarchy at all, set the
+=ALT_NAVIGATION= property to a list of at most 3 titles, separated by
+commas, to be used for the /Next/, /Previous/, and /Up/ pointers,
+respectively.  For example:
+
+#+begin_example
+,* Mathematical Logic
+  :PROPERTIES:
+  :ALT_TITLE: Logic
+  :END:
+
+,* Proposition
+  :PROPERTIES:
+  :ALT_NAVIGATION: ,, Logic
+  :END:
+
+  - /Next/ and /Previous/ disabled.
+  - /Up/ leads to [[Mathematical Logic]].
+#+end_example
+
 *** Indices
 :PROPERTIES:
 :DESCRIPTION: Creating indices.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 392788055..25dd3ae49 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -77,6 +77,13 @@ You can now create links to =shortdoc= documentation groups for Emacs
 Lisp functions (see =M-x shortdoc-display-group=).  Requires Emacs 28
 or newer.
 
+*** Texinfo exports can have custom navigation hierarchies
+
+You can now alter the Texinfo navigation hierarchy by specifying the
+/Next/, /Previous/, and /Up/ pointers in the =ALT_NAVIGATION=
+property.  For more information, see "13.14.6 Headings and sectioning
+structure" section of the Org manual.
+
 ** New and changed options
 
 # Chanes deadling with changing default values of customizations,
diff --git a/lisp/org.el b/lisp/org.el
index d5c1dcb35..dcd05571e 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -12691,7 +12691,8 @@ but in some other way.")
     "EXPORT_TITLE" "EXPORT_AUTHOR" "EXPORT_DATE" "UNNUMBERED"
     "ORDERED" "NOBLOCKING" "COOKIE_DATA" "LOG_INTO_DRAWER" "REPEAT_TO_STATE"
     "CLOCK_MODELINE_TOTAL" "STYLE" "HTML_CONTAINER_CLASS"
-    "ORG-IMAGE-ACTUAL-WIDTH")
+    "ORG-IMAGE-ACTUAL-WIDTH"
+    "ALT_TITLE" "ALT_NAVIGATION")
   "Some properties that are used by Org mode for various purposes.
 Being in this list makes sure that they are offered for completion.")
 
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index 6adee9fca..43fdf27ae 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -1102,6 +1102,7 @@ holding contextual information."
 	   (full-text
 	    (funcall (plist-get info :texinfo-format-headline-function)
 		     todo todo-type priority text tags))
+           (navigation (org-element-property :ALT_NAVIGATION headline))
 	   (contents
 	    (concat "\n"
 		    (if (org-string-nw-p contents) (concat "\n" contents) "")
@@ -1118,7 +1119,9 @@ holding contextual information."
 	(concat
 	 ;; Even if HEADLINE is using @subheading and al., leave an
 	 ;; anchor so cross-references in the Org document still work.
-	 (format (if notoc? "@anchor{%s}\n" "@node %s\n") node)
+	 (format (if notoc? "@anchor{%s}" "@node %s") node)
+         (if navigation (concat "," navigation) "")
+         "\n"
 	 (format command full-text)
 	 contents))))))
 
diff --git a/testing/lisp/test-ox-texinfo.el b/testing/lisp/test-ox-texinfo.el
index b16a344e7..352df378f 100644
--- a/testing/lisp/test-ox-texinfo.el
+++ b/testing/lisp/test-ox-texinfo.el
@@ -345,5 +345,104 @@ body
        (should-not (org-element-contents section))
        (should (eq first-heading (org-element-parent section)))))))
 
+\f
+;;; Alternative title and navigation
+
+(ert-deftest test-ox-texinfo/alt-title ()
+  "Test alternative titles."
+  (should
+   (org-test-with-temp-text
+       (string-join
+        (list "* Title 1"
+              ":PROPERTIES:"
+              ":ALT_TITLE: Title 2"
+              ":END:")
+        "\n")
+     (let ((export-buffer "*Test Texinfo Export*")
+           (org-export-show-temporary-export-buffer nil))
+       (org-export-to-buffer 'texinfo export-buffer
+         nil nil nil nil nil
+         #'texinfo-mode)
+       (with-current-buffer export-buffer
+         (goto-char (point-min))
+         (search-forward "@node Title 2"))))))
+
+(ert-deftest test-ox-texinfo/alt-navigation/all-directions ()
+  "Test alternative navigation in all directions."
+  (should
+   (org-test-with-temp-text
+       (string-join
+        (list "* Title"
+              ":PROPERTIES:"
+              ":ALT_NAVIGATION: Next,Previous,Up"
+              ":END:")
+        "\n")
+     (let ((export-buffer "*Test Texinfo Export*")
+           (org-export-show-temporary-export-buffer nil))
+       (org-export-to-buffer 'texinfo export-buffer
+         nil nil nil nil nil
+         #'texinfo-mode)
+       (with-current-buffer export-buffer
+         (goto-char (point-min))
+         (search-forward "@node Title,Next,Previous,Up"))))))
+
+(ert-deftest test-ox-texinfo/alt-navigation/one-direction ()
+  "Test alternative navigation in only one direction."
+  (should
+   (org-test-with-temp-text
+       (string-join
+        (list "* Title"
+              ":PROPERTIES:"
+              ":ALT_NAVIGATION: ,, Up"
+              ":END:")
+        "\n")
+     (let ((export-buffer "*Test Texinfo Export*")
+           (org-export-show-temporary-export-buffer nil))
+       (org-export-to-buffer 'texinfo export-buffer
+         nil nil nil nil nil
+         #'texinfo-mode)
+       (with-current-buffer export-buffer
+         (goto-char (point-min))
+         (search-forward "@node Title,,, Up"))))))
+
+(ert-deftest test-ox-texinfo/alt-navigation/no-directions ()
+  "Test alternative navigation with all directions disabled."
+  (should
+   (org-test-with-temp-text
+       (string-join
+        (list "* Title"
+              ":PROPERTIES:"
+              ":ALT_NAVIGATION: ,,,"
+              ":END:")
+        "\n")
+     (let ((export-buffer "*Test Texinfo Export*")
+           (org-export-show-temporary-export-buffer nil))
+       (org-export-to-buffer 'texinfo export-buffer
+         nil nil nil nil nil
+         #'texinfo-mode)
+       (with-current-buffer export-buffer
+         (goto-char (point-min))
+         (search-forward "@node Title,,,"))))))
+
+(ert-deftest test-ox-texinfo/alt-navigation/with-alt-title ()
+  "Test alternative navigation combined with alternative titles."
+  (should
+   (org-test-with-temp-text
+       (string-join
+        (list "* Title 1"
+              ":PROPERTIES:"
+              ":ALT_TITLE: Title 2"
+              ":ALT_NAVIGATION: Next,Previous,Up"
+              ":END:")
+        "\n")
+     (let ((export-buffer "*Test Texinfo Export*")
+           (org-export-show-temporary-export-buffer nil))
+       (org-export-to-buffer 'texinfo export-buffer
+         nil nil nil nil nil
+         #'texinfo-mode)
+       (with-current-buffer export-buffer
+         (goto-char (point-min))
+         (search-forward "@node Title 2,Next,Previous,Up"))))))
+
 (provide 'test-ox-texinfo)
 ;;; test-ox-texinfo.el end here
-- 
2.39.3 (Apple Git-146)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-ox-texinfo-Add-support-for-links-in-titles.patch --]
[-- Type: text/x-patch, Size: 4792 bytes --]

From ecd8df5bd46feeb8951005bc4929b1384d16bad6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <rudolf@adamkovic.org>
Date: Thu, 22 Aug 2024 18:11:35 +0200
Subject: [PATCH 2/2] ox-texinfo: Add support for links in titles

* etc/ORG-NEWS (Texinfo export backend now allows links to be used in
headings): Inform end users about the new functionality.
* lisp/ox-texinfo.el:
(org-texinfo--format-entries):
(org-texinfo--get-node):
(org-texinfo--sanitize-title-reference):
(org-texinfo--sanitize-title): A 2-step change: (1) Rename
`--sanitize-title' to `--sanitize-title-reference' and (2) create a
new `--sanitize-title' sanitation function.  The new function is less
strict in that does not remove links, which should be allowed in
sectioning commands, such as `@unnumbered'.  The old function remains
more strict, which is useful for generating `@node' names, for
example.
* testing/lisp/test-ox-texinfo.el:
(test-ox-texinfo/headings-with-links): Test the new functionality to
avoid regressions in the future.
---
 etc/ORG-NEWS                    |  4 ++++
 lisp/ox-texinfo.el              | 17 +++++++++++++++--
 testing/lisp/test-ox-texinfo.el | 28 ++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 25dd3ae49..b6d9c54ef 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -230,6 +230,10 @@ This way, attachments will remain accessible when opening symlinked Org file.
 When no attach dir exists, Org mode will still prefer creating it in
 the "default" directory - where the symlink is located.
 
+*** Texinfo export can have links in headings
+
+The Texinfo export backend no longer removes links from headings.
+
 * Version 9.7
 
 ** Important announcements and breaking changes
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index 43fdf27ae..4a02e7b04 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -524,7 +524,7 @@ node or anchor name is unique."
 		(org-texinfo--sanitize-node
 		 (pcase (org-element-type datum)
 		   (`headline
-		    (org-texinfo--sanitize-title
+		    (org-texinfo--sanitize-title-reference
 		     (org-export-get-alt-title datum info) info))
 		   (`radio-target
 		    (org-export-data (org-element-contents datum) info))
@@ -569,6 +569,19 @@ periods, commas and colons."
 (defun org-texinfo--sanitize-title (title info)
   "Make TITLE suitable as a section name.
 TITLE is a string or a secondary string.  INFO is the current
+export state, as a plist."
+  (org-export-data-with-backend
+   title
+   (org-export-create-backend
+    :parent 'texinfo
+    :transcoders `((footnote-reference . ,#'ignore)
+                   (radio-target . ,(lambda (_r c _) c))
+                   (target . ,#'ignore)))
+   info))
+
+(defun org-texinfo--sanitize-title-reference (title info)
+  "Make TITLE suitable as a section reference.
+TITLE is a string or a secondary string.  INFO is the current
 export state, as a plist."
   (org-export-data-with-backend
    title (org-export-toc-entry-backend 'texinfo) info))
@@ -1471,7 +1484,7 @@ a plist containing contextual information."
 	      ;; name.  Remove them.
 	      (replace-regexp-in-string
 	       "[ \t]*:+" ""
-	       (org-texinfo--sanitize-title
+	       (org-texinfo--sanitize-title-reference
 		(org-export-get-alt-title h info) info)))
 	     (node (org-texinfo--get-node h info))
 	     (entry (concat "* " title ":"
diff --git a/testing/lisp/test-ox-texinfo.el b/testing/lisp/test-ox-texinfo.el
index 352df378f..f22448681 100644
--- a/testing/lisp/test-ox-texinfo.el
+++ b/testing/lisp/test-ox-texinfo.el
@@ -444,5 +444,33 @@ body
          (goto-char (point-min))
          (search-forward "@node Title 2,Next,Previous,Up"))))))
 
+\f
+;;; Headings with links
+
+(ert-deftest test-ox-texinfo/headings-with-links ()
+  "Test node and chapter names."
+  (should
+   (org-test-with-temp-text
+       (string-join
+        (list "* Heading 1"
+              "  ...."
+              "* Heading 2 ([[* Heading 1][Heading 1]])"
+              "  ....")
+        "\n")
+     (let ((export-buffer "*Test Texinfo Export*")
+           (org-export-show-temporary-export-buffer nil))
+       (org-export-to-buffer 'texinfo export-buffer
+         nil nil nil nil nil
+         #'texinfo-mode)
+       (with-current-buffer export-buffer
+         (goto-char (point-min))
+         (search-forward "* Heading 1::")
+         (search-forward "* Heading 2 (Heading 1)::")
+         (search-forward "@node Heading 1")
+         (search-forward "@chapter Heading 1")
+         (search-forward "@node Heading 2 (Heading 1)")
+         (search-forward "@chapter Heading 2 (@ref{Heading 1})")
+         (buffer-string))))))
+
 (provide 'test-ox-texinfo)
 ;;; test-ox-texinfo.el end here
-- 
2.39.3 (Apple Git-146)


[-- Attachment #4: Type: text/plain, Size: 173 bytes --]

-- 
"Thinking is a momentary dismissal of irrelevancies."
--- Richard Buckminster Fuller, 1969

Rudolf Adamkovič <rudolf@adamkovic.org> [he/him]
http://adamkovic.org