master 5254c582efb 1/3: ox-texinfo:: Require only TEXINFO_DIR_CATEGORY

[Stefan Monnier]

branch: master
commit 5254c582efb3e7171e955dde653e7530d2d3ffef
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    ox-texinfo:: Require only TEXINFO_DIR_CATEGORY
    
    Until now @dircategory/@direntry entries were added only if
    both TEXINFO_DIR_CATEGORY and TEXINFO_DIR_TITLE were set.
    And the setting of TEXINFO_DIR_TITLE had to be careful to
    provide exactly the right syntax.
    
    This patch changes various things in this regard:
    - Only require TEXINFO_DIR_CATEGORY in order to generate
      `@dircategory` and `@direntry`.
    - Use the document title by default if TEXINFO_DIR_DESC is missing.
    - Use the filename by default when TEXINFO_DIR_TITLE is missing.
    - Try and make it harder to provide a direntry that does not
      have the right format or refers to a different filename than
      the one we're outputting to.
    
    * lisp/org/ox-texinfo.el: Remove redundant `:group` arguments.
    Prefer #' to quote function names.
    (org-texinfo-template): Use sane defaults for `@direntry`.
    
    * doc/misc/org.org (Texinfo specific export settings): Adjust accordingly.
---
 doc/misc/org.org       | 11 ++++++++--
 lisp/org/ox-texinfo.el | 58 ++++++++++++++++++++++++--------------------------
 2 files changed, 37 insertions(+), 32 deletions(-)

diff --git a/doc/misc/org.org b/doc/misc/org.org
index 05ab5b36ca0..f4590525892 100644
--- a/doc/misc/org.org
+++ b/doc/misc/org.org
@@ -15322,11 +15322,18 @@ the general options (see [[*Export Settings]]).
 
   #+cindex: @samp{TEXINFO_DIR_TITLE}, keyword
   The directory title of the document.
+  This is the short name under which the ~m~ command will find your
+  manual in the main Info directory.  It defaults to the base name of
+  the Texinfo file.
+
+  If you need more control, it can also be the full entry using the
+  syntax ~* TITLE: (FILENAME).~.
 
 - =TEXINFO_DIR_DESC= ::
 
   #+cindex: @samp{TEXINFO_DIR_DESC}, keyword
   The directory description of the document.
+  Defaults to the title of the document.
 
 - =TEXINFO_PRINTED_TITLE= ::
 
@@ -15422,7 +15429,7 @@ Here is an example that writes to the Info directory 
file:
 
 #+begin_example
 ,#+TEXINFO_DIR_CATEGORY: Emacs
-,#+TEXINFO_DIR_TITLE: Org Mode: (org)
+,#+TEXINFO_DIR_TITLE: Org Mode
 ,#+TEXINFO_DIR_DESC: Outline-based notes management and organizer
 #+end_example
 
@@ -15830,7 +15837,7 @@ Texinfo code.
 ,#+TEXINFO_HEADER: @syncodeindex pg cp
 
 ,#+TEXINFO_DIR_CATEGORY: Texinfo documentation system
-,#+TEXINFO_DIR_TITLE: sample: (sample)
+,#+TEXINFO_DIR_TITLE: sample
 ,#+TEXINFO_DIR_DESC: Invoking sample
 
 ,#+TEXINFO_PRINTED_TITLE: GNU Sample
diff --git a/lisp/org/ox-texinfo.el b/lisp/org/ox-texinfo.el
index 84313645e6e..5065c3fb63c 100644
--- a/lisp/org/ox-texinfo.el
+++ b/lisp/org/ox-texinfo.el
@@ -110,6 +110,10 @@
     (:subtitle "SUBTITLE" nil nil parse)
     (:subauthor "SUBAUTHOR" nil nil newline)
     (:texinfo-dircat "TEXINFO_DIR_CATEGORY" nil nil t)
