From ba13b7a50d515db99a5cdd0dea19ea98b76d68b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= 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 feature in detail. * etc/ORG-NEWS (Texinfo exports can have custom navigation hierarchies): Inform end users about the new feature. * lisp/org.el (org-default-properties): Offer the `ALT_TITLE' and `ALT_NAVIGATION' properties for completion. * lisp/ox-texinfo.el (org-texinfo-headline, org-texinfo-template): Use the `ALT_NAVIGATION' property when generating Texinfo notes to set the Next, Previous, and Up pointers of the relevant Texinfo node. (org-texinfo--match-definition, org-texinfo-item): Fix indentation. * 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-ox-texinfo/alt-navigation/top/default, test-ox-texinfo/alt-navigation/top/default): Test the new feature to avoid regressions in the future. --- doc/org-manual.org | 23 ++++++ etc/ORG-NEWS | 7 ++ lisp/org.el | 3 +- lisp/ox-texinfo.el | 21 +++-- testing/lisp/test-ox-texinfo.el | 133 ++++++++++++++++++++++++++++++++ 5 files changed, 181 insertions(+), 6 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..a396d93d3 100644 --- a/lisp/ox-texinfo.el +++ b/lisp/ox-texinfo.el @@ -652,7 +652,7 @@ The car is the command and the cdr is its arguments." (string-match org-texinfo--definition-command-regexp tag) (pcase-let* ((cmd (car (rassoc (match-string-no-properties 1 tag) - org-texinfo--definition-command-alist))) + org-texinfo--definition-command-alist))) (`(,cmd ,category) (and cmd (save-match-data (split-string cmd " ")))) (args (match-string-no-properties 2 tag))) @@ -799,7 +799,7 @@ holding export options." (org-export-data copying info)))) (let* ((dircat (or (plist-get info :texinfo-dircat) "Misc")) (file (or (org-strip-quotes (plist-get info :texinfo-filename)) - (plist-get info :output-file))) + (plist-get info :output-file))) (file (if file (file-name-sans-extension file))) (dn (or (plist-get info :texinfo-dirname) (plist-get info :texinfo-dirtitle))) ;Obsolete name. @@ -875,7 +875,15 @@ holding export options." ;; Configure Top Node when not for TeX. Also include contents ;; from the first section of the document. "@ifnottex\n" - "@node Top\n" + ;; Top node. + "@node Top" + (if-let ((top-navigation + (org-element-map (plist-get info :parse-tree) 'org-data + (lambda (data) + (org-element-property :ALT_NAVIGATION data)) + info t))) + (concat ", " top-navigation)) + "\n" (format "@top %s\n" title) (let* ((first-section (org-element-map (plist-get info :parse-tree) 'section @@ -1102,6 +1110,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 +1127,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)))))) @@ -1189,7 +1200,7 @@ contextual information." (compact (and (eq (org-element-property :type plain-list) 'descriptive) (or (plist-get info :texinfo-compact-itemx) (org-not-nil (org-export-read-attribute - :attr_texinfo plain-list :compact))))) + :attr_texinfo plain-list :compact))))) (previous-item nil)) (when (and compact (org-export-get-next-element item info) diff --git a/testing/lisp/test-ox-texinfo.el b/testing/lisp/test-ox-texinfo.el index b16a344e7..fe931baa4 100644 --- a/testing/lisp/test-ox-texinfo.el +++ b/testing/lisp/test-ox-texinfo.el @@ -345,5 +345,138 @@ 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")))))) + + +(ert-deftest test-ox-texinfo/alt-navigation/top-node/default () + "Test alternative navigation when not set at the top level." + (should + (org-test-with-temp-text "Hello world!" + (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)) + (re-search-forward "^@node Top$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/top-node/custom () + "Test alternative navigation when set at the top level." + (should + (org-test-with-temp-text + (string-join + (list ":PROPERTIES:" + ":ALT_NAVIGATION: Next, Previous, Up" + ":END:" + "#+TITLE: Title" + "* Headline") + "\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)) + (re-search-forward "^@node Top, Next, Previous, Up$")))))) + (provide 'test-ox-texinfo) ;;; test-ox-texinfo.el end here -- 2.39.3 (Apple Git-146)