From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Jambunathan K Newsgroups: gmane.emacs.devel Subject: Re: Trunk still not open Date: Sun, 16 Mar 2014 09:27:08 +0530 Message-ID: <87wqfukd7v.fsf@gmail.com> 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> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1394942167 29829 80.91.229.3 (16 Mar 2014 03:56:07 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 16 Mar 2014 03:56:07 +0000 (UTC) Cc: emacs-devel@gnu.org, Dmitry Gutov To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Mar 16 04:56:16 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 1WP2BM-0002yt-4Y for ged-emacs-devel@m.gmane.org; Sun, 16 Mar 2014 04:56:16 +0100 Original-Received: from localhost ([::1]:52216 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WP2BL-0006F2-Rn for ged-emacs-devel@m.gmane.org; Sat, 15 Mar 2014 23:56:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42505) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WP2BD-00062o-SQ for emacs-devel@gnu.org; Sat, 15 Mar 2014 23:56:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WP2B8-0000ir-GU for emacs-devel@gnu.org; Sat, 15 Mar 2014 23:56:07 -0400 Original-Received: from mail-pb0-x22f.google.com ([2607:f8b0:400e:c01::22f]:33931) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WP2B8-0000in-9v; Sat, 15 Mar 2014 23:56:02 -0400 Original-Received: by mail-pb0-f47.google.com with SMTP id up15so4279885pbc.34 for ; Sat, 15 Mar 2014 20:56:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:references:date:message-id:user-agent :mime-version:content-type; bh=caecFy+Y/7wXfB6cx00BOfHsqd8gShzeEAG7ZPKAsVo=; b=BKwLqoHrgwryoxFCU8rXjNRXg83hAkBVJ+4Gl5kQxt2WX0orr+6VAz/ykuQ/+ZSPwY ISfVYm+zpCC93R2yZ9LGblHneHuAECNhGevbwf8d/snhu8aAMJZxhxKGF9xbK1kXWmJS RGs5frpH5ZfAiH7ADaO+c0QyFptxwKyu1cf6y9ZvuYzI+fFFVWube1inKnhWqyou71zM 1yeX32STbZ5Sqw78rxe7dotCSjiDnmhSCbpFXkB/bkXOHPL9m3QR/lXkrNoLCIM9so4R AflcbuXkDW1Tv1PJiH2j4nM2Rg8DfJlQRi2cboQ712m1hJOHCSfTvckDXU6WsyFaWYI+ GWoQ== X-Received: by 10.68.239.70 with SMTP id vq6mr63779pbc.152.1394942161196; Sat, 15 Mar 2014 20:56:01 -0700 (PDT) Original-Received: from debian-6.05 ([101.63.215.189]) by mx.google.com with ESMTPSA id sm5sm50311545pab.19.2014.03.15.20.55.58 for (version=TLSv1.1 cipher=RC4-SHA bits=128/128); Sat, 15 Mar 2014 20:56:00 -0700 (PDT) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2607:f8b0:400e:c01::22f 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:170412 Archived-At: 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 :-) 1. Document the design decisions 2. Provide some historical context or add a personal note 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. The nodes on overlay, text properties, extents is a good example of (1). If I want to learn about text properties or overlays, I can progress quickly by starting with reference manual than by starting with underlying C files. (2) is very very important for software like Emacs whose life-term is measured in decades and not in years. I saw a recent commit where the documentation used the word "now" in questionable manner. (I cannot locate the commit right now) Use of such words is highly questionable and shows a lack of appreciation of historical context. In summary, I would say the "foreword" or "preamble" part of a Info chapter is "equally" the most important part and can be exploited by the author - both to give his creativity an expression and stimulate an explorer by having his curiosity sufficiently aroused. Eli Zaretskii writes: > 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