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.devel Subject: RE: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 09:58:59 -0700 (PDT) Message-ID: <4ea91e44-05db-4909-a98e-a6c8de9819e0@default> References: <20200712184908.13140.5739@vcs0.savannah.gnu.org> <20200712184909.BBC61209B1@vcs0.savannah.gnu.org> <7bf4d6ef-c0ec-43dc-ad5d-f6e81422ad90@yandex.ru> <83zh84m5ws.fsf@gnu.org> <3dd1c224-69b2-40af-5b2e-43a310253632@yandex.ru> <83tuybmtxs.fsf@gnu.org> <859f594b-1343-6d26-e1ac-7157c44eb56c@yandex.ru> <83a6zyk4tt.fsf@gnu.org> <6edffb7d-7708-534f-93ad-bf9180f5e0ed@yandex.ru> <57619ed5-49d5-d2a5-f205-8ea722d7f703@yandex.ru> 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="1408"; mail-complaints-to="usenet@ciao.gmane.io" To: emacs-devel@gnu.org, Gregory Heytings Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 17 19:00:25 2020 Return-path: Envelope-to: ged-emacs-devel@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 1jwTij-0000EZ-DL for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 19:00:25 +0200 Original-Received: from localhost ([::1]:36306 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwTii-0006tB-Cb for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 13:00:24 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44326) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwThW-0005Ml-W5 for emacs-devel@gnu.org; Fri, 17 Jul 2020 12:59:11 -0400 Original-Received: from aserp2130.oracle.com ([141.146.126.79]:45124) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwThV-0001NA-00 for emacs-devel@gnu.org; Fri, 17 Jul 2020 12:59:10 -0400 Original-Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06HGw0SW050909; Fri, 17 Jul 2020 16:59:05 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=S5eyzHJ90W/PXVv/zFDxMIU7lI1om5wqPRAyu+GSaIQ=; b=y2Ju+0beMVDBocAtr8Mk7e2B73v2KB6PGghJdmRGspExouGifq7AHjpW3vnkvTOmYYm/ O/asJH0I7QsL/7k6b7uw7oJxJjuEmkYbG+CwGOyBc/LqC04//86Lv1cAjbTPHk6ml+Vn KYkv6BkZ0k/dyumHgItFg4QXqoVIWm+B9Bi+xSKYWiw5bto7VCw0373hAGWh7nV4nN89 CNyoB4tavgO37CCkzku6vK70tGsW2GnL5mttRmuUrzCP+Ls8zWhoyAwrlq/Ez2uXOxf+ 374CDNYZM88hOTBSjp4EfxEqmYa1AtksWnLdGyVrHwixqAXduBxO+Yco5Vx5YihdAvAR 3Q== Original-Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by aserp2130.oracle.com with ESMTP id 327s65xpx1-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Fri, 17 Jul 2020 16:59:05 +0000 Original-Received: from pps.filterd (userp3020.oracle.com [127.0.0.1]) by userp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06HGvsI7113294; Fri, 17 Jul 2020 16:59:04 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userp3020.oracle.com with ESMTP id 32bbk0r08k-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 17 Jul 2020 16:59:04 +0000 Original-Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 06HGx0dA017705; Fri, 17 Jul 2020 16:59:03 GMT In-Reply-To: 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=9685 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=18 mlxscore=0 adultscore=0 spamscore=0 mlxlogscore=995 malwarescore=0 phishscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007170119 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9685 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 malwarescore=0 phishscore=0 mlxscore=0 priorityscore=1501 lowpriorityscore=0 spamscore=0 clxscore=1015 bulkscore=0 mlxlogscore=986 impostorscore=0 suspectscore=18 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007170119 Received-SPF: pass client-ip=141.146.126.79; envelope-from=drew.adams@oracle.com; helo=aserp2130.oracle.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/17 12:59:07 X-ACL-Warn: Detected OS = Linux 3.1-3.10 [fuzzy] X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 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_NONE=-0.0001, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:253040 Archived-At: > Of course I did. But as it happens, this difference does not exist in > Emacs. Remember that one of the direct inspirations of Emacs were Lisp > machines, in which the user can read and modify almost every piece of > code on the fly, from the lowest to the highest level. In such a system, > there can be no difference between "internal" and "external" documentatio= n. > I understand that it can be difficult to adapt to this way of thinking > when one comes from another programming tradition. FWIW, I agree. The only uses of labeling something "internal" for Emacs are (1) to indicate some relative risk/expectation of future change in implementation and (2) to indicate some relative risk in changing some fragile or tricky code. And even in those case, IMO just a binary label "internal" vs "external" is not the way to go. Just document in more words what's involved - which kind of risk, maybe exactly what the risks are or the future expectations/intentions are.=20 IOW, "relative" is key here - it's not about an unexplained absolute "hands-off" or "don't look". We aren't limited to just hanging an "Off Limits - No Admittance" sign. We can tell our future selves just what's involved, and why.