From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Michael Albinus Newsgroups: gmane.emacs.devel Subject: Re: Docstrings and manuals Date: Sun, 17 Apr 2016 13:16:23 +0200 Message-ID: <8737qkcwoo.fsf@gmx.de> 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> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1460891805 10202 80.91.229.3 (17 Apr 2016 11:16:45 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 11:16:45 +0000 (UTC) Cc: Glenn Morris , emacs-devel To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 17 13:16:36 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 1arkgt-0008VG-Ed for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 13:16:35 +0200 Original-Received: from localhost ([::1]:44520 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arkgs-0006t8-Ne for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 07:16:34 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45888) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arkgp-0006mD-8A for emacs-devel@gnu.org; Sun, 17 Apr 2016 07:16:32 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1arkgk-0002aL-8J for emacs-devel@gnu.org; Sun, 17 Apr 2016 07:16:31 -0400 Original-Received: from mout.gmx.net ([212.227.15.18]:56113) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arkgj-0002aD-Vi; Sun, 17 Apr 2016 07:16:26 -0400 Original-Received: from detlef.gmx.de ([87.146.42.239]) by mail.gmx.com (mrgmx002) with ESMTPSA (Nemesis) id 0MQ2zr-1amVtj2I7f-005E8P; Sun, 17 Apr 2016 13:16:24 +0200 In-Reply-To: <8dfdfe5d-41fe-7c05-0054-0bd3e589390e@yandex.ru> (Dmitry Gutov's message of "Sun, 17 Apr 2016 13:50:35 +0300") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.92 (gnu/linux) X-Provags-ID: V03:K0:AFAan5rudwjA65DuIAcAI1+m2xAMiS/GvHGjnHp4u0rJN/dJoXF JLol4/ccMmLyX1Ft3YyXTgj+H71rmDT+hnsC/htlEV4GwoCd6+BbvAw3LbZYptp5Y/lTVCV wugB+wEQNconR1cbDoiChflKHUsyg+YjpAItvn/kbi6/cSvEqQoM2+tn+hdKNwcK0HEA9wI 0jzIXcyEKdxc5/iL9Q/jA== X-UI-Out-Filterresults: notjunk:1;V01:K0:DhIt3Zc7yWE=:sa75F0hvsvlvpV6ISbLRYX TVva4gKpKGxAhcQ8hzSIk/bLFixv3SIiNB5HaakLH3VSccJGAm6F0V4y+WehrLRsi5aY5TMOe yiUc6p0A9dfiSEoB2XUe44U6OihjU7B486ra4JJefrRWeebNN4sN2iXlmtmIH78hyiNrFzPWs wMPiQdS11NEZc7WTR8jarTQLAT7VuqzA8PgV7QYWEjNC4fK9z62mA1Fug9OgV0jzzOL9b+WTJ BTuf/6jUB6lZwI0yWS+/po2K/fQ7xfQxcQgK52vpTVb3DMEQoKG/14ADOwWUO3YVL986xj9aL 3K/ACT+Db2MeTzEcZzaPF1nEQKko05dvqx4v3FGq7dtA0J+OAirzaWMXc0FkdhDTEG1IL7qXL kHjOCN0nTkh02UXtmZ/HkswcKPmtG+G1QGrmzLyuTrxEAqUVLoWo4vEWOLPal0MRqlvaMtwR9 L1Lckd48cLfQJj7D0xx5kjPg05NDaaZAY7pTrC7xwX1Hvz2WPpgWTEB6n8qVlI/xx8cJb49lW Lf67gHGK0x+9ZpuKZl9Qqk8mz95cew1yU95wCkTm2dFwn4eaZcRET5xzHI9rnX4MBYaOvriSX ZcQ5954kmljKIJQjZa5buvSNRL1IoKCz3zxIq1OUxmyUrPqFAdLb2JTc0KSjqP+XLqrYVEG6g 0JOuik3Wp9rP6ymjwj5j9Xy4oPQ4SF2eQc1z9TxztJedvisQ8OkSJIoRRHXTv2YD2GNEp+Usu dA+NgbbSClReGiqXr8XRpsbS5PMEMGvcZ1kd/w5BpD7f2Vd6JlMYmq8/wsAGa6jOc6hmCYCl X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.15.18 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:203007 Archived-At: Dmitry Gutov writes: >> This does not mean that manuals are useless. It only means, that there's >> a bug to be fixed. > > Sure. But I think that means that we should have a policy that the > manual is secondary to the information contained in the source > files. Right now, I have no idea which one is supposed to be the > primary source of truth. No primary or secondary. If docstring and manual are inconsistent, it is a bug which must be fixed. There is no automatism that the docstring is always right, and the manual is wrong in this case. It could be also vice versa. 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=E2=80=94from specific examp= les 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--- Best regards, Michael.