From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: Docstrings and manuals Date: Sun, 17 Apr 2016 14:42:28 +0300 Message-ID: <909c91ef-aa2e-4bcc-9828-603c4203e3d0@yandex.ru> References: <6ok2vyzwf9.fsf@fencepost.gnu.org> <08f70cda-44be-0657-e50a-2b2c80d2c21c@yandex.ru> <87oa9dzgl0.fsf@gmx.de> <87potshczh.fsf@gmx.de> <87h9f4ghzg.fsf@gmx.de> <8737qnc8ep.fsf@gmx.de> <87k2jwd3gr.fsf_-_@gmx.de> <8dfdfe5d-41fe-7c05-0054-0bd3e589390e@yandex.ru> <8737qkcwoo.fsf@gmx.de> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1460893380 31971 80.91.229.3 (17 Apr 2016 11:43:00 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 11:43:00 +0000 (UTC) Cc: Glenn Morris , emacs-devel To: Michael Albinus Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 17 13:42:53 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1arl6J-0004A4-2f for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 13:42:51 +0200 Original-Received: from localhost ([::1]:44887 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arl6I-00012V-Af for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 07:42:50 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50409) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arl63-0000zf-Sq for emacs-devel@gnu.org; Sun, 17 Apr 2016 07:42:36 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1arl60-0008OC-DN for emacs-devel@gnu.org; Sun, 17 Apr 2016 07:42:35 -0400 Original-Received: from mail-wm0-x243.google.com ([2a00:1450:400c:c09::243]:36080) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arl60-0008Ny-7E; Sun, 17 Apr 2016 07:42:32 -0400 Original-Received: by mail-wm0-x243.google.com with SMTP id l6so17237747wml.3; Sun, 17 Apr 2016 04:42:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:subject:to:references:cc:from:message-id:date:user-agent :mime-version:in-reply-to:content-transfer-encoding; bh=kBHiDVqUMBH0ERShApnca9m11nQRNkdYYQfSifuYD3g=; b=dMzCrt4ymmmivtwTWEmDPiPrU1s7nLtyPFMYqIIfDXQ/ps4fhL2dhpycKZGXCvnTYw RplXNjTITs5Hb44egzpU+TqdbR1fnu2lkTH0wD2gjbB3AEEjjbpNHNlCwdgA7Xn/kcts AW9wDixS083cBLOhcAlOFZTB6UCfqpNv9zVxhHqwmkbpClI27tVGje3TXyuZO0lzHJdl Skw1mW9LqFRbBNzL93FFRdCRqhHcryoYktjJWwps1G+J2ogw6GuduKCOUlme8PDmvOUe s5SYcnx+mRhMHthT6CAiq/iuIU4gYICjvVNUczE8t3B0eFgd8B6LYPISWJj15TZBRbGX WAzQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:subject:to:references:cc:from:message-id :date:user-agent:mime-version:in-reply-to:content-transfer-encoding; bh=kBHiDVqUMBH0ERShApnca9m11nQRNkdYYQfSifuYD3g=; b=g0XeWRIasgpRkGeOOnPBtkHoXsEUtrTBS/svFdo4nXHwtY8d3cEoRFh1M4tCj3SvhX F0i77QshuniV2bx6DhE2p5gpSTGdjO6MsoP/XAXsYjVFMdBtA38IV0UlHaIyKHtG7bYz KY6JJ+BALNWHEb6LI49Dnnbr7hP981HJ7ze6OIXH8ghUjJ6UzCM9NMYEqo15W+0Ptk+M l2GxdEiJlU5SNPA1XaaeMCpSGImjuTsoR0iOrcsCl4NQ0M4Nlim6OFBqKraAnb2eO6hm pHeqCvRNV9YY7oT8IdRTkgh2KYVfGhx2Zdl7Ga/VkSZjjYxeL9b+dETvw/YnnxOjSKoq hj/g== X-Gm-Message-State: AOPr4FWQcb4plFabPEcI3U8o9vwaMSllSnVKLad8Hn2N0BDnXX85rT5btuGIshG62mE1dA== X-Received: by 10.194.92.45 with SMTP id cj13mr34253785wjb.178.1460893351311; Sun, 17 Apr 2016 04:42:31 -0700 (PDT) Original-Received: from [192.168.1.2] ([185.105.175.24]) by smtp.googlemail.com with ESMTPSA id e140sm32183338wma.13.2016.04.17.04.42.29 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 17 Apr 2016 04:42:30 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0 In-Reply-To: <8737qkcwoo.fsf@gmx.de> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:400c:c09::243 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:203009 Archived-At: On 04/17/2016 02:16 PM, Michael Albinus wrote: > No primary or secondary. If docstring and manual are inconsistent, it is > a bug which must be fixed. What's "inconsistent" in this case? They are almost always different. > There is no automatism that the docstring is > always right, and the manual is wrong in this case. It could be also > vice versa. Wouldn't it be better if we had this "automatism"? > See also the Elisp Manual (info "(elisp)Caveats") > > --8<---------------cut here---------------start------------->8--- > The manual should be fully correct in what it does cover, and it is > therefore open to criticism on anything it says—from specific examples > and descriptive text, to the ordering of chapters and sections. If > something is confusing, or you find that you have to look at the sources > or experiment to learn something not covered in the manual, then perhaps > the manual should be fixed. Please let us know. > --8<---------------cut here---------------end--------------->8--- I'm not arguing in favor of leaving mistakes in the manual. But I think it should be strictly a derivative work. I.e. the docstrings must contain the complete information (if maybe presented in a terse fashion), and the manual could rephrase that, only to make it more accessible (but not more informative).