[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Provide sane default for the @direntry
From: |
Stefan Monnier |
Subject: |
Re: Provide sane default for the @direntry |
Date: |
Wed, 06 Mar 2024 10:00:34 -0500 |
User-agent: |
Gnus/5.13 (Gnus v5.13) |
> The patches are against Emacs git repository, not against Org mode. May
> your please port them?
See attached.
>> Subject: [PATCH 1/2] * lisp/org/ox-texinfo.el: Remove redundant `:group`s
> By our convention, we drop leading * in the first line of the commit message.
Done.
>> * lisp/org/ox-texinfo.el (texinfo): Add entry for TEXINFO_DIR_NAME.
>> (org-texinfo-template): Use sane defaults for `@direntry` and `@dircategory`.
>> * doc/misc/org.org (Texinfo specific export settings): Adjust accordingly.
> * etc/ORG-NEWS changelog entry is missing.
Hmm... did know you needed them.
>> +- =TEXINFO_DIR_NAME= ::
>> +
>> + #+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_TITLE= ::
>>
>> #+cindex: @samp{TEXINFO_DIR_TITLE}, keyword
>> - The directory title of the document.
>> + Old and obsolete name of the =TEXINFO_DIR_NAME= option.
>
> We can simply remove TEXINFO_DIR_TITLE from the manual.
Fair enough.
> Also, please update "Info directory file" section. In particular,
> references to TEXINFO_DIR_TITLE.
Indeed, thanks for spotting this.
>> + (dn (or (plist-get info :texinfo-dirname)
>> + (plist-get info :texinfo-dirtitle))) ;Obsolete name.
>> + ;; Strip any terminating `.' from `dn'.
>> + (dn (if (string-match "\\.\\'" dn) (substring dn 0 -1) dn))
>
> `string-match' will throw an error when both :texinfo-dirname and
> :texinfo-dirtitle records are not provided (nil).
Duh!
Stefan
>From ae03b9fa16599eae15a13167d7158266640e76fc Mon Sep 17 00:00:00 2001
From: Stefan Monnier <monnier@iro.umontreal.ca>
Date: Tue, 5 Mar 2024 14:11:19 -0500
Subject: [PATCH 1/2] lisp/ox-texinfo.el: Remove redundant `:group`s
---
lisp/ox-texinfo.el | 22 ++--------------------
1 file changed, 2 insertions(+), 20 deletions(-)
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index bd01effaa6..ef46dafff2 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -147,12 +147,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 +203,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 +230,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 +240,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 +275,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 +286,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 +311,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 +328,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 +347,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 +359,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 +375,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 +389,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 +398,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
@@ -1591,7 +1573,7 @@ information."
(concat
"@noindent"
(mapconcat
- 'identity
+ #'identity
(delq nil
(list
(let ((closed (org-element-property :closed planning)))
--
2.43.0
>From e64f880e68cc48666a857f33ad27e68e9103b21e Mon Sep 17 00:00:00 2001
From: Stefan Monnier <monnier@iro.umontreal.ca>
Date: Tue, 5 Mar 2024 14:15:55 -0500
Subject: [PATCH 2/2] 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: 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..cf347d253f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1727,6 +1727,13 @@ following properties: ~:hook~, ~:prepare-finalize~,
~:before-finalize~, ~:after-finalize~. These nullary functions run
prior to their global counterparts for the selected template.
+*** 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 options
*** A new option for custom setting ~org-refile-use-outline-path~ to show
document title in refile targets
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index ef46dafff2..b66e98e19c 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.
@@ -797,25 +798,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 (file-name-sans-extension
+ (or (org-strip-quotes (plist-get info :texinfo-filename))
+ (plist-get info :output-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 file))
+ (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"
--
2.43.0
- Re: Provide sane default for the @direntry, Stefan Monnier, 2024/03/02
- Re: Provide sane default for the @direntry, Ihor Radchenko, 2024/03/04
- Re: Provide sane default for the @direntry, Stefan Monnier, 2024/03/04
- Re: Provide sane default for the @direntry, Ihor Radchenko, 2024/03/05
- Re: Provide sane default for the @direntry, Stefan Monnier, 2024/03/05
- Re: Provide sane default for the @direntry, Ihor Radchenko, 2024/03/06
- Re: Provide sane default for the @direntry,
Stefan Monnier <=
- Re: Provide sane default for the @direntry, Ihor Radchenko, 2024/03/07
- Re: Provide sane default for the @direntry, Stefan Monnier, 2024/03/08
- Re: Provide sane default for the @direntry, Ihor Radchenko, 2024/03/08