[elpa] scratch/org 0a0119112c 2/2: ox-texinfo:: Always provide a @direntry

[Stefan Monnier]

branch: scratch/org
commit 0a0119112c82424a59e2c8132ddb1674b010f85c
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    ox-texinfo:: Always provide a @direntry
    
    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:
    - Always generate a @dircategory/@direntry.
    - Default TEXINFO_DIR_CATEGORY to "Misc".
    - Use the document title by default if TEXINFO_DIR_DESC is missing.
    - Rename TEXINFO_DIR_TITLE to TEXINFO_DIR_NAME.
    - Use the filename by default when TEXINFO_DIR_NAME 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/ox-texinfo.el (texinfo): Add entry for TEXINFO_DIR_NAME.
    (org-texinfo-template): Use sane defaults for `@direntry` and 
`@dircategory`.
    
    * doc/org-manual.org (Texinfo specific export settings): Adjust accordingly.
    (Info directory file, A Texinfo example, Export Setup): Update examples
    to use the new syntax.
    * etc/ORG-NEWS (Version 9.7 / New features): Add entry.
---
 doc/org-manual.org | 27 +++++++++++++++--------
 etc/ORG-NEWS       |  7 ++++++
 lisp/ox-texinfo.el | 65 +++++++++++++++++++++++++++++++++++++-----------------
 3 files changed, 70 insertions(+), 29 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 89592b12da..39a9fec854 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -15718,17 +15718,26 @@ the general options (see [[*Export Settings]]).
 - =TEXINFO_DIR_CATEGORY= ::
 
   #+cindex: @samp{TEXINFO_DIR_CATEGORY}, keyword
-  The directory category of the document.
+  The directory category of the document.  Defaults to ~Misc~.
 
-- =TEXINFO_DIR_TITLE= ::
+- =TEXINFO_DIR_NAME= ::
 
-  #+cindex: @samp{TEXINFO_DIR_TITLE}, keyword
-  The directory title of the document.
+  #+cindex: @samp{TEXINFO_DIR_NAME}, keyword
+  The directory name 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.
+
+  The full form of the Texinfo entry is ~* DIRNAME: NODE.~ where ~NODE~
+  is usually just ~(FILENAME)~.  Normally this option only provides the
+  ~DIRNAME~ part, but if you need more control, it can also be the full
+  entry (recognized by the presence of parentheses or a leading ~* ~).
 
 - =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= ::
 
@@ -15812,11 +15821,11 @@ Copyright information is printed on the back of the 
title page.
 #+cindex: @code{install-info}, in Texinfo export
 
 #+cindex: @samp{TEXINFO_DIR_CATEGORY}, keyword
-#+cindex: @samp{TEXINFO_DIR_TITLE}, keyword
+#+cindex: @samp{TEXINFO_DIR_NAME}, keyword
 #+cindex: @samp{TEXINFO_DIR_DESC}, keyword
 The end result of the Texinfo export process is the creation of an
 Info file.  This Info file's metadata has variables for category,
-title, and description: =TEXINFO_DIR_CATEGORY=, =TEXINFO_DIR_TITLE=,
+title, and description: =TEXINFO_DIR_CATEGORY=, =TEXINFO_DIR_NAME=,
 and =TEXINFO_DIR_DESC= keywords that establish where in the Info
 hierarchy the file fits.
 
@@ -15824,7 +15833,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_NAME: Org Mode
 ,#+TEXINFO_DIR_DESC: Outline-based notes management and organizer
 #+end_example
 
@@ -16232,7 +16241,7 @@ Texinfo code.
 ,#+TEXINFO_HEADER: @syncodeindex pg cp
 
 ,#+TEXINFO_DIR_CATEGORY: Texinfo documentation system
-,#+TEXINFO_DIR_TITLE: sample: (sample)
+,#+TEXINFO_DIR_NAME: sample
 ,#+TEXINFO_DIR_DESC: Invoking sample
 
 ,#+TEXINFO_PRINTED_TITLE: GNU Sample
@@ -22924,7 +22933,7 @@ modify this GNU manual."
 #+export_file_name: org.texi
 
 #+texinfo_dir_category: Emacs editing modes
