* Provide sane default for the @direntry
@ 2024-02-28 0:19 Stefan Monnier
2024-02-28 10:35 ` Ihor Radchenko
0 siblings, 1 reply; 12+ messages in thread
From: Stefan Monnier @ 2024-02-28 0:19 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 349 bytes --]
When exporting to Texinfo, the patch below makes it easier to generate
a good `@direntry` by using sane defaults.
For most files, you'll just need
#+TEXINFO_DIR_CATEGORY: {my-category}
I believe it also makes it a bit harder to shoot oneself in the foot and
generate an invalid entry (e.g. with a missing or wrong file name).
Stefan
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: org.patch --]
[-- Type: text/x-diff, Size: 1864 bytes --]
diff --git a/lisp/org/ox-texinfo.el b/lisp/org/ox-texinfo.el
index 84313645e6e..beea7aacab7 100644
--- a/lisp/org/ox-texinfo.el
+++ b/lisp/org/ox-texinfo.el
@@ -817,17 +799,27 @@ org-texinfo-template
(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)
+ (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 +1582,7 @@ org-texinfo-planning
(concat
"@noindent"
(mapconcat
- 'identity
+ #'identity
(delq nil
(list
(let ((closed (org-element-property :closed planning)))
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: Provide sane default for the @direntry 2024-02-28 0:19 Provide sane default for the @direntry Stefan Monnier @ 2024-02-28 10:35 ` Ihor Radchenko 2024-03-02 20:01 ` Stefan Monnier 0 siblings, 1 reply; 12+ messages in thread From: Ihor Radchenko @ 2024-02-28 10:35 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-orgmode Stefan Monnier <monnier@iro.umontreal.ca> writes: > When exporting to Texinfo, the patch below makes it easier to generate > a good `@direntry` by using sane defaults. > For most files, you'll just need > > #+TEXINFO_DIR_CATEGORY: {my-category} > > I believe it also makes it a bit harder to shoot oneself in the foot and > generate an invalid entry (e.g. with a missing or wrong file name). May you please supply a ChangeLog entry? I am not sure if I understand the purpose of each change in the diff. Also, it looks like you introduce some DWIM behaviour for auto-generating @direntry contents. Such new behaviour ought to be documented in the manual and announced in the news. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-02-28 10:35 ` Ihor Radchenko @ 2024-03-02 20:01 ` Stefan Monnier 2024-03-04 11:09 ` Ihor Radchenko 0 siblings, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2024-03-02 20:01 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 338 bytes --] > May you please supply a ChangeLog entry? I am not sure if I understand > the purpose of each change in the diff. > > Also, it looks like you introduce some DWIM behaviour for auto-generating > @direntry contents. Such new behaviour ought to be documented in the > manual and announced in the news. New patch attached, Stefan [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-ox-texinfo-Require-only-TEXINFO_DIR_CATEGORY.patch --] [-- Type: text/x-diff, Size: 10155 bytes --] From 6cb66a8737adc8efdb053bd76607289dc120d60b Mon Sep 17 00:00:00 2001 From: Stefan Monnier <monnier@iro.umontreal.ca> Date: Sat, 2 Mar 2024 14:48:29 -0500 Subject: [PATCH] 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 @@ 'texinfo (: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 @@ org-texinfo-coding-system "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 @@ org-texinfo-classes 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 @@ org-texinfo-format-headline-function 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 @@ org-texinfo-node-description-column "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 @@ org-texinfo-table-scientific-notation \(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 @@ org-texinfo-table-default-markup \"@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 @@ org-texinfo-text-markup-alist 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 @@ org-texinfo-format-drawer-function 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 @@ org-texinfo-format-inlinetask-function 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 @@ org-texinfo-with-latex 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 @@ org-texinfo-compact-itemx 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 @@ org-texinfo-info-process 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 @@ org-texinfo-logfiles-extensions '("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 @@ org-texinfo-template (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 @@ org-texinfo-planning (concat "@noindent" (mapconcat - 'identity + #'identity (delq nil (list (let ((closed (org-element-property :closed planning))) -- 2.43.0 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-02 20:01 ` Stefan Monnier @ 2024-03-04 11:09 ` Ihor Radchenko 2024-03-04 16:16 ` Stefan Monnier 0 siblings, 1 reply; 12+ messages in thread From: Ihor Radchenko @ 2024-03-04 11:09 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-orgmode Stefan Monnier <monnier@iro.umontreal.ca> writes: >> May you please supply a ChangeLog entry? I am not sure if I understand >> the purpose of each change in the diff. >> >> Also, it looks like you introduce some DWIM behaviour for auto-generating >> @direntry contents. Such new behaviour ought to be documented in the >> manual and announced in the news. > > New patch attached, Thanks! See my comments inline. > * lisp/org/ox-texinfo.el: Remove redundant `:group` arguments. > Prefer #' to quote function names. May you please split unrelated changes into a separate patch? > * doc/misc/org.org (Texinfo specific export settings): Adjust accordingly. It would be nice to provide etc/ORG-NEWS entry as well. > #+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).~. This example is a bit confusing. How will it look like in Org document? #+TEXINFO_DIR_TITLE: * title: (filename). ? If yes, it is confusing because you just mention that default value is filename, but you have both "title" and "filename" in the example. Maybe : #+TEXINFO_DIR_TITLE: * name: (filename). ? > - =TEXINFO_DIR_DESC= :: > > #+cindex: @samp{TEXINFO_DIR_DESC}, keyword > The directory description of the document. > + Defaults to the title of the document. I'd also add that it should be a short sentence. > (: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. What about TEXINFO_DIR_NAME + TECINFO_DIR_DESC? I do not see a big problem with description defaulting to document title given that it should be a short sentence - an equivalent of proper document title. > + ;; 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"? Sounds reasonable. We may add a new custom option with default category. > + (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)) It would be nice to add a comment saying that dt values like "Foo (filename)" are already captured by the previous cond clause. > + (t (format "* %s." file))))) What if dt is "Foo."? -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-04 11:09 ` Ihor Radchenko @ 2024-03-04 16:16 ` Stefan Monnier 2024-03-05 12:49 ` Ihor Radchenko 0 siblings, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2024-03-04 16:16 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs-orgmode >> * doc/misc/org.org (Texinfo specific export settings): Adjust accordingly. > It would be nice to provide etc/ORG-NEWS entry as well. Yes, thanks. >> #+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).~. > > This example is a bit confusing. How will it look like in Org document? > #+TEXINFO_DIR_TITLE: * title: (filename). ? > If yes, it is confusing because you just mention that default value is > filename, but you have both "title" and "filename" in the example. > > Maybe > > : #+TEXINFO_DIR_TITLE: * name: (filename). > > ? [ Calling it "TITLE" is definitely confusing, I should use DIRTITLE. ] And yes, the Texinfo syntax is either * FILENAME. or * DIRTITLE: (FILENAME). [ where FILENAME which should be the file name without the `.info` extension). ] so I think it makes a lot sense for DIRTITLE to default to FILENAME? The "* DIRTITLE: (FILENAME)." syntax is Texinfo's syntax, and currently the Org user needs to know that syntax and abide by it (even though it's not well defined nor well documented, IME). My change mostly makes it unnecessary for the user to know that syntax because ox-texinfo already knows the FILENAME, so it only needs the DIRTITLE. The new code supports the "* DIRTITLE: (FILENAME)." syntax mostly for backward compatibility, tho it can also be useful in corner cases such as when the final filename will be different than the one ox-texinfo knows about. Not sure how to adjust the text to clarify that, without including a discussion of the "* DIRTITLE: (FILENAME)." and how things used to be, and how the filename is controlled. The old(current) situation is arguably worse because it doesn't even document the syntax that needs to be used. >> - =TEXINFO_DIR_DESC= :: >> >> #+cindex: @samp{TEXINFO_DIR_DESC}, keyword >> The directory description of the document. >> + Defaults to the title of the document. > > I'd also add that it should be a short sentence. Not sure if it needs to be a sentence, but yes, it should usually be short tho I don't think there's a technical need for it, so I think the "defaults to the title" should be a good enough hint about the kind of length expected. >> (: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. > What about TEXINFO_DIR_NAME + TECINFO_DIR_DESC? Fine by me, yes. > I do not see a big problem with description defaulting to document title > given that it should be a short sentence - an equivalent of proper > document title. I don't see a problem with it either. The problem is mostly in the DIR_TITLE name suggesting it should be like the title rather than the indexing keyword that it is. >> + (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)) > > It would be nice to add a comment saying that dt values like > "Foo (filename)" are already captured by the previous cond clause. I don't understand what you mean by that. >> + (t (format "* %s." file))))) > > What if dt is "Foo."? Good point. Stefan ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-04 16:16 ` Stefan Monnier @ 2024-03-05 12:49 ` Ihor Radchenko 2024-03-05 19:27 ` Stefan Monnier 0 siblings, 1 reply; 12+ messages in thread From: Ihor Radchenko @ 2024-03-05 12:49 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-orgmode Stefan Monnier <monnier@iro.umontreal.ca> writes: > The "* DIRTITLE: (FILENAME)." syntax is Texinfo's syntax, and currently the > Org user needs to know that syntax and abide by it (even though it's > not well defined nor well documented, IME). My change mostly makes it > unnecessary for the user to know that syntax because ox-texinfo already > knows the FILENAME, so it only needs the DIRTITLE. If it is not well-documented, we may as well help users by explaining a bit in a footnote in the Org manual. > The new code supports the "* DIRTITLE: (FILENAME)." syntax mostly for > backward compatibility, tho it can also be useful in corner cases such > as when the final filename will be different than the one ox-texinfo > knows about. > > Not sure how to adjust the text to clarify that, without including > a discussion of the "* DIRTITLE: (FILENAME)." and how things used to be, > and how the filename is controlled. ... then we can also include this discussion in a footnote and put the new syntax into the main visible part of the manual. > The old(current) situation is arguably worse because it doesn't even > document the syntax that needs to be used. Agree. >>> - =TEXINFO_DIR_DESC= :: >>> >>> #+cindex: @samp{TEXINFO_DIR_DESC}, keyword >>> The directory description of the document. >>> + Defaults to the title of the document. >> >> I'd also add that it should be a short sentence. > > Not sure if it needs to be a sentence, but yes, it should usually be > short tho I don't think there's a technical need for it, so I think the > "defaults to the title" should be a good enough hint about the kind of > length expected. Also ok. I do not have a strong opinion here - referring to title is also clear enough for me; I am just not sure if it is clear enough for all the readers of the manual. >>> (: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. >> What about TEXINFO_DIR_NAME + TECINFO_DIR_DESC? > > Fine by me, yes. I can add it after we finalize your patch. Or you can do it as a part of the patch, if you are willing to. (Just make sure that old keyword name is supported for backwards-compatibility) >>> + (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)) >> >> It would be nice to add a comment saying that dt values like >> "Foo (filename)" are already captured by the previous cond clause. > > I don't understand what you mean by that. I had a hard time understanding why the second clause of `cond' never matches things like "Foo (filename)" - the test (equal dt file) looks suspicious from the first glance; until I spend some time parsing the above regexps. So, I am asking you to add code comment explaining why (equal dt file) is sufficient. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-05 12:49 ` Ihor Radchenko @ 2024-03-05 19:27 ` Stefan Monnier 2024-03-06 11:17 ` Ihor Radchenko 0 siblings, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2024-03-05 19:27 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 82 bytes --] New version of the patch, which I believe address your comments. Stefan [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-lisp-org-ox-texinfo.el-Remove-redundant-group-s.patch --] [-- Type: text/x-diff, Size: 5470 bytes --] From 53c8fab18625e8a722657181cb3c825a1d8c895c 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/org/ox-texinfo.el: Remove redundant `:group`s --- lisp/org/ox-texinfo.el | 22 ++-------------------- 1 file changed, 2 insertions(+), 20 deletions(-) diff --git a/lisp/org/ox-texinfo.el b/lisp/org/ox-texinfo.el index 84313645e6e..b3b94511d50 100644 --- a/lisp/org/ox-texinfo.el +++ b/lisp/org/ox-texinfo.el @@ -147,12 +147,10 @@ org-texinfo-coding-system "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 @@ org-texinfo-classes 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 @@ org-texinfo-format-headline-function 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 @@ org-texinfo-node-description-column "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 @@ org-texinfo-table-scientific-notation \(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 @@ org-texinfo-table-default-markup \"@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 @@ org-texinfo-text-markup-alist 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 @@ org-texinfo-format-drawer-function 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 @@ org-texinfo-format-inlinetask-function 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 @@ org-texinfo-with-latex 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 @@ org-texinfo-compact-itemx 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 @@ org-texinfo-info-process 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 @@ org-texinfo-logfiles-extensions '("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 @@ -1590,7 +1572,7 @@ org-texinfo-planning (concat "@noindent" (mapconcat - 'identity + #'identity (delq nil (list (let ((closed (org-element-property :closed planning))) -- 2.43.0 [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #3: 0002-ox-texinfo-Always-provide-a-direntry.patch --] [-- Type: text/x-diff, Size: 7658 bytes --] From 1318e575eb4b3602c7e26c4bdf1f6176ca1367f1 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/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. --- doc/misc/org.org | 22 +++++++++++--- etc/ORG-NEWS | 7 +++++ lisp/org/ox-texinfo.el | 65 +++++++++++++++++++++++++++++------------- 3 files changed, 70 insertions(+), 24 deletions(-) diff --git a/doc/misc/org.org b/doc/misc/org.org index 05ab5b36ca0..14000dc7a53 100644 --- a/doc/misc/org.org +++ b/doc/misc/org.org @@ -15316,17 +15316,31 @@ 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_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. - =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 +15436,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 +15844,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/etc/ORG-NEWS b/etc/ORG-NEWS index d07ce53ab20..b58d2fe6db4 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -431,6 +431,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/org/ox-texinfo.el b/lisp/org/ox-texinfo.el index b3b94511d50..de5f87fa029 100644 --- a/lisp/org/ox-texinfo.el +++ b/lisp/org/ox-texinfo.el @@ -110,7 +110,8 @@ 'texinfo (: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 @@ org-texinfo-template (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 (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 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-05 19:27 ` Stefan Monnier @ 2024-03-06 11:17 ` Ihor Radchenko 2024-03-06 15:00 ` Stefan Monnier 0 siblings, 1 reply; 12+ messages in thread From: Ihor Radchenko @ 2024-03-06 11:17 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-orgmode Stefan Monnier <monnier@iro.umontreal.ca> writes: > New version of the patch, which I believe address your comments. Thanks! The patches are against Emacs git repository, not against Org mode. May your please port them? See some more minor comments inline. > 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. > ... > * 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. > +- =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. Also, please update "Info directory file" section. In particular, references to TEXINFO_DIR_TITLE. > + (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). -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-06 11:17 ` Ihor Radchenko @ 2024-03-06 15:00 ` Stefan Monnier 2024-03-07 13:46 ` Ihor Radchenko 0 siblings, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2024-03-06 15:00 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 1984 bytes --] > 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 [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-lisp-ox-texinfo.el-Remove-redundant-group-s.patch --] [-- Type: text/x-diff, Size: 5664 bytes --] 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 [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #3: 0002-ox-texinfo-Always-provide-a-direntry.patch --] [-- Type: text/x-diff, Size: 8675 bytes --] 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 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-06 15:00 ` Stefan Monnier @ 2024-03-07 13:46 ` Ihor Radchenko 2024-03-08 8:09 ` Stefan Monnier 0 siblings, 1 reply; 12+ messages in thread From: Ihor Radchenko @ 2024-03-07 13:46 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-orgmode Stefan Monnier <monnier@iro.umontreal.ca> writes: >> The patches are against Emacs git repository, not against Org mode. May >> your please port them? > > See attached. Thanks! Unfortunately, the patch causes some tests (make test) to fail. Looks like export to temporary buffer is broken (temporary buffer does not have a filename): 2 unexpected results: FAILED test-ox-texinfo/end-to-end-inline stringp FAILED test-ox-texinfo/end-to-end-sanity-check-displayed stringp > Subject: [PATCH 1/2] lisp/ox-texinfo.el: Remove redundant `:group`s > > '("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." ^^ stray newline. > --- 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. This is under Org 9.6 header, while should be under Org 9.7 (not yet released). -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-07 13:46 ` Ihor Radchenko @ 2024-03-08 8:09 ` Stefan Monnier 2024-03-08 10:49 ` Ihor Radchenko 0 siblings, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2024-03-08 8:09 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 586 bytes --] > Thanks! > Unfortunately, the patch causes some tests (make test) to fail. > Looks like export to temporary buffer is broken (temporary buffer does > not have a filename): > > 2 unexpected results: > FAILED test-ox-texinfo/end-to-end-inline stringp > FAILED test-ox-texinfo/end-to-end-sanity-check-displayed stringp [...] > ^^ stray newline. [...] > This is under Org 9.6 header, while should be under Org 9.7 (not yet > released). I fixed those three issues (I still get test failures, but I get the same with or without my patch 🙂). Stefan [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-lisp-ox-texinfo.el-Remove-redundant-group-s.patch --] [-- Type: text/x-diff, Size: 5612 bytes --] From 11a40ce47b104609c003c7b9d871db1f2f26be67 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 | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el index bd01effaa6..d74ed50033 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" @@ -417,7 +399,6 @@ the output file." "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 +1572,7 @@ information." (concat "@noindent" (mapconcat - 'identity + #'identity (delq nil (list (let ((closed (org-element-property :closed planning))) -- 2.43.0 [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #3: 0002-ox-texinfo-Always-provide-a-direntry.patch --] [-- Type: text/x-diff, Size: 8667 bytes --] From 0a0119112c82424a59e2c8132ddb1674b010f85c 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 (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" -- 2.43.0 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: Provide sane default for the @direntry 2024-03-08 8:09 ` Stefan Monnier @ 2024-03-08 10:49 ` Ihor Radchenko 0 siblings, 0 replies; 12+ messages in thread From: Ihor Radchenko @ 2024-03-08 10:49 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-orgmode Stefan Monnier <monnier@iro.umontreal.ca> writes: > I fixed those three issues (I still get test failures, but I get the > same with or without my patch 🙂). Applied, onto main. https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=4fd869194 https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=b0c3c9057 If you are getting failures on make test, please report them. There should not be any, normally. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92> ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2024-03-08 10:46 UTC | newest] Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2024-02-28 0:19 Provide sane default for the @direntry Stefan Monnier 2024-02-28 10:35 ` Ihor Radchenko 2024-03-02 20:01 ` Stefan Monnier 2024-03-04 11:09 ` Ihor Radchenko 2024-03-04 16:16 ` Stefan Monnier 2024-03-05 12:49 ` Ihor Radchenko 2024-03-05 19:27 ` Stefan Monnier 2024-03-06 11:17 ` Ihor Radchenko 2024-03-06 15:00 ` Stefan Monnier 2024-03-07 13:46 ` Ihor Radchenko 2024-03-08 8:09 ` Stefan Monnier 2024-03-08 10:49 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).