From: Stefan Monnier <monnier@iro.umontreal.ca>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: emacs-orgmode@gnu.org
Subject: Re: Provide sane default for the @direntry
Date: Sat, 02 Mar 2024 15:01:39 -0500 [thread overview]
Message-ID: <jwvv864h09c.fsf-monnier+emacs@gnu.org> (raw)
In-Reply-To: <87v868khb2.fsf@localhost> (Ihor Radchenko's message of "Wed, 28 Feb 2024 10:35:13 +0000")
[-- 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
next prev parent reply other threads:[~2024-03-02 20:02 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=jwvv864h09c.fsf-monnier+emacs@gnu.org \
--to=monnier@iro.umontreal.ca \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).