From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id 6JwXLBj05WVQgAAA62LTzQ:P1 (envelope-from ) for ; Mon, 04 Mar 2024 17:17:28 +0100 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id 6JwXLBj05WVQgAAA62LTzQ (envelope-from ) for ; Mon, 04 Mar 2024 17:17:28 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=iro.umontreal.ca header.s=mail header.b="i2SFGrB/"; 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=1709569048; 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=soKGxWx4OiQZ4uq4/7bDu+W47GahaKJwJ+K7D6v8+qM=; b=unskyE6lfLIugosyrdCFkt4TYTv4kszrCWTyR8o+dwhTtDsuBBqK/1Zuk0zWP/1ilFr8ys D/zWx/i3lH08YkmsF2E9h+92O+f0OXTsNs1zoc0w7vwL4gmIq4fZ9xYkX64fK1c2NNVPx0 hPYq7vGwxp7Ce9K0LuJ1/g5N9MN/CEJfQhdTYmlwWHPEKI4ikEU+1KNxbBLNUYqEZ8NkI5 HSASTSYvrWjmGtb9x4mPod5JndMEFLVxFBMDOAW6XetbkuxthKgGmNzl2KE/kf1vFgzjQq JqBTb1SJPkjdo3mrVO//Ja4+zo8ceGkwo5m4S702L2iK8z+/71ALrw6szm8VKQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=iro.umontreal.ca header.s=mail header.b="i2SFGrB/"; 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=1709569048; a=rsa-sha256; cv=none; b=mEzaxGFLP2iiMCRnYdHj+CJKsSsHRyG9sO4ghGKvlywPaYG7IQgnvf8CDXU9wx36AZEpA4 G9MvfkZ/ZdCyuCvEvgIhrRAHVMLJXi7ak4eM/boGfGbTQA6607p3OkxQn/qFskPped9Y+P Jg4NUGjM7Up8YoAEs7uwCd/p8Fb6l0W3qkgCcubHzUpQeEGydFxFJm8J7nXrA4LJyLDRpz MDSXZ7+MN3gxuoZQIrFzMJYsfxqdvVqXFv8lL1cHbdPaS3dRDeQtZmV63B/OGBT4trDBWs i+jpF+22y+/RNL+/hrG5KFC7Yx8Mn8IoC3QzFAvEn1dHAp0y86v3FLv+Gu8yHQ== 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 786026DCE4 for ; Mon, 4 Mar 2024 17:17:28 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rhAzW-0007mn-Ej; Mon, 04 Mar 2024 11:16:38 -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 1rhAzV-0007mb-8X for emacs-orgmode@gnu.org; Mon, 04 Mar 2024 11:16:37 -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 1rhAzT-0000Ah-7b for emacs-orgmode@gnu.org; Mon, 04 Mar 2024 11:16:36 -0500 Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id B2EE644498D; Mon, 4 Mar 2024 11:16:33 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1709568991; bh=I67YOA1Y5Ib7WbGojILvztfYq1h7N1HgmzOKJ+3OFc4=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=i2SFGrB/3fVj5cFR7gZPB7z4tXUY+TDQtc/SdhcHlG3NoM1y23QoatpvbRr8ZI5VY Zo8wpl1LD6YwFkPcr5HrmrNISMg9DnpkS7zoXks70mIvVrW4knco1pBdhnEIc8iWI9 kHdfi4kDCqekfRvW3x5mDos7GHuMmW0ANlFaKV9IlpyMvDZRAE9+W0/njd2WgBu1gB 5r6UL5m9xKoiKItn++ZzDZRmLcJX3kTIEuD9zQF7t4QIojk8+F0fTRG/JgXL2u90pW 65EAv8vlDa57DX4zmraSD74b6SsA7cwvB5VxBWelvg5im4OUzM5eGIZIYlMwE13O5P iciBcVCJ0klhg== Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id C5BAD44497D; Mon, 4 Mar 2024 11:16:31 -0500 (EST) Received: from pastel (unknown [104.247.233.29]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id A33D4120857; Mon, 4 Mar 2024 11:16:31 -0500 (EST) From: Stefan Monnier To: Ihor Radchenko Cc: emacs-orgmode@gnu.org Subject: Re: Provide sane default for the @direntry In-Reply-To: <871q8q1cfd.fsf@localhost> (Ihor Radchenko's message of "Mon, 04 Mar 2024 11:09:10 +0000") Message-ID: References: <87v868khb2.fsf@localhost> <871q8q1cfd.fsf@localhost> Date: Mon, 04 Mar 2024 11:16:22 -0500 User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain 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-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: -10.51 X-Spam-Score: -10.51 X-Migadu-Queue-Id: 786026DCE4 X-Migadu-Scanner: mx11.migadu.com X-TUID: tNE3mPlTjyIi >> * 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