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: Guile in Emacs Date: Thu, 15 Apr 2010 09:11:48 -0700 Message-ID: <7FD4F9AC1DDE4490898CB06959609E96@us.oracle.com> References: <4B8147A9.7030504@gmail.com> <873a0cyv3r.fsf@lola.goethe.zz> <87aauiho3y.fsf_-_@lifelogs.com><1271028837.6164.55.camel@dell-desktop.example.com><1271102739.6067.38.camel@dell-desktop.example.com><8039yz34ka.fsf@tiny.isode.net><1271173887.6067.53.camel@dell-desktop.example.com> <87FA5F05CB9C41409B9E72BD06D7C8CF@us.oracle.com><87fx2xp839.fsf@lola.goethe.zz><3EFDD45EB5AD4018B8FEA8F13CFEDA32@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1271349769 11198 80.91.229.12 (15 Apr 2010 16:42:49 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 15 Apr 2010 16:42:49 +0000 (UTC) Cc: 'David Kastrup' , emacs-devel@gnu.org To: "'Jeff Clough'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Apr 15 18:42:46 2010 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1O2S9N-0001Jx-GJ for ged-emacs-devel@m.gmane.org; Thu, 15 Apr 2010 18:42:46 +0200 Original-Received: from localhost ([127.0.0.1]:35484 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O2S9M-00017T-NM for ged-emacs-devel@m.gmane.org; Thu, 15 Apr 2010 12:42:44 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1O2RgA-0000X8-2v for emacs-devel@gnu.org; Thu, 15 Apr 2010 12:12:34 -0400 Original-Received: from [140.186.70.92] (port=51303 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O2Rg2-0000N4-9q for emacs-devel@gnu.org; Thu, 15 Apr 2010 12:12:33 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1O2Rfz-000688-3h for emacs-devel@gnu.org; Thu, 15 Apr 2010 12:12:26 -0400 Original-Received: from rcsinet11.oracle.com ([148.87.113.123]:45880) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2Rfy-00067g-T0; Thu, 15 Apr 2010 12:12:23 -0400 Original-Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rcsinet11.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id o3FGCINQ005222 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 15 Apr 2010 16:12:20 GMT Original-Received: from acsmt355.oracle.com (acsmt355.oracle.com [141.146.40.155]) by acsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o3FBhAUU006180; Thu, 15 Apr 2010 16:12:16 GMT Original-Received: from abhmt008.oracle.com by acsmt354.oracle.com with ESMTP id 178709451271347909; Thu, 15 Apr 2010 09:11:49 -0700 Original-Received: from dradamslap1 (/130.35.178.194) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 15 Apr 2010 09:11:49 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcrckyaiY/NURv7MTZ2nqUmIGr/4aAAH7kPw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: acsmt355.oracle.com [141.146.40.155] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090203.4BC73AE1.005A:SCFMA4539814,ss=1,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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:123711 Archived-At: > > It is a choice whether we want clicking a cross-reference > > in an Emacs manual to take you (a) to a section of the > > same manual or another manual available locally > > or (b) to a section of a manual that might be on the Web. A > > cross reference might well be to a non-local or a non-GNU > > manual or specification. What is important is that we give > > users access to the specific info they need. > > It is also important for that information to be available in > one place. When the information you need is split between two > (or more) manuals, a wiki, a HOW-TO and Wonder Tommy's blog, > it sucks, no matter how well cross-referenced or searchable it is. > There's a better way and Emacs has it (for the most part). It is a classic documentation dilemma that you cannot have everything you want to know about something in a single place. What you want to know about something is different from what person X wants/needs to know. And what you need to know today is different from what you need tomorrow. This is still a problem even if you are dealing with only a single, local manual that is self-contained as a whole (contains all of the info on its subject). You might want to see one organization into manual sections and person X might want to see a different organization. And for you alone, the optimal organization might be different today (looking for info on some topic) from tomorrow (looking with a different eye). IOW, there are *trade-offs*. People dealing with documentation professsionally deal with such trade-offs everyday - it's a significant part of what they do. Of course, there are trade-offs that many users might agree are reasonably good ones, and there are trade-offs that many would agree are poor ones. Picking an extremely poor documention organization as your example does not invalidate the fact that trade-offs are always required. > I've never subscribed to the theory that just because a feature is > described on some web page out there, and not in the official manual, > that it's "documented". Why people want to see this as the success of > the internet rather than as a failure of the documentation is > beyond me. No one mentioned "some web page out there". You are simply arguing about a straw man. The point is that Common Lisp has a standard definition (at least one!), and the language is documented. To the extent that Emacs supports some or all of that standard to various degrees, the Emacs documentation needs to: 1. Be clear about that support, specifying which CL standard is supported and specifying exactly any divergences from that standard. 2. Give clear guidance about any Emacs-specific uses of particular features from that standard. That does not imply that the *Emacs* doc needs to reproduce, in addition, a complete documentation of the standard language that it (more or less) supports. That's the point of having a standard that can be referenced. Nothing prevents the Emacs doc from giving examples and explanation of how to use particular Common Lisp constructs in an Emacs environment. Quite the contrary. > Keep the information itself in one place It's a wonderfully naive idea. Get involved with documenting something (non-trivial) and you will soon discover the trade-offs. Keeping X "in one place" begs the question of what X is, how much X encompasses, and what point of view X is regarded from (audience background, audience quest/need). > that I can put on a tablet as a PDF, or print out and take with > me on an overnight. Not everyone reads their docs from within > Emacs all of the time. > > For what it's worth.