From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: docstrings and elisp reference Date: Tue, 6 Jun 2017 14:21:12 -0700 (PDT) Message-ID: <3d5a1ca0-645f-421f-8044-f344c586705d@default> References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <13fd66c8-b22b-5b87-bd8c-34dbe0c7ec38@yandex.ru> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1496784094 16513 195.159.176.226 (6 Jun 2017 21:21:34 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 6 Jun 2017 21:21:34 +0000 (UTC) To: Dmitry Gutov , Stephen Leake , emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 06 23:21:27 2017 Return-path: Envelope-to: ged-emacs-devel@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 1dILup-0003zM-8X for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 23:21:27 +0200 Original-Received: from localhost ([::1]:40154 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dILuu-0003UK-N9 for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 17:21:32 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37168) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dILul-0003U2-5o for emacs-devel@gnu.org; Tue, 06 Jun 2017 17:21:26 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dILug-0006e4-2u for emacs-devel@gnu.org; Tue, 06 Jun 2017 17:21:23 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:50953) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dILuf-0006cR-N7 for emacs-devel@gnu.org; Tue, 06 Jun 2017 17:21:18 -0400 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v56LLFjg022722 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 6 Jun 2017 21:21:15 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id v56LLE3j018102 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 6 Jun 2017 21:21:15 GMT Original-Received: from abhmp0013.oracle.com (abhmp0013.oracle.com [141.146.116.19]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v56LLEaH021979; Tue, 6 Jun 2017 21:21:14 GMT In-Reply-To: <13fd66c8-b22b-5b87-bd8c-34dbe0c7ec38@yandex.ru> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6767.5000 (x86)] X-Source-IP: userv0021.oracle.com [156.151.31.71] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-Received-From: 156.151.31.81 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:215483 Archived-At: > > they should not duplicate each other. >=20 > Then you have something else in mind than the current > situation with documentation in Emacs. No, you do, if you think the intention now is that they duplicate each other. It never has been. Some of the information is often the same; that's all. The presentation and context of use are different. The level of detail is often different. (Sometimes there is more detail in the manual; sometimes there is more in a doc string.) In particular, doc strings are written as user help. The interactive use, if any, is typically described first, and from the point of an interactive user. Not so, the Elisp manual. The doc string for a command tells a user what it does and how a prefix arg changes the behavior. In many cases the user need have no little or no knowledge of Emacs Lisp. The Elisp doc for a command tells a Lisp programmer what the function and its parameters are, and describes their behavior. It might or might not mention that one of the parameters corresponds to the prefix arg when called interactively. Different contexts; different purposes; not necessarily the same readers or readers with the same immediate goal.