From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Scan of regexps in Emacs (March 17) Date: Wed, 20 Mar 2019 21:21:38 -0700 (PDT) Message-ID: <36108066-ff96-48d2-86c0-06fb8ce127ba@default> References: < <5363970c-3207-1bb4-8b30-74a7d12277cc@cs.ucla.edu> <05269D79-B016-4FCB-94B8-068BF7D1C2D2@acm.org> <3974269b-6cad-0744-bd1f-66c067f94192@cs.ucla.edu> <4b1164c4-e302-ce41-07c3-145d31a97b4c@cs.ucla.edu> <5c3865d3-4f6f-4a07-be99-487ec0fb6217@default>> <> <<83d0mk6go5.fsf@gnu.org>> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="141526"; mail-complaints-to="usenet@blaine.gmane.org" Cc: drew.adams@oracle.com, emacs-devel@gnu.org To: Eli Zaretskii , Paul Eggert Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Mar 21 05:22:33 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1h6pDs-000afd-3x for ged-emacs-devel@m.gmane.org; Thu, 21 Mar 2019 05:22:32 +0100 Original-Received: from localhost ([127.0.0.1]:59344 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h6pDq-0005MD-Tu for ged-emacs-devel@m.gmane.org; Thu, 21 Mar 2019 00:22:30 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:35286) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h6pDH-0005Lv-04 for emacs-devel@gnu.org; Thu, 21 Mar 2019 00:21:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h6pDF-0007Of-Vi for emacs-devel@gnu.org; Thu, 21 Mar 2019 00:21:54 -0400 Original-Received: from aserp2130.oracle.com ([141.146.126.79]:41270) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1h6pD9-0006Sg-Vq; Thu, 21 Mar 2019 00:21:48 -0400 Original-Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x2L4JD4v131301; Thu, 21 Mar 2019 04:21:40 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=dmPl6VRVgc1yVqApV72rJrQBukKIZKzUkHNHBEOMvDE=; b=AXYfdcrwJRVVw6T8i/vgufuJDHyE4U3Wdx8j/YcCMTEJvG5zpUVpJNG+KCNxKlaPvKmk psJN8ie7eOCgG7LMNixECPgvodH760kLcTlSCZqf7CG0/0Qd+pLQhgIKkCV73FFp0HVG VhWDnqa8Lq+eUyVJNimT/S6xBiWMfy8se2BJ6AbPrlV41FazQyG7NWfjG1Uurv1+jwRp mqIwIJH4kYVX2EBQzABX6dsNzCMDHS2v41uNVNU8l39nvgG2lK0rvxWSPhbYv2IR9zce jKemhPaL/vaBAZmNUeu2xYKeW9D0uyfdhV9F6RTksLFHF//xHZ3J2wu3a8xEGLB3Vm3m /g== Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp2130.oracle.com with ESMTP id 2r8pnexjk9-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 21 Mar 2019 04:21:40 +0000 Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id x2L4LdrJ011671 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 21 Mar 2019 04:21:39 GMT Original-Received: from abhmp0009.oracle.com (abhmp0009.oracle.com [141.146.116.15]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x2L4Ldgd028366; Thu, 21 Mar 2019 04:21:39 GMT In-Reply-To: <<83d0mk6go5.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4822.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9201 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1903210028 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-Received-From: 141.146.126.79 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:234448 Archived-At: > > As the Emacs documentation currently has thousands of occurrences of > > "should", it sounds like we don't generally follow the guideline you're > > suggesting. If they're accompanied by stating _why_ you should then there's generally no problem understanding. Call that a scoped/qualified "should" - not really a problem, because the follow-up explains (by describing consequences) what we mean there by "should". =20 > Indeed. And the reason is likely that our documentation is not > "technical documentation" in the sense meant in that article. There was no article. Just my opinion. (The URL was just to explain the term "weasel word".) And in my opinion our doc _is_ technical doc. If we don't say why you should then it's usually preferable (IMO) to say that we "recommend" that you do XYZ than to say you "should" do XYZ. In any case, it's usually helpful to say why. The problem with an empty "should" is that it's vague, and it can be misunderstood as a (possibly shame-faced) "must". (Shame-faced ~ weasel.) Something that's presented as an unexplained recommendation is at least seldom confused with a requirement (a "must"). "Should" is more vague and is often understood as stronger than just "it's a good idea" (a recommendation). But "should", "recommend", and "must" all typically beg the question of what happens if you don't. With "should", in particular, it's also typically unclear how important it is that you do what's suggested. "Must" is pretty clearly important - a requirement of some sort. But for "must" too it helps to say what happens if you don't respect the rule. To be clear, I'm not saying it's appropriate or enough to just replace all occurrences of "should", or that all such occurrences are unwise.