-#+texinfo_dir_title: Org Mode: (org)
+#+texinfo_dir_name: Org Mode: (org)
 #+texinfo_dir_desc: Outline-based notes management and organizer
 
 * Footnotes
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 26f0c90f95..abe62daaf5 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1141,6 +1141,13 @@ anonymous footnotes automatically with 
~org-footnote-new~.
 The same can be done via startup options:
 : #+STARTUP: fnanon
 
+*** ox-texinfo always generates a ~@direntry~
+We use defaults based on the file name and title of the document, and
+place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
+
+=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
+The old name is obsolete.
+
 ** New functions and changes in function arguments
 *** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
 
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index d74ed50033..22b5567514 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -110,7 +110,8 @@
     (:subtitle "SUBTITLE" nil nil parse)
     (:subauthor "SUBAUTHOR" nil nil newline)
     (:texinfo-dircat "TEXINFO_DIR_CATEGORY" nil nil t)
-    (:texinfo-dirtitle "TEXINFO_DIR_TITLE" nil nil t)
+    (:texinfo-dirtitle "TEXINFO_DIR_TITLE" nil nil t) ;Obsolete.
+    (:texinfo-dirname "TEXINFO_DIR_NAME" nil nil t)
     (:texinfo-dirdesc "TEXINFO_DIR_DESC" nil nil t)
     (:texinfo-printed-title "TEXINFO_PRINTED_TITLE" nil nil t)
     ;; Other variables.
@@ -796,25 +797,49 @@ 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)
-        (concat "@dircategory " dircat "\n"
-                "@direntry\n"
-                (let ((dirdesc
-                       (let ((desc (plist-get info :texinfo-dirdesc)))
-                         (cond ((not desc) nil)
-                               ((string-suffix-p "." desc) desc)
-                               (t (concat desc "."))))))
-                  (if dirdesc (format "%-23s %s" dirtitle dirdesc) dirtitle))
-                "\n"
-                "@end direntry\n\n")))
+     (let* ((dircat (or (plist-get info :texinfo-dircat) "Misc"))
+           (file (or (org-strip-quotes (plist-get info :texinfo-filename))
+                   (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.
+           ;; Strip any terminating `.' from `dn'.
+           (dn (if (and dn (string-match "\\.\\'" dn)) (substring dn 0 -1) dn))
+           ;; The direntry we need to produce has the shape:
+           ;;     * DIRNAME: NODE.   DESCRIPTION.
+           ;; where NODE is usually just `(FILENAME)', and where
+           ;; `* FILENAME.' is a shorthand for `* FILENAME: (FILENAME).'
+           (dirname
+             (cond
+              ((and dn (string-match
+                        (eval-when-compile
+                          (concat "\\`\\(?:"
+                                  "\\* \\(?1:.*\\)" ;Starts with `* ' or
+                                  "\\|\\(?1:.*(.*).*\\)" ;contains parens.
+                                  "\\)\\'"))
+                        dn))
+               ;; When users provide a `dn' that looks like a complete
+               ;; `* DIRNAME: (FILENAME).' thingy, we just trust them to
+               ;; provide something valid (just making sure it starts
+               ;; with `* ' and ends with `.').
+               (format "* %s." (match-string 1 dn)))
+              ;; `dn' is presumed to be just the DIRNAME part, so generate
+              ;; either `* DIRNAME: (FILENAME).' or `* FILENAME.', whichever
+              ;; is shortest.
+              ((and dn (not (equal dn file)))
+               (format "* %s: (%s)." dn (or file dn)))
+              (t (format "* %s." file)))))
+       (concat "@dircategory " dircat "\n"
+              "@direntry\n"
+              (let ((dirdesc
+                     (let ((desc (or (plist-get info :texinfo-dirdesc)
+                                     title)))
+                       (cond ((not desc) nil)
+                             ((string-suffix-p "." desc) desc)
+                             (t (concat desc "."))))))
+                (if dirdesc (format "%-23s %s" dirname dirdesc) dirname))
+              "\n"
+              "@end direntry\n\n"))
      ;; Title
      "@finalout\n"
      "@titlepage\n"