+    ;; FIXME: The naming of these options is unsatisfactory:
+    ;; TEXINFO_DIR_DESC corresponds (and defaults) to the document's
+    ;; title, whereas TEXINFO_DIR_TITLE corresponds (and defaults) to
+    ;; its filename.
     (:texinfo-dirtitle "TEXINFO_DIR_TITLE" nil nil t)
     (:texinfo-dirdesc "TEXINFO_DIR_DESC" nil nil t)
     (:texinfo-printed-title "TEXINFO_PRINTED_TITLE" nil nil t)
@@ -147,12 +151,10 @@
   "Default document encoding for Texinfo output.
 
 If nil it will default to `buffer-file-coding-system'."
-  :group 'org-export-texinfo
   :type 'coding-system)
 
 (defcustom org-texinfo-default-class "info"
   "The default Texinfo class."
-  :group 'org-export-texinfo
   :type '(string :tag "Texinfo class"))
 
 (defcustom org-texinfo-classes
@@ -205,7 +207,6 @@ The sectioning structure of the class is given by the 
elements
 following the header string.  For each sectioning level, a number
 of strings is specified.  A %s formatter is mandatory in each
 section string and will be replaced by the title of the section."
-  :group 'org-export-texinfo
   :version "27.1"
   :package-version '(Org . "9.2")
   :type '(repeat
@@ -233,7 +234,6 @@ TEXT      the main headline text (string).
 TAGS      the tags as a list of strings (list of strings or nil).
 
 The function result will be used in the section format string."
-  :group 'org-export-texinfo
   :type 'function
   :version "26.1"
   :package-version '(Org . "8.3"))
@@ -244,38 +244,32 @@ The function result will be used in the section format 
string."
   "Column at which to start the description in the node listings.
 If a node title is greater than this length, the description will
 be placed after the end of the title."
-  :group 'org-export-texinfo
   :type 'integer)
 
 ;;;; Timestamps
 
 (defcustom org-texinfo-active-timestamp-format "@emph{%s}"
   "A printf format string to be applied to active timestamps."
-  :group 'org-export-texinfo
   :type 'string)
 
 (defcustom org-texinfo-inactive-timestamp-format "@emph{%s}"
   "A printf format string to be applied to inactive timestamps."
-  :group 'org-export-texinfo
   :type 'string)
 
 (defcustom org-texinfo-diary-timestamp-format "@emph{%s}"
   "A printf format string to be applied to diary timestamps."
-  :group 'org-export-texinfo
   :type 'string)
 
 ;;;; Links
 
 (defcustom org-texinfo-link-with-unknown-path-format "@indicateurl{%s}"
   "Format string for links with unknown path type."
-  :group 'org-export-texinfo
   :type 'string)
 
 ;;;; Tables
 
 (defcustom org-texinfo-tables-verbatim nil
   "When non-nil, tables are exported verbatim."
-  :group 'org-export-texinfo
   :type 'boolean)
 
 (defcustom org-texinfo-table-scientific-notation nil
@@ -285,7 +279,6 @@ The format should have \"%s\" twice, for mantissa and 
exponent
 \(i.e. \"%s\\\\times10^{%s}\").
 
 When nil, no transformation is made."
-  :group 'org-export-texinfo
   :type '(choice
          (string :tag "Format string")
          (const :tag "No formatting" nil)))
@@ -297,7 +290,6 @@ This should an indicating command, e.g., \"@code\", 
\"@kbd\" or
 \"@samp\".
 
 It can be overridden locally using the \":indic\" attribute."
-  :group 'org-export-texinfo
   :type 'string
   :version "26.1"
   :package-version '(Org . "9.1")
@@ -323,7 +315,6 @@ to typeset and protects special characters.
 
 When no association is found for a given markup, text is returned
 as-is."
-  :group 'org-export-texinfo
   :version "26.1"
   :package-version '(Org . "9.1")
   :type 'alist
@@ -341,7 +332,6 @@ The function must accept two parameters:
 The function should return the string to be exported.
 
 The default function simply returns the value of CONTENTS."
-  :group 'org-export-texinfo
   :version "24.4"
   :package-version '(Org . "8.2")
   :type 'function)
@@ -361,7 +351,6 @@ The function must accept six parameters:
   CONTENTS  the contents of the inlinetask, as a string.
 
 The function should return the string to be exported."
-  :group 'org-export-texinfo
   :type 'function)
 
 ;;;; LaTeX
@@ -374,7 +363,6 @@ fragments as Texinfo \"@displaymath\" and \"@math\" commands
 respectively.  Alternatively, when set to `detect', the exporter
 does so only if the installed version of Texinfo supports the
 necessary commands."
