From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: npostavs@users.sourceforge.net Newsgroups: gmane.emacs.bugs Subject: bug#25462: Out of date doc string for "`". Date: Tue, 17 Jan 2017 21:04:48 -0500 Message-ID: <87y3y9w2bj.fsf@users.sourceforge.net> References: <20170116213051.GB4747@acm.fritz.box> <20170117200539.GB4169@acm.fritz.box> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1484705061 4923 195.159.176.226 (18 Jan 2017 02:04:21 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 18 Jan 2017 02:04:21 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) Cc: 25462@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Jan 18 03:04:16 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTfbd-0000I6-Gw for geb-bug-gnu-emacs@m.gmane.org; Wed, 18 Jan 2017 03:04:09 +0100 Original-Received: from localhost ([::1]:38741 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cTfbi-0005aX-82 for geb-bug-gnu-emacs@m.gmane.org; Tue, 17 Jan 2017 21:04:14 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43443) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cTfbb-0005aR-RZ for bug-gnu-emacs@gnu.org; Tue, 17 Jan 2017 21:04:08 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cTfbW-0004Gf-Qn for bug-gnu-emacs@gnu.org; Tue, 17 Jan 2017 21:04:07 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:35988) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cTfbW-0004GL-O0 for bug-gnu-emacs@gnu.org; Tue, 17 Jan 2017 21:04:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cTfbW-0000CX-DR for bug-gnu-emacs@gnu.org; Tue, 17 Jan 2017 21:04:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 18 Jan 2017 02:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25462 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 25462-submit@debbugs.gnu.org id=B25462.1484705032757 (code B ref 25462); Wed, 18 Jan 2017 02:04:02 +0000 Original-Received: (at 25462) by debbugs.gnu.org; 18 Jan 2017 02:03:52 +0000 Original-Received: from localhost ([127.0.0.1]:34187 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTfbK-0000C7-Or for submit@debbugs.gnu.org; Tue, 17 Jan 2017 21:03:50 -0500 Original-Received: from mail-it0-f50.google.com ([209.85.214.50]:38816) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTfbI-0000Bu-Eq for 25462@debbugs.gnu.org; Tue, 17 Jan 2017 21:03:48 -0500 Original-Received: by mail-it0-f50.google.com with SMTP id c7so1438479itd.1 for <25462@debbugs.gnu.org>; Tue, 17 Jan 2017 18:03:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=1N1snMcOeFjATak8RAHFafVD9h4+J1yGKBT9TOBXxNQ=; b=Ktkdtqjhz+zrQGkaacr/EuE0UNVfKRhB71/yl5M6kJ/POGFrWKRCFdpKDwervsOz7p RyYessS12A/MNofaKpNIsuVbgX4DrCOLYQADel8TGjYssqV4CymfaGBz3Bd7Cp0go+Zv Y2biLXlM4yogVmyKrkA1nzvF0VjidRD4Ik2KQu2PGuZMIMAID85t2XxxlryfYkPRLnE0 Rhb9qgf8GmBD41fA+fTP71uYiFnOc8GIe3aMOXspGqR764bj3pMsBCAkFevVzc6hGXAQ lM1iPDY0wZrxwKIDA4E1T8R1AoCYTRsncHdmBxbAgwUutd8dHgof42vRQ1bQL+inBhaG bVIA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=1N1snMcOeFjATak8RAHFafVD9h4+J1yGKBT9TOBXxNQ=; b=K8lury8Huzg4B0Ifr3DeFGv3SOi29pvXcS+ssOhhgQZD3XPHayBFVq4Xdm7vfdpU5K JLtlwVSnKOoZP9AAQRGhWtPxpkjZdgFp7x3uL6NQ2MtLc/PV8uy7WQUqRQfHtWRvoKuH k5/9IPXQ/JdrOGnyiL6jkdq4GgEZMPRllL9lr7C3Z+VW8pFt8E+QMJobj7RcEncf6YPY QVZ32Rg+SH67snhnTeEvF0m7VqNWVoPZY15xl14tHjs+gjCc7PvZFAY+ZlaJ1aYktAga H2uB3/XZ7ghM5v+8dL41W0KRIqhWmPyYlyOvyWx50HqzjjAGpVRQgJvVoKhLMH8sam7a C3nQ== X-Gm-Message-State: AIkVDXJUj3PY7RMcxzmVsgzkNCP/UIErfXwbzfVO3PLXArTrbnHfWBRox/I/y7gttkFtCQ== X-Received: by 10.36.170.68 with SMTP id y4mr1302233iti.7.1484705022738; Tue, 17 Jan 2017 18:03:42 -0800 (PST) Original-Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id p20sm8176264itc.2.2017.01.17.18.03.41 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 17 Jan 2017 18:03:42 -0800 (PST) In-Reply-To: <20170117200539.GB4169@acm.fritz.box> (Alan Mackenzie's message of "Tue, 17 Jan 2017 20:05:39 +0000") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:128191 Archived-At: Alan Mackenzie writes: > Hello, Noam. > > On Mon, Jan 16, 2017 at 04:52:36PM -0500, Noam Postavsky wrote: >> On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie wrote: >> > Hello, Emacs. > >> > The doc string for "`" has become partial. > >> > It fails to mention that "`" has a radically different meaning when used >> > in certain parts of a `pcase', and probably quite a few other similar >> > macros. > >> I don't think that makes sense. Similarly, we don't add a mention of >> `cl-loop's use of `if' in the docstring of `if', because that's not >> part of the `if' special form. It's just a use of `if' as a plain >> symbol. > > I don't think `if' inside cl-loop is liable to cause much confusion. > pcase, on the other hand, does cause confusion, as it radically changes > the meaning of symbols contained within it, something that other macros > don't do - with the possible minor exception of cl-loop. > > If you can think of any other such examples of context dependence > changing the semantics, I think these should be documented too. `rx' gives new semantics to `and', `or', `any', etc... `condition-case' changes the meaning of the symbol list at the front of its handlers. At one point, the `use-package' macro (note, this is not (yet) part of Emacs) interpreted `,' to mean eager evaluation. But people didn't like it, so it now uses `lambda' for that instead. > The direction I'm coming from is to make the doc strings help users - > not to make them 100% consistent. Well, I guess adding a mention of pcase in backquote's docstring would be okay. The way your initial report phrases it, as if the docstring is incomplete without that, didn't make sense to me.