From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: David Kastrup Newsgroups: gmane.emacs.xemacs.beta,gmane.emacs.devel Subject: Re: Emacs setup assistants Date: 20 May 2004 22:57:08 +0200 Sender: xemacs-beta-admin@xemacs.org Message-ID: References: <87zn847n6a.fsf@mail.jurta.org> <1438-Thu20May2004203119+0300-eliz@gnu.org> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1085086937 9851 80.91.224.253 (20 May 2004 21:02:17 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 20 May 2004 21:02:17 +0000 (UTC) Cc: juri@jurta.org, xemacs-beta@xemacs.org, emacs-devel@gnu.org Original-X-From: xemacs-beta-admin@xemacs.org Thu May 20 23:02:08 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BQug4-0001Fx-00 for ; Thu, 20 May 2004 23:02:08 +0200 Original-Received: from gwyn.tux.org ([199.184.165.135]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BQug3-0000bw-00 for ; Thu, 20 May 2004 23:02:08 +0200 Original-Received: from gwyn.tux.org (localhost.localdomain [127.0.0.1]) by gwyn.tux.org (8.11.6p2/8.9.1) with ESMTP id i4KKwBs22521; Thu, 20 May 2004 16:58:11 -0400 Original-Received: (from turnbull@localhost) by gwyn.tux.org (8.11.6p2/8.9.1) id i4KKvE521921 for xemacs-beta-mailman@xemacs.org; Thu, 20 May 2004 16:57:14 -0400 Original-Received: (from mail@localhost) by gwyn.tux.org (8.11.6p2/8.9.1) id i4KKvBc21900 for turnbull@tux.org; Thu, 20 May 2004 16:57:11 -0400 Original-Received: from fencepost.gnu.org (fencepost.gnu.org [199.232.76.164]) by gwyn.tux.org (8.11.6p2/8.9.1) with ESMTP id i4KKvBs21895 for ; Thu, 20 May 2004 16:57:11 -0400 Original-Received: from localhost ([127.0.0.1] helo=lola.goethe.zz) by fencepost.gnu.org with esmtp (Exim 4.34) id 1BQubG-0000Xt-6O; Thu, 20 May 2004 16:57:10 -0400 Original-To: Eli Zaretskii In-Reply-To: <1438-Thu20May2004203119+0300-eliz@gnu.org> Original-Lines: 90 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3.50 X-XEmacs-List: beta Errors-To: xemacs-beta-admin@xemacs.org X-BeenThere: xemacs-beta@xemacs.org X-Mailman-Version: 2.0.13 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: XEmacs Beta Testers List-Unsubscribe: , Xref: main.gmane.org gmane.emacs.xemacs.beta:14777 gmane.emacs.devel:23799 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:23799 "Eli Zaretskii" writes: > > From: David Kastrup > > Date: 20 May 2004 19:00:41 +0200 > > > > If we could replace things like > > "To do this, press M-x customize-variable RET > > preview-default-option-list RET and make sure that [...]" with > > "press here to customize this behavior", then people would not be > > forced to jump between customization buffers and manual forth and > > back. > > I support this goal. > > > > > Isolated customization strings don't do that. > > > > > > I didn't say isolated strings. > > > > You said, this is nothing that could not be done with variable > > documentation/customize documentation. This stuff is > > variable-specific. You have no idea in what sequence the user might > > try customizing variables. Therefore, you are working with isolated > > strings. They are not arranged by topic, but by variables. > > > > That's isolated, without context. > > I think we might be miscommunicating. The text I had in mind was > normal text that we see even today in the Customize buffer. For > example, here is the text we see at the beginning of that buffer: > > This is a customization buffer for group Emacs. > `Raised' buttons show active fields; type RET or click mouse-1 > on an active field to invoke its action. Editing an option value > changes the text in the buffer; invoke the State button and > choose the Set operation to set the option value. > Invoke Help for more information. > > We could have similar text fragments that guide the user thru the > setup process. But those text fragments would have to appear between the variables in question. And explanatory texts are more effective if you can highlight stuff, include cross references to the manual and so on. Anyway, you think that something like assistants should best be tackled from the angle of documentation strings, I think that it would be better to approach this from printable manuals, like Texinfo stuff. Our disagreement would become less relevant if the manual and the documentation strings were written basically in the same language. We already had a proposal of using stuff like @var{...} or so to mark up variables in the DOC strings. If we allow at least a solid subset of Texinfo, with cross references and fonts and similar hoopla, we don't need to solve our "italics or not" and similar problems separately for info and DOC strings. If this language also makes it possible to create widgets and active code, that would be an advantage. We would probably want to preprocess this super-Texinfo before turning it into a printed or HTML version: it would be nice if an Emacs-internal makeinfo could just show the the available menus and menu structure by calling them by name and keymap, for example. > In short, I'm talking about specialized interactive tutorial, and it > seemed to me that Customize, if appropriately enhanced and > augmented, could do the job. But even if not, I don't see why an > infrastructure for such a feature could not have some other Lispy > foundation, rather than a Texinfo foundation. Because "Lispy foundations" mix text and code in a manner that does not have a human-readable appeal. And that means that it becomes less feasible for a _programmer_ to start with a skeleton, and then let a _writer_ without much Lisp experience improve the material. A format which I can throw at somebody not knowing Emacs and tell him "could you proof-read this for me?" is a nice multiplier. In particular, since you can also throw it at somebody not Emacs-savvy and ask him "could you translate this into a different language for me?". We will at some time probably need to convert from and back to XML, so that people may use their favorite XML editors and tools for helping. However, as an internal format XML is not a good idea within Emacs: we already noticed that there are rather few existing DOC strings that actually clash with Texinfo. With < > tag syntax, we'd have much more of a problem. -- David Kastrup, Kriemhildstr. 15, 44793 Bochum