-  :group 'org-export-texinfo
   :package-version '(Org . "9.6")
   :type '(choice
           (const :tag "Detect" detect)
@@ -391,7 +379,6 @@ body but is followed by another item, then the second item 
is
 transcoded to `@itemx'.  See info node `(org)Plain lists in
 Texinfo export' for how to enable this for individual lists."
   :package-version '(Org . "9.6")
-  :group 'org-export-texinfo
   :type 'boolean
   :safe t)
 
@@ -406,7 +393,6 @@ relative file name, %F by the absolute file name, %b by the 
file
 base name (i.e. without directory and extension parts), %o by the
 base directory of the file and %O by the absolute file name of
 the output file."
-  :group 'org-export-texinfo
   :version "26.1"
   :package-version '(Org . "9.1")
   :type '(repeat :tag "Shell command sequence"
@@ -416,8 +402,8 @@ the output file."
   '("aux" "toc" "cp" "fn" "ky" "pg" "tp" "vr")
   "The list of file extensions to consider as Texinfo logfiles.
 The logfiles will be remove if `org-texinfo-remove-logfiles' is
+
 non-nil."
-  :group 'org-export-texinfo
   :type '(repeat (string :tag "Extension")))
 
 (defcustom org-texinfo-remove-logfiles t
@@ -815,19 +801,31 @@ holding export options."
          (format "@copying\n%s@end copying\n\n"
                  (org-element-normalize-string
                   (org-export-data copying info))))
-     ;; Info directory information.  Only supply if both title and
-     ;; category are provided.
-     (let ((dircat (plist-get info :texinfo-dircat))
-          (dirtitle
-           (let ((title (plist-get info :texinfo-dirtitle)))
-             (and title
-                  (string-match "^\\(?:\\* \\)?\\(.*?\\)\\(\\.\\)?$" title)
-                  (format "* %s." (match-string 1 title))))))
-       (when (and dircat dirtitle)
+     ;; Info directory information.  Only supply if category is provided.
+     ;; FIXME: A Texinfo doc without a direntry is significantly less useful
+     ;; since it won't appear in the main Info-directory, so maybe we should
+     ;; use a default category like "misc"?
+     (let* ((dircat (plist-get info :texinfo-dircat))
+           (dt (plist-get info :texinfo-dirtitle))
+           (file (file-name-sans-extension
+                  (or (org-strip-quotes (plist-get info :texinfo-filename))
+                      (plist-get info :output-file))))
+           (dirtitle
+             (cond
+              ((and dt
+                    (or (string-match "\\`\\* \\(.*?\\)\\(\\.\\)?\\'" dt)
+                        (string-match "\\`\\(.*(.*)\\)\\(\\.\\)?\\'" dt)))
+               ;; `dt' is already "complete".
+               (format "* %s." (match-string 1 dt)))
+              ((and dt (not (equal dt file)))
+               (format "* %s: (%s)." dt file))
+              (t (format "* %s." file)))))
+       (when dircat
         (concat "@dircategory " dircat "\n"
                 "@direntry\n"
                 (let ((dirdesc
-                       (let ((desc (plist-get info :texinfo-dirdesc)))
+                       (let ((desc (or (plist-get info :texinfo-dirdesc)
+                                       title)))
                          (cond ((not desc) nil)
                                ((string-suffix-p "." desc) desc)
                                (t (concat desc "."))))))
@@ -1590,7 +1588,7 @@ information."
   (concat
    "@noindent"
    (mapconcat
-    'identity
+    #'identity
     (delq nil
          (list
           (let ((closed (org-element-property :closed planning)))