From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id wHP6MIVZ3mLV4AAAbAwnHQ (envelope-from ) for ; Mon, 25 Jul 2022 10:51:17 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id SGkFMIVZ3mJtHAEAG6o9tA (envelope-from ) for ; Mon, 25 Jul 2022 10:51:17 +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 A5467C09F for ; Mon, 25 Jul 2022 10:51:16 +0200 (CEST) Received: from localhost ([::1]:54166 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oFto3-0002Dq-7n for larch@yhetil.org; Mon, 25 Jul 2022 04:51:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34318) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oFtmf-0002B3-KX for emacs-orgmode@gnu.org; Mon, 25 Jul 2022 04:49:51 -0400 Received: from mail-pg1-x536.google.com ([2607:f8b0:4864:20::536]:36414) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oFtme-0005RT-3H for emacs-orgmode@gnu.org; Mon, 25 Jul 2022 04:49:49 -0400 Received: by mail-pg1-x536.google.com with SMTP id s206so9790690pgs.3 for ; Mon, 25 Jul 2022 01:49:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:in-reply-to:references:date:message-id :mime-version; bh=mo6gS+cIiZe5A9t2Z4P3TM1G4pGmyPE3/uOGqFX0Iic=; b=ZRot5eCli0MD3eWlqLSiQdQhRKXKYrZeGD1F3miMkQxqX1FfnoexNDwQVuq0fe7V8N SNHk+gMwpItiHFdSgjASDKxu1NTqfbAMnGHujRlOvL0YkCm2GIfL7KNeaWHfZ6A+UPNL r+y0KCVUyGx/9476fdfIE+EFLtySKMZI5vLngQrCfgM4eUbWRqgqmpHr92qY5mHJAMjf GU49B8PoMOMVwjTVdKOGtNXqRJ2HXvIPoy4XIM6YIOyVrPIqtHd3VW0qzabH/FH44SGl mBt4vz2+a+alYF4bnw8Y5KVIo22fJXmYsRhKRp9U9g06X+bwENIzQknTfohhpQHI6OMR oyeg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references:date :message-id:mime-version; bh=mo6gS+cIiZe5A9t2Z4P3TM1G4pGmyPE3/uOGqFX0Iic=; b=RNvQMvmBfnBahVVFypyF59PQCYE9Xil2EdopsIPjOB+fVrVdP03WxbqNpqgY4CmCdm dOsz7Yw7aok+LUyiqo4C/9+pb98Ljy3C/A4je8Rwe70QuYeYAQGLYzJ6uZJoJVXDhzBw U6pKfG4HYWH2YY9rDST7t7Sl1gT4fnZCa44rGPUOScL+4mFpioYiPVXSETx+diWwRJZg 3YKhhk2yWStLxbhiX3yu8hTlSGKvDjhwueTB6sIcHyEFwuiEzxKClkQKM17fxPb1/68T BSvseaLIvvJKOcyQBXHoVVq512RHs6kgrKU83dBbH0xdj3WR/JmV3hgmFnjra0pBjVMz 4TMA== X-Gm-Message-State: AJIora9gzjKbESAoZtj9nPcFGrz9abXENG6LfL6B2tboXsutcvergPss ZIKPZ3vaHmjVZWutNtl/c+Q= X-Google-Smtp-Source: AGRyM1s/IXaUnLRFqzgVN2A9yTTRD//5j5dxw0AzO4j/KwHfX+YUdNIAq9iQzR7W8HMqrOS8hTPakA== X-Received: by 2002:a63:550:0:b0:413:8c29:e9ed with SMTP id 77-20020a630550000000b004138c29e9edmr9828574pgf.180.1658738986205; Mon, 25 Jul 2022 01:49:46 -0700 (PDT) Received: from localhost ([115.154.175.57]) by smtp.gmail.com with ESMTPSA id h3-20020a17090a648300b001f291c9d3bdsm2825910pjj.48.2022.07.25.01.49.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 25 Jul 2022 01:49:45 -0700 (PDT) From: Ihor Radchenko To: Paul Eggert Cc: emacs-orgmode@gnu.org Subject: Re: [PROPOSED-PATCH] Fix doc string quoting problems with ' In-Reply-To: <20220724170720.46921-1-eggert@cs.ucla.edu> References: <20220724170720.46921-1-eggert@cs.ucla.edu> Date: Mon, 25 Jul 2022 16:50:51 +0800 Message-ID: <87k081vams.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::536; envelope-from=yantar92@gmail.com; helo=mail-pg1-x536.google.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, 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=1658739076; 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=mo6gS+cIiZe5A9t2Z4P3TM1G4pGmyPE3/uOGqFX0Iic=; b=hkUR5orbTNhbqTOwWZv2hLmneWIL6fKEBxAvM8zv8m1o6OD28S5oVIAzIEu+RmCogkSIlR brjmARf7Dmx4WkIoXL4/SkVDGk0POBgnKLNZxBEC+Z42YkW6EvHmU4Hdl6HsHtPRD5/gyt XK1/xLEvXGwfDxwkO09tHAQLagEPmWat2zCSbXhdhxOXDxM6FSVPuw+tNZdEBrpY3qrNSp 0WRZVNCW63BKlrMEZBHRie2QYsSfKKQXSiy2wIh25+NYUg1Wk3JQcHIeC3WIecJcFuRbRz YF0my9gICSdf9ryACokEzHIXqYj2qJYlvrAfMY5kM91D6/W0Obh8qlflj8XnHg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1658739076; a=rsa-sha256; cv=none; b=BKynufLUAJ8zUKrNbnaFi7vZ/2cHHM9L+SWiDqQQEGVsg1TjyGBv8yK9gKTkDTfm88zVWK 74Nr26WCcDEWZGL2cbPt86rh3ANZRLDA2J2braI9uU1/Bn+gb/s9IM8KthEFMqHw8UbYqm kuMGk/oI3oASs7GZ6NL2xrx5Z2qemoJbBfeKBKMA8UXBEczyUkptLW/19yjrHbnxTBfxu7 w64UfVt5GxMoPiTIOXVSJh7+wIDWHZzLZtLa8dcTa+s1S3XtL7ZbZae9RtF/QZ6HdzEGRs XWaFJ9LdzKlTKQ7zHQVMStlJqvSbBzb+xGifWCJFeT82A0ZkLY2vkLknUX3j6A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=ZRot5eCl; dmarc=pass (policy=none) header.from=gmail.com; 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: -1.93 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=ZRot5eCl; dmarc=pass (policy=none) header.from=gmail.com; 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: A5467C09F X-Spam-Score: -1.93 X-Migadu-Scanner: scn1.migadu.com X-TUID: ULNhs5VyBj01 Paul Eggert writes: > The Emacs doc string convention is to document values as-is when that > is clear, and surrounded by `single quotes' otherwise. For example, a > doc string "(a b c)" stands for a list of symbols, and the doc string > "`a'" stands for a single symbol. The doc string "\\=`a" is typically > not correct for that single symbol, because that is equivalent to > "(quote a)" and the typical intent is to talk about the symbol, not > about the Lisp quoting construct. One needs "\\=`X" only when talking > about something intended to be equivalent to "(quote X)", as in the > doc string "(provide \\='org-xyz)". Thanks for the patch! 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. The patch looks good in general, however 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. Also, note that references in the babel documentation are _not_ Elisp symbols - they are defined in #+name: name lines at the relevant src blocks. Finally, note that your patch does not apply after Kyle backported similar changes from Emacs master. Best, Ihor