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: Tue, 06 Jun 2017 18:42:11 -0400 Message-ID: References: Reply-To: rms@gnu.org NNTP-Posting-Host: blaine.gmane.org Content-Type: text/plain; charset=Utf-8 X-Trace: blaine.gmane.org 1496788987 23394 195.159.176.226 (6 Jun 2017 22:43:07 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 6 Jun 2017 22:43:07 +0000 (UTC) Cc: emacs-devel@gnu.org To: Jean-Christophe Helary Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 07 00:43:03 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 1dINBn-0005rW-Eq for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 00:43:03 +0200 Original-Received: from localhost ([::1]:40310 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dINBs-0003m0-Pt for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 18:43:08 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58279) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dINB2-0003k4-UN for emacs-devel@gnu.org; Tue, 06 Jun 2017 18:42:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dINB1-0004JI-Mb for emacs-devel@gnu.org; Tue, 06 Jun 2017 18:42:16 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:39193) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dINAx-0004GB-Qc; Tue, 06 Jun 2017 18:42:11 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1dINAx-00081A-71; Tue, 06 Jun 2017 18:42:11 -0400 In-reply-to: (message from Jean-Christophe Helary on Tue, 6 Jun 2017 06:26:07 +0900) 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:215487 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. ]]] > I was thinking (naively?) that having the docstrings on one side > and the reference on the other side was not a very efficient way > to maintain documentation. Is everything in the documentation > actually written by hand based on the docstrings? Wouldn't it be > nicer to have good docstrings and use them directly in the > documentation to avoid duplication of work? Absolutely not! That's a recipe for a bad manual. The text of a good manual section is totally different from a series of doc strings. Doc strings are read one by one. Each one describes one function or variable in isolation. They are written specifically for this kind of use. By contrast, a section in a manual describes several related functions and variables, and it should be written in an integrated way that flows smoothly. Meanwhile, common material should be stated only once. -- 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.