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 22:59:21 +0300 Message-ID: <532e9505-ea1b-d035-e5c6-131ec36ea441@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> <909c91ef-aa2e-4bcc-9828-603c4203e3d0@yandex.ru> <83ziss9sml.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 1460923200 9036 80.91.229.3 (17 Apr 2016 20:00:00 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 20:00:00 +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 21:59:54 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 1arsrJ-0006Pr-CS for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 21:59:53 +0200 Original-Received: from localhost ([::1]:51226 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arsrI-0003WQ-MX for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 15:59:52 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38481) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arsr3-0003Tk-21 for emacs-devel@gnu.org; Sun, 17 Apr 2016 15:59:37 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1arsqz-0007ax-Qh for emacs-devel@gnu.org; Sun, 17 Apr 2016 15:59:36 -0400 Original-Received: from mail-wm0-x241.google.com ([2a00:1450:400c:c09::241]:34185) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arsqz-0007am-JN; Sun, 17 Apr 2016 15:59:33 -0400 Original-Received: by mail-wm0-x241.google.com with SMTP id n3so19494467wmn.1; Sun, 17 Apr 2016 12:59:33 -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=5TVRTEozaNsKF9XMsL4Wb0gVTbusGA4cPFtBXcSrkNY=; b=ssL93A/yr4CBL/KvYjKd9781RyUJ0S7E+o8xna380lBgISEc3VFh4ZFspR3AlnAxpU 7RIhrwwjGeRWxBSl7kSIw8sFl3wb9LIht5rCSvhjdammYOrg6VJ4wJTlyfVVqlUPQti8 s6YIYSro2oap+u6mqBGyc2BOrA07RoYTb7APCmN15M6znXx2A+X5NgGnxnaLod/L7CCZ pWeY3yRlyknzWNsmbn0M5Pbyb2khLRe6ac9XK5QAB2ssOkjzs6/3/jNZ/8g4cptqiKgU JJDxs3E9TpGXfVmr6K4Uc7Y6XOel3frCxTQNrplu+clo+usUbMn9k5aeeeaW9kRK+NvX 1fOg== 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=5TVRTEozaNsKF9XMsL4Wb0gVTbusGA4cPFtBXcSrkNY=; b=SbYqsg6rTGaF+bqr0jBIWMscCvdyTw+NCJh1rT7++ymVMkuAu3G/b/+R42Pez4F6jl NfHGKhWuBCQcBelPL/S1N8tmKJH3oroY8IK0ZnBrJXEaVWJXsbwCbwTe/qFIdz8NL6vJ cwgyPrnCBcOQZuxT/DJ2XIecdqFNmpyJpatk6UeL4zzaRG5W5sIi+SH/uhCyfeTGt++s tflfI5o7Wq0IogcbPFXO1F8kSeI+z0XbThzoL+oDssXtH+pPHYsn8zzbkdJ1bEABOJr1 FuoP0GCAiV85e8zlW97RUyvYXASxMM/lQZ1yBNkKoy54Cw/uWkP2A+GG0eVV5a7BTcJw ZEPg== X-Gm-Message-State: AOPr4FWVf09EyVuum+r1LyuFXUrm6dwjQKldIlbowo0Yjwy53T8ALWMLT12nSDN877HP7w== X-Received: by 10.194.187.145 with SMTP id fs17mr31699830wjc.179.1460923172841; Sun, 17 Apr 2016 12:59:32 -0700 (PDT) Original-Received: from [192.168.1.2] ([185.105.175.24]) by smtp.googlemail.com with ESMTPSA id u4sm60454411wjz.4.2016.04.17.12.59.30 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 17 Apr 2016 12:59:32 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0 In-Reply-To: <83ziss9sml.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::241 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:203022 Archived-At: On 04/17/2016 06:12 PM, Eli Zaretskii wrote: > Once you allow rephrasing, you already allow deviation. And there > really is no way around allowing it, because a manual that includes > only the doc strings with a minimum "glue" is much less palatable. > You can look at Guile as one example; GnuTLS is another. Such manuals > are much less useful, IME, than what we have in Emacs. I'd rather minimize rephrasing in the manuals, while still allowing the "glue" text. Instead of having two ways to describe each important variable, I'd rather have just the docstrings, which could be adjusted to be more approachable. That would require some new Texinfo syntax to "insert the docstring here". The narrative can still be free-form, but at least there would be one fewer source of duplication. > One thing that you will never find in doc strings is a discussion of > merits and demerits of different ways of solving some problem, > especially if such a discussion requires to jump back and forth > between these ways, in order to make some point. The counterpart to "glue" text outside of the manuals is the Commentary section usually. While they're also terse usually (but not always), they aren't bound by the limitation that a docstring has to relate to a particular symbol. > IOW, writing a good manual is still a human activity that cannot be > easily automated. Ideally, doc strings should be phrased like > reference material, covering all the traits as tersely as possible, > while the manual should provide an easier reading with more continuity > text and even some explanations why things are the way they are. At > least IMO. That sounds fine, and maybe this way is best for the more complex subjects, but in general I'd prefer to see docstrings also written with readability in mind. Then, when writing a manual section, you'll only need to write the "glue" text, and pick which symbol references, with docstrings, to add, and in which order.