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: RE: tutorial or guidebook text for some complex topics Date: Mon, 23 Oct 2006 14:14:26 -0700 Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1161638120 3027 80.91.229.2 (23 Oct 2006 21:15:20 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 23 Oct 2006 21:15:20 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 23 23:15:15 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 1Gc78Z-0001NN-Lj for ged-emacs-devel@m.gmane.org; Mon, 23 Oct 2006 23:15:12 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Gc78Y-0007cu-RQ for ged-emacs-devel@m.gmane.org; Mon, 23 Oct 2006 17:15:10 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Gc77y-0007R1-3J for emacs-devel@gnu.org; Mon, 23 Oct 2006 17:14:34 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Gc77w-0007Q2-3B for emacs-devel@gnu.org; Mon, 23 Oct 2006 17:14:33 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Gc77v-0007Px-Sg for emacs-devel@gnu.org; Mon, 23 Oct 2006 17:14:31 -0400 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA:32) (Exim 4.52) id 1Gc77v-0007vY-NH for emacs-devel@gnu.org; Mon, 23 Oct 2006 17:14:31 -0400 Original-Received: from rgmsgw02.us.oracle.com (rgmsgw02.us.oracle.com [138.1.186.52]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id k9NLESXP008424 for ; Mon, 23 Oct 2006 16:14:29 -0500 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 k9NLERql011397 for ; Mon, 23 Oct 2006 15:14:27 -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) In-Reply-To: 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:61067 Archived-At: > 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. I think that if you propose good accessor (and constructor) functions, they have a good chance of being accepted. There's opposition to making data structures opaque, but that doesn't mean that you should *have* to look under the hood. I agree about that, of course: not opaque, and not obliging people to pick things apart piece by piece, referring to the doc or other code as a roadmap at every turn. That's why `map-keymap' was added, for example. I'm very glad it was. Thank you, to whomever was responsible. AFAIK, regarding keymaps, the main missing accessor function is the one that parses a "keyelt" (which can be as simple as a function symbol, but as complex as a big `menu-item'). I don't have any particular suggestions to make here. Yes, I agree about keyelt (though there might be a better name for that). I was thinking of menu-item details like the prompt string, whether `menu-item' is present, key-binding reminder (shortcut), and so on. The form of a menu item is quite variable, and accessor functions could help reduce that complexity (e.g. some combinations can only occur together). I was reminded of this recently, when I discovered that Imenu used string values instead of symbols, following symbol `keymap'. The spec in the manual allows for this, but AFAIK, this is the only place where that is done. Code that treats keymaps in a general fashion has many different cases to consider, largely for "hysterical raisins" (SM, 2006). Access functions would address those cases. > 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. You're in the best position to start writing this. If you feel like you're not up-to-the-task, try it anyway and let other people's feedback do the grunt of the work. GNU won't use my text, because my employer won't sign papers. I can contribute suggestions to existing proposals, however, as well as general ideas (like this one, to add some pedagogical doc for our complex but important data structures). I also will purposely try to stay out of this one to some extent, based on the fiasco that occurred the last time I made tutorial suggestions. Instead of considering the multiple suggestions made, we plunged down a rat hole of anti-mouse alarmism. AFAIK, there was no constructive outcome, in spite of some good suggestions. (Take that with a sense of humor, or don't bother to take it at all, please.) A start, I think, would be for interested people to contribute examples, typical and perhaps not so typical (gotchas). Good examples can form the core of a pedagogical text. We could discuss the examples first, and then go on to discuss the narrative thread. Another good way to start would be for someone to try to explain, using examples, what the manual already says using a concise, rigorous specification. For example, try explaining the syntax of font-lock-keywords with examples of the various cases, perhaps using some existing code as illustration. This could be done here or, if people consider that a distraction, it could be done on a page or two at Emacs Wiki. The wiki is a good place for collaborative editing, but email is generally better for dialog.