From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id wJ6LKemF42Uz4wAAe85BDQ:P1 (envelope-from ) for ; Sat, 02 Mar 2024 21:02:49 +0100 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id wJ6LKemF42Uz4wAAe85BDQ (envelope-from ) for ; Sat, 02 Mar 2024 21:02:49 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=iro.umontreal.ca header.s=mail header.b=ANAYn5n9; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=quarantine) header.from=iro.umontreal.ca ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1709409769; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=rqAlXJAXzjZw52to8LvuVgviSAfH1ghROMS/s7kOL04=; b=ZUoE+scMkznJ2v3Kgec97KV2jrejrY1vT9/6wVSPsnwrqZfzGjwjV7lFrnGOM26/dYydcX LwRhFOfmFMYYB4YnKfKdvL6kYUmr2blYEqm63+Ol8JdZUepgbC5xE27Qw4SiGD+g6Wj72H HOtmHlboByk18QURidl0XOCU7vxKEhLRzM4yBWj2eXbf1sa1VDUsDW08wOcUiZXWfNGWvD +oslAZuk/cq3kRGTTm/1peuq/CytxXLMceVtdNJGXu2bygBVLqprUX4EdzHu2bIeVFkThV CknpsIIjTa/61pDw5NY09M/Esv+FkK1zh1xR60ohrrOs5O36of1A8bYAia96wQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=iro.umontreal.ca header.s=mail header.b=ANAYn5n9; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=quarantine) header.from=iro.umontreal.ca ARC-Seal: i=1; s=key1; d=yhetil.org; t=1709409769; a=rsa-sha256; cv=none; b=CkOt2XACrL4znI2BTEJxhdZ4LwuJ8Fn8PBHyeuG+Y2UkSyLvH09WEa7AZZ5/Z3daOmDyD7 ztc9TAnX6A5oOsGzJryU9ei1ZpqISiir+W9fbSWTwXEqFKb8uVCqQv8Cmc5CG58JQSZfWc udDRDQ8g/w18TQTDWMXdr0IUaOJJRYyO61d8dvJDT9+gGZ7zq//m3MhoWmT3cjUf9KAr7U k9oeR5nZq7xUqDv6PHxQ5PtYXvA9NAhh7qleBSYZedJwDornJQdgJo+6rmzSEfMNv8Ylrt YNuPQlvrQqzjVI2Ib1tPEiyj6JSKoghEaSOr1yhwkV3IksweUljjr2KWseisnA== Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id ABE43232F9 for ; Sat, 2 Mar 2024 21:02:48 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rgVYN-0002bn-R1; Sat, 02 Mar 2024 15:01:51 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rgVYK-0002bZ-1d for emacs-orgmode@gnu.org; Sat, 02 Mar 2024 15:01:49 -0500 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rgVYH-0001Pa-Gk for emacs-orgmode@gnu.org; Sat, 02 Mar 2024 15:01:47 -0500 Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id D0C6B442AA6; Sat, 2 Mar 2024 15:01:42 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1709409700; bh=UAilXcd76xc175K8V4BPawVu+MuQiS4DXKgpgCv0fM0=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=ANAYn5n9pWdueDH19T7fuG7xBM0VDMEOCP8qMs71WWdSDb8R9orCPNl6rVZ7FDm7s 39K+sVpS36opRuyfnJfwDPWwf6cKtYExmwWJaiUEAXwSFMSEdV9KlEqUCuNjN8x/z1 O9GWGQUQJQ6iOae86yrQHtZ17QPP9cpTbQSGWgmCwfdr0AurD8LFxXXsl5PQ2cbmWU gKDx4OZFOUGmQ3O2ZRrFO1tE77O1Tvu30oOeK6mdl/V/TOaZIy+0dPpQerudpwysuw 1YxOAw4NyTpEmu79YgScETdyJiDOqsEX9lTnzfsBmoLBOf7ulW86cvokXxQ0D9vT51 v1CDtn42X9Y5Q== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 159E7442AA7; Sat, 2 Mar 2024 15:01:40 -0500 (EST) Received: from pastel (unknown [216.154.1.84]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id E4C901204F5; Sat, 2 Mar 2024 15:01:39 -0500 (EST) From: Stefan Monnier To: Ihor Radchenko Cc: emacs-orgmode@gnu.org Subject: Re: Provide sane default for the @direntry In-Reply-To: <87v868khb2.fsf@localhost> (Ihor Radchenko's message of "Wed, 28 Feb 2024 10:35:13 +0000") Message-ID: References: <87v868khb2.fsf@localhost> Date: Sat, 02 Mar 2024 15:01:39 -0500 User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Scanner: mx10.migadu.com X-Migadu-Spam-Score: -10.15 X-Spam-Score: -10.15 X-Migadu-Queue-Id: ABE43232F9 X-TUID: Uhgv/XuVTDGf --=-=-= Content-Type: text/plain > 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 --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-ox-texinfo-Require-only-TEXINFO_DIR_CATEGORY.patch >From 6cb66a8737adc8efdb053bd76607289dc120d60b Mon Sep 17 00:00:00 2001 From: Stefan Monnier 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 --=-=-=--