From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Miles Bader Newsgroups: gmane.emacs.xemacs.design,gmane.emacs.devel Subject: Re: INFO on add-ons Date: 04 Sep 2002 10:39:37 +0900 Sender: xemacs-design-admin@xemacs.org Message-ID: References: <3D728E82.8000808@cox.net> <87vg5pe4pr.fsf@emacswiki.org> <3D73F919.5010706@cox.net> <873csqr8b9.fsf@emacswiki.org> <87u1l6pok2.fsf@emacswiki.org> Reply-To: Miles Bader NNTP-Posting-Host: localhost.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1031103511 14697 127.0.0.1 (4 Sep 2002 01:38:31 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Wed, 4 Sep 2002 01:38:31 +0000 (UTC) Cc: emacs-devel@gnu.org, xemacs-design@xemacs.org Return-path: Original-Received: from gwyn.tux.org ([207.96.1.200]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 17mP7l-0003ou-00 for ; Wed, 04 Sep 2002 03:38:29 +0200 Original-Received: from gwyn.tux.org (localhost.localdomain [127.0.0.1]) by gwyn.tux.org (8.9.3/8.9.1) with ESMTP id VAA21961; Tue, 3 Sep 2002 21:40:03 -0400 Original-Received: (from turnbull@localhost) by gwyn.tux.org (8.9.3/8.9.1) id VAA21923 for xemacs-design-mailman@xemacs.org; Tue, 3 Sep 2002 21:39:43 -0400 Original-Received: (from mail@localhost) by gwyn.tux.org (8.9.3/8.9.1) id VAA21919 for turnbull@tux.org; Tue, 3 Sep 2002 21:39:42 -0400 Original-Received: from TYO201.gate.nec.co.jp (TYO201.gate.nec.co.jp [202.32.8.214]) by gwyn.tux.org (8.9.3/8.9.1) with ESMTP id VAA21915 for ; Tue, 3 Sep 2002 21:39:41 -0400 Original-Received: from mailgate4.nec.co.jp ([10.7.69.197]) by TYO201.gate.nec.co.jp (8.11.6/3.7W01080315) with ESMTP id g841ddE16403; Wed, 4 Sep 2002 10:39:39 +0900 (JST) Original-Received: from mailsv4.nec.co.jp (mailgate51.nec.co.jp [10.7.69.190]) by mailgate4.nec.co.jp (8.11.6/3.7W-MAILGATE-NEC) with ESMTP id g841dd519924; Wed, 4 Sep 2002 10:39:39 +0900 (JST) Original-Received: from mcsss2.ucom.lsi.nec.co.jp ([10.30.114.133]) by mailsv4.nec.co.jp (8.11.6/3.7W-MAILSV4-NEC) with ESMTP id g841dch10242; Wed, 4 Sep 2002 10:39:38 +0900 (JST) Original-Received: from mcspd15.ucom.lsi.nec.co.jp (mcspd15 [10.30.114.174]) by mcsss2.ucom.lsi.nec.co.jp (8.10.2+Sun/3.7Wlsi_mx_6.0) with ESMTP id g841dbs24045; Wed, 4 Sep 2002 10:39:37 +0900 (JST) Original-Received: by mcspd15.ucom.lsi.nec.co.jp (Postfix, from userid 31295) id 5979E36F4; Wed, 4 Sep 2002 10:39:37 +0900 (JST) Original-To: Alex Schroeder System-Type: i686-pc-linux-gnu Blat: Foop In-Reply-To: <87u1l6pok2.fsf@emacswiki.org> Original-Lines: 54 X-XEmacs-List: design Errors-To: xemacs-design-admin@xemacs.org X-BeenThere: xemacs-design@xemacs.org X-Mailman-Version: 2.0.1 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Discussion of design and features for XEmacs. List-Unsubscribe: , Xref: main.gmane.org gmane.emacs.xemacs.design:1363 gmane.emacs.devel:7420 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:7420 Alex Schroeder writes: > Only if doc strings and commentaries (readable via package finder in > Emacs, perhaps there needs to be a better interface?) fail, should we > need to write Info. As I said this is for newbies, and pulling stuff > together. I use doc-strings more often in my daily work, but I think info files are very useful for getting a broader view of a package. I don't think we should avoid writing manual entries just because there are doc-strings (and the package finder is so pathetic that it's not really much of a contender for anything; at best, it's a way of seeing a list of what packages there are). Other source of documentation tend to be scattered all over the place, and would be much more useful if they were pulled together -- and what better way than by using info (perhaps automatically generated info)? Usually when I write manual entries I mostly copy the doc-strings I wrote earlier, make mechanical changes like replacing FOO with @var{foo}, and change the wording slightly to fit the manual format better (e.g., remove duplicate text that can be shared more easily in the manual page). Perhaps what we ought to do is make it easier to produce a coherent info node(s) from a package's existing information. E.g., if we could automatically take the `;;; Commentary:' header from and the doc-strings an elisp file, and massage them appropiately, maybe the result would be a good start for making an info node. Like checkdoc, but even more whizzy (call it `makedoc' :-)... The problem, of course, is that the elisp file will get updated later, and if you re-run `makedoc' you'll have to go and re-do all the cleanup you had to do the last time, so anything we could do to make the automatic result better would be good. [note that currently it's very common for doc-strings and manual entries to go out of sync, though] One thing that might make the job easier would be embedding various formatting directives in doc-strings, which would be removed or intepreted at display-time by the help commands (I think computers are fast enough these days that this wouldn't be a problem), and could be used to perform more coherent documentation. A simple example would be allowing the use of texinfo forms like @var{foo} or @code{foo} in doc-strings. An alternative to the above might be a real on-demand info-page creator that would prodce more `mechanical' results than a real manual, but could still benefit from all the power of the info browser (which really is a good tool; we should use it!). [I've long thought that the current `package browser' should be replaced by automatically generated info nodes.] -Miles -- Suburbia: where they tear out the trees and then name streets after them.