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: Sun, 16 Mar 2014 18:17:20 +0200 Message-ID: <83mwgqazjj.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> <834n2zdf3s.fsf@gnu.org> <87wqfukd7v.fsf@gmail.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1394986647 25643 80.91.229.3 (16 Mar 2014 16:17:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 16 Mar 2014 16:17:27 +0000 (UTC) Cc: emacs-devel@gnu.org, dgutov@yandex.ru To: Jambunathan K Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Mar 16 17:17:35 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 1WPDkj-0000N7-CN for ged-emacs-devel@m.gmane.org; Sun, 16 Mar 2014 17:17:33 +0100 Original-Received: from localhost ([::1]:53836 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WPDki-00067F-ME for ged-emacs-devel@m.gmane.org; Sun, 16 Mar 2014 12:17:32 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50234) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WPDkb-00065a-DN for emacs-devel@gnu.org; Sun, 16 Mar 2014 12:17:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WPDkW-0005rQ-4D for emacs-devel@gnu.org; Sun, 16 Mar 2014 12:17:25 -0400 Original-Received: from mtaout26.012.net.il ([80.179.55.182]:48333) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WPDkV-0005r1-Se for emacs-devel@gnu.org; Sun, 16 Mar 2014 12:17:20 -0400 Original-Received: from conversion-daemon.mtaout26.012.net.il by mtaout26.012.net.il (HyperSendmail v2007.08) id <0N2J00C00EEPEB00@mtaout26.012.net.il> for emacs-devel@gnu.org; Sun, 16 Mar 2014 18:16:38 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by mtaout26.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0N2J006W9EJQUL50@mtaout26.012.net.il>; Sun, 16 Mar 2014 18:16:38 +0200 (IST) In-reply-to: <87wqfukd7v.fsf@gmail.com> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 80.179.55.182 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:170420 Archived-At: > From: Jambunathan K > Cc: Dmitry Gutov , emacs-devel@gnu.org > Date: Sun, 16 Mar 2014 09:27:08 +0530 > > > To the below list, I would also add this (just for emphasis). Eli, I am > not saying it is an oversight on your part. So don't pounce on me :-) It's not an oversight, because I didn't intend to provide a checklist of how to document a feature, only how a description suitable for a manual _differs_ from a doc string. > 1. Document the design decisions Definitely not! Users are not interested in design decisions, they are interested in how things should work as designed. Sometimes, describing the latter will hint (or more than hint) on the former, but it's definitely not an end in itself. > 2. Provide some historical context or add a personal note Not needed, IMO, and will generally bloat the documentation for no good reason. > 3. Consolidate (as in "bring together") various aspects of the > feature "scattered" across multiple files or symbols in a single > node and provide a cohesive narrative. Yes, a feature should be generally described in one place, and then cross-references to that place put in related sections. > The nodes on overlay, text properties, extents is a good example of (1). That's the odd one out, and the reason is lost in history that only old men such as myself remember.