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
>From 1c4fc3979ea26ca93742b16d9c135ec62a8b4d0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <rud...@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)))))))
+
+;;; 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)
>From ecd8df5bd46feeb8951005bc4929b1384d16bad6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <rud...@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"))))))
+
+;;; 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)
--
"Thinking is a momentary dismissal of irrelevancies."
--- Richard Buckminster Fuller, 1969
Rudolf Adamkovič <rud...@adamkovic.org> [he/him]
http://adamkovic.org
