From b0c3c90574ed79a63e56acaeee156ef8d9593233 Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Tue, 5 Mar 2024 14:15:55 -0500 Subject: [PATCH] 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 21e13ded1..121ff59b4 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 26f0c90f9..abe62daaf 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 d74ed5003..22b556751 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"