From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Trunk still not open Date: Sat, 15 Mar 2014 10:45:59 +0200 Message-ID: <834n2zdf3s.fsf@gnu.org> References: <6xwqfxhl88.fsf@fencepost.gnu.org> <83txb1mcsy.fsf@gnu.org> <87siqlku0i.fsf@uwakimon.sk.tsukuba.ac.jp> <87wqfxari2.fsf@yandex.ru> <87zjksrvqr.fsf@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1394873174 28490 80.91.229.3 (15 Mar 2014 08:46:14 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 15 Mar 2014 08:46:14 +0000 (UTC) Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Mar 15 09:46:23 2014 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 1WOkEY-0000kd-LZ for ged-emacs-devel@m.gmane.org; Sat, 15 Mar 2014 09:46:22 +0100 Original-Received: from localhost ([::1]:49209 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOkEY-0007K5-7W for ged-emacs-devel@m.gmane.org; Sat, 15 Mar 2014 04:46:22 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42616) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOkEP-00078L-MO for emacs-devel@gnu.org; Sat, 15 Mar 2014 04:46:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WOkEK-0000BK-Bp for emacs-devel@gnu.org; Sat, 15 Mar 2014 04:46:13 -0400 Original-Received: from mtaout22.012.net.il ([80.179.55.172]:58031) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOkEK-0000B3-3N; Sat, 15 Mar 2014 04:46:08 -0400 Original-Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0N2G00000YZDNI00@a-mtaout22.012.net.il>; Sat, 15 Mar 2014 10:46:06 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0N2G000OSZ0PAZA0@a-mtaout22.012.net.il>; Sat, 15 Mar 2014 10:46:01 +0200 (IST) In-reply-to: <87zjksrvqr.fsf@yandex.ru> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.172 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:170382 Archived-At: > From: Dmitry Gutov > Date: Sat, 15 Mar 2014 05:22:52 +0200 > Cc: emacs-devel@gnu.org > > Having just now updated the manual WRT to the new > `blink-matching-paren', I feel quite disgusted by having to document the > changes in triplicate. > > The docstrings in the code, lispref/display.texi and emacs/programs.texi > all contain the descriptions of the relevant symbols, each using quite > different text. > > Writing docs does not come easy to me in general, and editing three > seemingly arbitrarily different descriptions of the same things is a > good recipe for a headache. I have no idea how to judge the changes I > made. The doc strings and the manuals take different views on the same features. The doc strings document only the symbol they pertain to, with minimal links to others. By contrast, the manuals should always describe the features in the context of a larger theme that is the subject of the containing section of the manual. This means, in particular, that the manual text should: . contrast each feature with other features and discuss its advantages and disadvantages, as in "unlike FOO, this function..." . include cross-references to related material and places where terminology you use is defined and described . provide examples where necessary to clarify the usage of a feature, especially when its formal description might not be clear enough . in general be less concise and more explanatory, since the size of the text is less important than in a doc string (it doesn't affect the memory footprint of the Emacs process) . for the ELisp manual, provide the information that Lisp programmers need to use the feature best, such as considerations when to use and when not to use it It is quite rare to have a feature whose documentation in the manual is simply a repetition of its doc string.