From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Per Abrahamsen Newsgroups: gmane.emacs.xemacs.beta,gmane.emacs.devel Subject: Re: Emacs setup assistants Date: Sun, 30 May 2004 10:15:01 +0200 Organization: The Church of Emacs Sender: xemacs-beta-admin@xemacs.org Message-ID: References: <87zn847n6a.fsf@mail.jurta.org> <40B7E6CB.30602@cox.net> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1085905096 6809 80.91.224.253 (30 May 2004 08:18:16 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 30 May 2004 08:18:16 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: xemacs-beta-admin@xemacs.org Sun May 30 10:18:07 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 1BULWB-0007lB-00 for ; Sun, 30 May 2004 10:18:07 +0200 Original-Received: from gwyn.tux.org ([199.184.165.135]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1BULWA-0004mH-00 for ; Sun, 30 May 2004 10:18:07 +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 i4U8G6o15773; Sun, 30 May 2004 04:16:06 -0400 Original-Received: (from turnbull@localhost) by gwyn.tux.org (8.11.6p2/8.9.1) id i4U8FEe14968 for xemacs-beta-mailman@xemacs.org; Sun, 30 May 2004 04:15:15 -0400 Original-Received: (from mail@localhost) by gwyn.tux.org (8.11.6p2/8.9.1) id i4U8FCW14913 for turnbull@tux.org; Sun, 30 May 2004 04:15:12 -0400 Original-Received: from main.gmane.org (main.gmane.org [80.91.224.249]) by gwyn.tux.org (8.11.6p2/8.9.1) with ESMTP id i4U8FBo14894 for ; Sun, 30 May 2004 04:15:11 -0400 Original-Received: from list by main.gmane.org with local (Exim 3.35 #1 (Debian)) id 1BULTG-0000hx-00 for ; Sun, 30 May 2004 10:15:10 +0200 Original-Received: from sheridan.dina.kvl.dk ([130.225.40.227]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 30 May 2004 10:15:06 +0200 Original-Received: from abraham by sheridan.dina.kvl.dk with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 30 May 2004 10:15:06 +0200 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: xemacs-beta@xemacs.org Original-To: xemacs-beta@xemacs.org Original-Lines: 21 Original-X-Complaints-To: usenet@sea.gmane.org X-Gmane-NNTP-Posting-Host: sheridan.dina.kvl.dk X-Face: +kRV2]2q}lixHkE{U)mY#+6]{AH=yN~S9@IFiOa@X6?GM|8MBp/ Mail-Copies-To: nobody User-Agent: Gnus/5.110002 (No Gnus v0.2) Emacs/21.3 (gnu/linux) Cancel-Lock: sha1:E+OV2sigrk1Rul14rMy6aLAG7b0= 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:14901 gmane.emacs.devel:24209 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:24209 "David A. Cobb" writes: > I would really hate to see the information separated physically from > the code! That's a guarantee one of them will be wrong. There are two levels of documentation. One is tool-centric, and the other is user centric. Both are needed. Tool-centric documentation says "I'm a tool, here is what I can do". User-centric documentation says "I'm a user. I have this problem. Here is how I solved it". The tool-centric documentation should be as close to the code as possible, in order to stay complete and up to date. Doc-strings and Customize are great for providing tool-centric documentation. But user-centric documentation needs another viewpoint. Assistants are supposed to be user-centric, otherwise they would just be another interface to Customize. I don't care whether they are written in a markup language with embedded Lisp, or on Lisp with an embedded markup language. But if they are written in Lisp, they will (logically) be separate from the main code body, unlike doc strings and defcustoms.