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 23:22:59 +0300 Message-ID: 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> <831t64b7l0.fsf@gnu.org> <3c95a1a7-a334-73e7-0644-71aa0d862b50@yandex.ru> <83twj09pc5.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1460924608 29068 80.91.229.3 (17 Apr 2016 20:23:28 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 20:23:28 +0000 (UTC) Cc: rgm@gnu.org, michael.albinus@gmx.de, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 17 22:23:27 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 1artE7-0008JD-Ce for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 22:23:27 +0200 Original-Received: from localhost ([::1]:51517 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1artE6-0007ZU-OA for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 16:23:26 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42176) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1artDn-0007Wb-5K for emacs-devel@gnu.org; Sun, 17 Apr 2016 16:23:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1artDj-00048T-4b for emacs-devel@gnu.org; Sun, 17 Apr 2016 16:23:07 -0400 Original-Received: from mail-wm0-x243.google.com ([2a00:1450:400c:c09::243]:36156) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1artDi-00048P-Tr; Sun, 17 Apr 2016 16:23:03 -0400 Original-Received: by mail-wm0-x243.google.com with SMTP id l6so19558890wml.3; Sun, 17 Apr 2016 13:23:02 -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=DObfpsJie1hxmNMn7nCTVxmr2GUB06FnzbQHM9vKcx0=; b=tiOlLurbAaM688MVMl/RzkKmSUmRRyAXxHPrMcHYI0V6zQRcAywLJfVWjQZ74F580N 1OAXFwRCHWRHWNrWWh8NOgKaNoZSnJzSfUgmnhnFLAzlJk73G6j//R3wDm/OBdEVYt68 SJpxQ/2dXzIMjeLfvO0kkjgxVilB/1ZeyfePaBJDdQM6xE/SiFrNclEOUIh0i+ZrSfUU c6m4uzxzIEOd4nlXEtCKRKAGho74MFfYMupr4MrW53fBUxbD3HoC/4+nuLEY2G+YXzb6 3hm50NRlFz96MbagO11qDxZc/BPAqSvbe9KWBARJ3KVCT9Dma5wnu2CsyzXG5zhV6PTe QXcQ== 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=DObfpsJie1hxmNMn7nCTVxmr2GUB06FnzbQHM9vKcx0=; b=CNNORiG+rAEEz72heq1MfBvfMi4WT4nZbNRrwzt1CjLspZuLZxWPjbzDGT76VLzDxE D61B3Pj/T3NQcg+LyQdjUIPBK3YAocIQUjDSUeFJoeIWjMlzGXuj/WLZflCdmA1xeKI/ FbPkD93hdAsUc7/BORQv2xn0LbYAExLPuE0zKVutTPId/LvJHUyF5nZgVjA4TCgfvVlb 69oofZ87JJniXT/H9scVpLvLk5942eiPVAMZxPwir0Rt488B3OIYSmj+rFSiooEfuPhJ XiGqzOnUJj2gfPsyNGCNuEoTrxT9wsoh+AtNpFfaXYEkjNmU1bUd4x/azqmefOGwH25Q JI1A== X-Gm-Message-State: AOPr4FUayZ8hreCFbTuYEMUrA6IZ2E3sbqeHYodk9oo4hn3MXkCeUQa+DMOg2wB/nxemPg== X-Received: by 10.194.58.138 with SMTP id r10mr31657136wjq.153.1460924582270; Sun, 17 Apr 2016 13:23:02 -0700 (PDT) Original-Received: from [192.168.1.2] ([185.105.175.24]) by smtp.googlemail.com with ESMTPSA id n3sm60371340wja.6.2016.04.17.13.23.00 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 17 Apr 2016 13:23:01 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0 In-Reply-To: <83twj09pc5.fsf@gnu.org> 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:203023 Archived-At: On 04/17/2016 07:23 PM, Eli Zaretskii wrote: > To produce a good manual text, you need to try to describe and explain > the subject in some logical way. The result is not a derivative, in > that it doesn't necessarily repeat the doc strings and then adds some > more stuff (although doing that is sometimes TRT). It should be a derivative in the sense that it's produced based on knowing the docstrings and the common context they're used it. But not some additional inner details about each symbol that never made it into docstrings, I think. > It could be that > most of the text of the manual section has no direct relation at all > to the doc strings. It could even be an entirely different POV of > looking at the subject. E.g., compare the node "Generic Functions" in > the ELisp manual with the doc strings of the symbols covered by that > node. As an even more extreme example, compare the node > "Bidirectional Editing" in the user manual with the doc strings of the > 3 variables it covers. Bidirectional Editing is fine. It describes a facility that's largely implemented in C, so the three variables are just a small part of it. Generic Functions, on the other hand, may be indicative of the problem that I've brought up: the descriptions of `cl-defgeneric' and `cl-defmethod' and much longer in the manual than their docstrings (especially the latter one). I see no particular reason for them to be different in this case. Maybe that will require restructuring the manual text to move the enumeration of the possible types (defined in cl--generic-typeof-types) to a separate paragraph or section, but that seems only beneficial. Why would we want to mention that :before methods get called "in the most-specific-first order" only in the manual, but not in the docstring? And so on. When a docstring gets too complicated, we can go the way of `cl-loop' to, again, avoid repeating ourselves. In that case I at least know to consult the manual, and which node to visit.