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.
This commit is contained in:
Stefan Monnier
Ihor Radchenko
parent
4fd8691941
commit
b0c3c90574
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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~
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in New Issue