From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Sun, 18 Jun 2017 15:52:25 -0400 Message-ID: References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <13fd66c8-b22b-5b87-bd8c-34dbe0c7ec38@yandex.ru> <3d5a1ca0-645f-421f-8044-f344c586705d@default> <0d081c78-3e64-4cc3-afdd-471b49f21f24@yandex.ru> <83r2yw8iyu.fsf@gnu.org> <8241d6cf-0902-5f3b-9060-8bb445c02fed@yandex.ru> <20170617130435.GA2955@acm.fritz.box> <9da1fc4f-1916-7d29-b9de-2ed265a9cf9a@yandex.ru> <20170617201423.GB2955@acm.fritz.box> <838tkqyqie.fsf@gnu.org> Reply-To: rms@gnu.org NNTP-Posting-Host: blaine.gmane.org Content-Type: text/plain; charset=Utf-8 X-Trace: blaine.gmane.org 1497815592 30259 195.159.176.226 (18 Jun 2017 19:53:12 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 18 Jun 2017 19:53:12 +0000 (UTC) Cc: acm@muc.de, dgutov@yandex.ru, stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jun 18 21:53:08 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 1dMgFv-0007Ts-QC for ged-emacs-devel@m.gmane.org; Sun, 18 Jun 2017 21:53:07 +0200 Original-Received: from localhost ([::1]:39405 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMgFz-0002hR-En for ged-emacs-devel@m.gmane.org; Sun, 18 Jun 2017 15:53:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40004) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMgFK-0002gD-9Z for emacs-devel@gnu.org; Sun, 18 Jun 2017 15:52:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dMgFJ-0001Ii-Et for emacs-devel@gnu.org; Sun, 18 Jun 2017 15:52:30 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:60611) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dMgFG-0001Dj-Fk; Sun, 18 Jun 2017 15:52:26 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1dMgFF-0005tK-E5; Sun, 18 Jun 2017 15:52:25 -0400 In-reply-to: <838tkqyqie.fsf@gnu.org> (message from Eli Zaretskii on Sun, 18 Jun 2017 05:32:41 +0300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:215755 Archived-At: [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] When you want to refer to documentation on a function whose context you already basically know, you probably want the doc string, because doc strings are made for that. The manual is made for when you want to learn about a certain feature, including various functions and variables. They are both important, and each should be written in the way that is best for its job. Which means, quite differently. -- Dr Richard Stallman President, Free Software Foundation (gnu.org, fsf.org) Internet Hall-of-Famer (internethalloffame.org) Skype: No way! See stallman.org/skype.html.