[patch] ox-man: footer-middle and header-middle options

["Grégoire Scano" <gregoire.scano@malloc.fr>]

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

Hello :-)

Thank you so much for recently adding =#+DATE= support for ox-man!

Attached is a small patch adding two options to =#+MAN_CLASS_OPTIONS= to
customize the footer-middle and header-middle arguments of the .TH macro.

Adding support for the footer-middle is convenient since it often
indicates the release version.
Although header-middle is probably not used very often, adding it was
just a step away - note that Emacs itself overwrites the title of
section 1 to GNU!

Tests are mostly here for non regression purposes.
They should also pass on main; except for the two added specifically,
namely =ox-man/title-date-section-release= and
=ox-man/title-date-section-release-header=.

Best,
Grégoire

Note: =title= seems to never be ='nil=. The line separator was missing
in the fallback condition but export seems to yield a clean .TH line in
every configuration.

[-- Attachment #2: 0001-ox-man-Add-support-for-footer-inside-and-header-midd.patch --]
[-- Type: text/x-patch, Size: 4870 bytes --]

From 1db85726bd557e3b3c7b834fd91ba6a7e6860eeb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Scano?= <gregoire.scano@malloc.fr>
Date: Tue, 21 Jan 2025 09:52:57 +0800
Subject: [PATCH] ox-man: Add support for footer-inside and header-middle

* etc/ORG-NEWS (ox-man): Announce the change.
* lisp/ox-man.el (org-man-template): Support footer-inside and header-middle with =#+MAN_CLASS_OPTIONS: :release "" :header ""=.
* testing/lisp/test-ox-man.el (ox-man-test): Add non regression and newly supported options tests.

TINYCHANGE
---
 etc/ORG-NEWS                |  6 ++++++
 lisp/ox-man.el              | 20 ++++++++++--------
 testing/lisp/test-ox-man.el | 42 +++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 9 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index cb2c16da8..93c128448 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -413,6 +413,12 @@ Previously, ox-man ignored =#+DATE:= keyword even when
 and specified in the =footer-middle= argument of =.TH= macro (see ~man
 7 man~).
 
+*** ox-man: Support specifying =:release= and =:header= in =#+MAN_CLASS_OPTIONS:= in addition to =:section-id=
+
+The newly added =:release= and =:header= options of =#+MAN_CLASS_OPTIONS=
+are respectively mapped to the =footer-inside= and =header-middle=
+arguments of the =.TH= macro (see ~man 7 groff_man~).
+
 *** ~org-timer-done-hook~ is now run before the timer is stopped
 
 Previously, ~org-timer-countdown-timer~ and ~org-timer-start-time~
diff --git a/lisp/ox-man.el b/lisp/ox-man.el
index 1fe5f9eae..0daee7c22 100644
--- a/lisp/ox-man.el
+++ b/lisp/ox-man.el
@@ -328,20 +328,22 @@ holding export options."
                               (list (plist-get info :man-class-options))
                               " "))))
          (section-item (plist-get attr :section-id))
+         (release (plist-get attr :release))
+         (header (plist-get attr :header))
          ;; Note: groff linter suggests date to be the third argument
          ;; of .TH
          (date (and (plist-get info :with-date)
 		    (org-export-data (org-export-get-date info) info))))
     (concat
-     (cond
-      ((and title (stringp section-item))
-       (format ".TH \"%s\" \"%s\" \"%s\" \n" title section-item date))
-      ((and (string= "" title) (stringp section-item))
-       (format ".TH \"%s\" \"%s\" \"%s\" \n" " " section-item date))
-      (title
-       (format ".TH \"%s\" \"1\" \"%s\" \n" title date))
-      (t
-       (format ".TH \" \" \"1\" \"%s\" " date)))
+     (format ".TH \"%s\" \"%s\"" ;; only two required by groff_man(7).
+             (if title title " ")
+             (if (stringp section-item) section-item "1"))
+     (format " \"%s\"" date)
+     (if release (format " \"%s\"" release))
+     ;; Do not write an empty footer-outside, otherwise man(1) will
+     ;; no longer generate its content, see groff_man(7).
+     (if header (format " \"%s\"" header))
+     " \n"
      contents)))
 
 
diff --git a/testing/lisp/test-ox-man.el b/testing/lisp/test-ox-man.el
index 12f839ea8..a7a41040b 100644
--- a/testing/lisp/test-ox-man.el
+++ b/testing/lisp/test-ox-man.el
@@ -82,5 +82,47 @@ executable is available)."
     (should (search-forward "\\fIunderlined\\fP"))
     (should (search-forward "\\fIverbatim\\fP"))))
 
+(ert-deftest ox-man/default ()
+  "Test default values."
+  (ox-man/test-with-exported-test
+   ""
+   (should (string= (buffer-string) ".TH \"\" \"1\" \"\" \n"))))
+
+(ert-deftest ox-man/title-only ()
+  "Test title only."
+  (ox-man/test-with-exported-test
+   "#+TITLE: Emacs"
+   (should (string= (buffer-string) ".TH \"Emacs\" \"1\" \"\" \n"))))
+
+(ert-deftest ox-man/section-only ()
+  "Test version (1 is the default value, use 2 instead)."
+  (ox-man/test-with-exported-test
+   "#+MAN_CLASS_OPTIONS: :section-id \"2\""
+   (should (string= (buffer-string) ".TH \"\" \"2\" \"\" \n"))))
+
+(ert-deftest ox-man/title-date-section ()
+  "Test main options."
+  (ox-man/test-with-exported-test
+   "#+TITLE: Emacs
+    #+DATE: 1985-03-20
+    #+MAN_CLASS_OPTIONS: :section-id \"2\""
+   (should (string= (buffer-string) ".TH \"Emacs\" \"2\" \"1985-03-20\" \n"))))
+
+(ert-deftest ox-man/title-date-section-release ()
+  "Test release."
+  (ox-man/test-with-exported-test
+   "#+TITLE: Emacs
+    #+DATE: 1985-03-20
+    #+MAN_CLASS_OPTIONS: :section-id \"2\" :release \"Emacs 13\""
+   (should (string= (buffer-string) ".TH \"Emacs\" \"2\" \"1985-03-20\" \"Emacs 13\" \n"))))
+
+(ert-deftest ox-man/title-date-section-release-header ()
+  "Test header."
+  (ox-man/test-with-exported-test
+   "#+TITLE: Emacs
+    #+DATE: 1985-03-20
+    #+MAN_CLASS_OPTIONS: :section-id \"2\" :release \"Emacs 13\" :header \"GNU\""
+   (should (string= (buffer-string) ".TH \"Emacs\" \"2\" \"1985-03-20\" \"Emacs 13\" \"GNU\" \n"))))
+
 (provide 'test-ox-man)
 ;;; test-ox-man.el ends here
-- 
2.39.5