From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: tutorial or guidebook text for some complex topics Date: Mon, 23 Oct 2006 11:35:12 -0700 Message-ID: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1161628629 26511 80.91.229.2 (23 Oct 2006 18:37:09 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 23 Oct 2006 18:37:09 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 23 20:37:04 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1Gc4eH-0003vK-4P for ged-emacs-devel@m.gmane.org; Mon, 23 Oct 2006 20:35:46 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Gc4eG-00013q-K5 for ged-emacs-devel@m.gmane.org; Mon, 23 Oct 2006 14:35:44 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Gc4e3-000135-L3 for emacs-devel@gnu.org; Mon, 23 Oct 2006 14:35:31 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Gc4dz-00011p-GD for emacs-devel@gnu.org; Mon, 23 Oct 2006 14:35:30 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Gc4dz-00011m-Bb for emacs-devel@gnu.org; Mon, 23 Oct 2006 14:35:27 -0400 Original-Received: from [148.87.113.118] (helo=rgminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA:32) (Exim 4.52) id 1Gc4dz-0008Ej-61 for emacs-devel@gnu.org; Mon, 23 Oct 2006 14:35:27 -0400 Original-Received: from rgmsgw02.us.oracle.com (rgmsgw02.us.oracle.com [138.1.186.52]) by rgminet01.oracle.com (Switch-3.2.4/Switch-3.1.6) with ESMTP id k9NIZDp6026105 for ; Mon, 23 Oct 2006 12:35:13 -0600 Original-Received: from dradamslap (dradams-lap.us.oracle.com [130.35.177.126]) by rgmsgw02.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with SMTP id k9NIZC8o003845 for ; Mon, 23 Oct 2006 12:35:12 -0600 Original-To: "Emacs-Devel" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:61054 Archived-At: Suggestion for after the release - There are a few fundamental data structures that Emacs uses that are quite complex and variable in form. I'm thinking of things like keymaps (including menus), font-lock-keywords, and faces/text properties. These complex structures are generally specified accurately in the Elisp manual. However, it is not always easy to learn about them by simply reading such a rigorous specification. My own experience, at least, bears that out. I've spent quite a bit of time trying to grasp what these things are and the various forms they can take, and most of my (still incomplete) understanding of them has come from coding and examining code that manipulates them. These structures are complex, with multiple possible cases to consider. They are not abstract data types with defined accessor functions, so code that manipulates them must explicitly "parse" them as cons trees, being careful at each access step. Personally, I'd prefer to see them treated as ADTs with accessor functions, but I expect that others will disagree, so I'm not suggesting that change. What I would suggest is that the documentation be beefed up a little, to help users understand these critters better. I'd like to suggest that these topics be dealt with in a tutorial or user-guide manner, with examples to help people learn what these critters can look like and how to use them. Adding pedagogical doc for each of these (and there may be some others) would help, but that doc probably doesn't belong in the Elisp manual, which is essentially a reference manual. A separate document or documents would likely be appropriate. An analogy is the Emacs-Lisp Intro book, which leads you by the hand to learn some Emacs-Lisp. I don't know if that book would itself be a good target for these topics, or if, instead, a separate document would be better. WDOT? Anyone else think that we could use some more explanation for these topics?