From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id GDxeNPD53mKsdQEAbAwnHQ (envelope-from ) for ; Mon, 25 Jul 2022 22:15:44 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id SP9RNPD53mKP8wAAauVa8A (envelope-from ) for ; Mon, 25 Jul 2022 22:15:44 +0200 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 E6EBC2B58B for ; Mon, 25 Jul 2022 22:15:43 +0200 (CEST) Received: from localhost ([::1]:51008 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oG4UQ-0006yG-MM for larch@yhetil.org; Mon, 25 Jul 2022 16:15:42 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:39018) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oG4T6-0006xu-Rn for emacs-orgmode@gnu.org; Mon, 25 Jul 2022 16:14:20 -0400 Received: from zimbra.cs.ucla.edu ([131.179.128.68]:37740) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oG4T4-0006Ux-Fa for emacs-orgmode@gnu.org; Mon, 25 Jul 2022 16:14:20 -0400 Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 10DD0160051; Mon, 25 Jul 2022 13:14:13 -0700 (PDT) Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id oFBytx98JVcZ; Mon, 25 Jul 2022 13:14:10 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id A68FB16005C; Mon, 25 Jul 2022 13:14:10 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id yKsRb4uCp11f; Mon, 25 Jul 2022 13:14:10 -0700 (PDT) Received: from [192.168.1.9] (cpe-172-91-119-151.socal.res.rr.com [172.91.119.151]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 7C9D3160051; Mon, 25 Jul 2022 13:14:10 -0700 (PDT) Message-ID: Date: Mon, 25 Jul 2022 13:14:09 -0700 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.11.0 Content-Language: en-US To: Ihor Radchenko Cc: emacs-orgmode@gnu.org References: <20220724170720.46921-1-eggert@cs.ucla.edu> <87k081vams.fsf@localhost> From: Paul Eggert Organization: UCLA Computer Science Department Subject: Re: [PROPOSED-PATCH] Fix doc string quoting problems with ' In-Reply-To: <87k081vams.fsf@localhost> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Received-SPF: pass client-ip=131.179.128.68; envelope-from=eggert@cs.ucla.edu; helo=zimbra.cs.ucla.edu X-Spam_score_int: -41 X-Spam_score: -4.2 X-Spam_bar: ---- X-Spam_report: (-4.2 / 5.0 requ) BAYES_00=-1.9, NICE_REPLY_A=-0.001, 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" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1658780144; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=5UbPQ+E1Bo78Vxx9sNIXbuEOnOdRZGCzfw2MY8Ktadw=; b=d5OKH049w+07ofMyB9vZtpqkKtEIrRHfPlLK8TA7AIAmNjpa0r5bP1v6TGSPE7LF6SAmxh tC1h7zzxiM4socOSeutfj4T2ALoxiw4rtC3pOnjr6cE8s0BexaM0bbrBin1tmRQudfT231 23IHpYAXLxoasNoe6omUGxy4DBOhX8Yy8Zh401Z0PW9dB7DhI3w6dRkKqAnt05f5k/OK9p qe8tjgTeYV8MdPclCSVV5VjEatTxbRSZ5rH54FiX1wA4wqo45YbS29GpqPYfniQ7GtGj20 gx+UMddJcIK6Z8pSDWgYfw6VTwBpQEIKzIzfka25gWYTN2nxP8WdWTrpO4bPhw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1658780144; a=rsa-sha256; cv=none; b=p/mWOif0+JW5iNFFsgy0KwbQ2YPt8wxbP4wl5DPuVmUHhh9n0hxos51vjDueoqo6LGHZIz NBE/qmG0z06eEEJwOo6xbAS1MCc5uDEx0cqxArviBfFA8ki7riTlTQMZCWhNE2XKAvdGf4 BC4hBW4U4ioMFz7laqyAc4ZHj7M34jehd1tBaKsvyXZnHawxNIzjjRU6h/B43/jlPlNAGU nyL2jp2SyQ4SUw8QCo8y+MnbAZx1Fm7ku7WIozBZtPL0U0TbyG4POV/v+oL/V8cHSs33pv pBgvgOeWnWKnBwnkvYaTXLr+f7YuAaVcf8MdYWW3m7X21wAnfKtqYc45/pIstA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; 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" X-Migadu-Spam-Score: -3.23 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; 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" X-Migadu-Queue-Id: E6EBC2B58B X-Spam-Score: -3.23 X-Migadu-Scanner: scn0.migadu.com X-TUID: /gQXvuc9Z5ye On 7/25/22 01:50, Ihor Radchenko wrote: > The conventions sound reasonable, though I do not think that they are > documented in D.6 Tips for Documentation Strings section of the Elisp > manual. Thanks, I added the following to the Elisp manual to try to fix that: https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=d04701c0c4959d3c42587a4e1277bb517a2ea04b > I am not sure if it is a > good idea to change explicit 'symbol or '(...) mentions in the > documentation of the defcustoms. In particular, when 'symbol is intended > to be set as (setq variable 'symbol), I feel that 'symbol should be > preferred over `symbol' - it will make life easier for users who can > then just copy-paste the text from docstring. OK, I went with a more conservative route there, e.g., replacing this: \\='((?R set-category get-category)) with this: (setq org-agenda-bulk-custom-functions \\='((?R set-category get-category))) Although wordier, this follows the doc string guidelines and should make it clear why the apostrophe is present. > Also, note that references in the babel documentation are _not_ Elisp > symbols - they are defined in #+name: name lines at the relevant src > blocks. Yes, I left those alone. Here's what I installed: https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=6013cb161d6f186829f6bfcfc5dd927c6cb89b49