From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions Date: Wed, 12 Aug 2020 20:18:48 +0000 (UTC) Message-ID: <9937689b-a9cc-4e6d-8d89-fed4141cf7c6@default> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16278"; mail-complaints-to="usenet@ciao.gmane.io" To: 42835@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Aug 12 22:19:10 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1k5xDJ-000496-P4 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 12 Aug 2020 22:19:09 +0200 Original-Received: from localhost ([::1]:51940 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5xDI-0001qT-RS for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 12 Aug 2020 16:19:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42220) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5xDC-0001qM-9Z for bug-gnu-emacs@gnu.org; Wed, 12 Aug 2020 16:19:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34099) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5xDC-0006oS-0y for bug-gnu-emacs@gnu.org; Wed, 12 Aug 2020 16:19:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1k5xDB-0001eF-Ss for bug-gnu-emacs@gnu.org; Wed, 12 Aug 2020 16:19:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 12 Aug 2020 20:19:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 42835 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.15972635396324 (code B ref -1); Wed, 12 Aug 2020 20:19:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 12 Aug 2020 20:18:59 +0000 Original-Received: from localhost ([127.0.0.1]:45645 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k5xD9-0001dw-2k for submit@debbugs.gnu.org; Wed, 12 Aug 2020 16:18:59 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:54406) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k5xD7-0001do-1U for submit@debbugs.gnu.org; Wed, 12 Aug 2020 16:18:57 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42210) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5xD6-0001qD-S8 for bug-gnu-emacs@gnu.org; Wed, 12 Aug 2020 16:18:56 -0400 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:40682) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5xD4-0006o7-Tx for bug-gnu-emacs@gnu.org; Wed, 12 Aug 2020 16:18:56 -0400 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 07CKGwTd168285 for ; Wed, 12 Aug 2020 20:18:51 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=3U0wDmIq7JGb/wvZFhX9f8RdrhhjFf6dp6y3wvIeW0o=; b=QhyOKe2jYHa/WFwBhvIYbBOm7RlIyP5/W2kxj3axgVZGl/kVz8AjBoUBRn2g/1P5H/UE bKIhF/4cj1c9f2lV7XMqf5b8r4tbxQ+/eM+kSYl4pys00BhiNv1awpXT3mftjfWTRXNq IzH+uf3BPtQR97wqHP4i5YLaLbuZsf7TC7Y2N1D7FGAGTxQtMF6K5BTQKt5Yp7pv1nsh X7Od72paADQ4EaFIbG1bv3fX/3ViOVXtYfyqRA5gpUAqYQk+ISs1R5tpsI0IACcGCXfU jl0qByit1JX3rPSlr5LepFMNgUFpIrLjetZu/ZsED+79c1apW75a5V6KwS+ZPnHxriqf VA== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by aserp2120.oracle.com with ESMTP id 32sm0mvyhy-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL) for ; Wed, 12 Aug 2020 20:18:51 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 07CKHMsf041871 for ; Wed, 12 Aug 2020 20:18:51 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3020.oracle.com with ESMTP id 32t5y7sbr9-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Wed, 12 Aug 2020 20:18:51 +0000 Original-Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 07CKInta025544 for ; Wed, 12 Aug 2020 20:18:50 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5017.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9711 signatures=668679 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 malwarescore=0 suspectscore=1 mlxscore=0 adultscore=0 bulkscore=0 phishscore=0 mlxlogscore=655 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2008120127 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9711 signatures=668679 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 phishscore=0 clxscore=1015 suspectscore=1 mlxlogscore=629 priorityscore=1501 adultscore=0 impostorscore=0 spamscore=0 bulkscore=0 mlxscore=0 lowpriorityscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2008120127 Received-SPF: pass client-ip=141.146.126.78; envelope-from=drew.adams@oracle.com; helo=aserp2120.oracle.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/08/12 16:18:52 X-ACL-Warn: Detected OS = Linux 3.1-3.10 [fuzzy] X-Spam_score_int: -63 X-Spam_score: -6.4 X-Spam_bar: ------ X-Spam_report: (-6.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:184873 Archived-At: This node has a list of functions and macros, some of which have footnotes. I don't understand the footnotes (which are not sentences, BTW). For example, `cl-incf' has footnote [1], which says: [1] Only when PLACE is a plain variable name. What happens only when PLACE (the first arg to `cl-incf') is a plain variable name? What happens when PLACE is not a plain variable name? `C-h f cl-incf' doesn't help at all in this regard. It doesn't say anything at all about different behaviors for different kinds of PLACE. Similarly for the other names and their footnotes. There's no doc specifying the behaviors of `cl-pushnew' etc. for any particular kinds of PLACE. Nothing says what happens "only if :test is ___ or :key is ___.=20 This doc is completely unclear to me. I have no idea what it's trying to say. And the doc strings of these functions and macros don't help at all with this. If I look up the doc for, say `cl-incf' in the CL manual, it doesn't help. It says nothing about a non-variable PLACE (and nothing specific about a variable PLACE, for that matter). It just shows an example. The manual entry for `cl-pushnew' is even worse. It talks only about `eql' and doesn't say anything about :test. There's an xref to node `Lists as Sets' for info about the keyword args, but that node also says nothing about :test. Instead, that node just punts further, to node `Sequences'. In general, this doc in this manual, and the CL doc strings, are nearly useless, and perhaps harmful/misleading. Certainly not very helpful. In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32) of 2019-08-29 Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd Windowing system distributor `Microsoft Corp.', version 10.0.18362 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3''