From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.xemacs.design,gmane.emacs.devel Subject: Re: INFO on add-ons Date: Wed, 4 Sep 2002 06:42:50 +0200 (IST) Sender: xemacs-design-admin@xemacs.org Message-ID: References: <873csqr8b9.fsf@emacswiki.org> NNTP-Posting-Host: localhost.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: main.gmane.org 1031114753 1916 127.0.0.1 (4 Sep 2002 04:45:53 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Wed, 4 Sep 2002 04:45:53 +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 17mS33-0000Ud-00 for ; Wed, 04 Sep 2002 06:45:49 +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 AAA30379; Wed, 4 Sep 2002 00:47:16 -0400 Original-Received: (from turnbull@localhost) by gwyn.tux.org (8.9.3/8.9.1) id AAA30348 for xemacs-design-mailman@xemacs.org; Wed, 4 Sep 2002 00:46:08 -0400 Original-Received: (from mail@localhost) by gwyn.tux.org (8.9.3/8.9.1) id AAA30339 for turnbull@tux.org; Wed, 4 Sep 2002 00:46:07 -0400 Original-Received: from is.elta.co.il (is.elta.co.il [199.203.121.2]) by gwyn.tux.org (8.9.3/8.9.1) with ESMTP id AAA30334 for ; Wed, 4 Sep 2002 00:46:05 -0400 Original-Received: from is (is [199.203.121.2]) by is.elta.co.il (8.9.3/8.8.8) with SMTP id GAA27291; Wed, 4 Sep 2002 06:42:50 +0200 (IST) X-Sender: eliz@is Original-To: Alex Schroeder In-Reply-To: <873csqr8b9.fsf@emacswiki.org> 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:1372 gmane.emacs.devel:7429 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:7429 On Wed, 4 Sep 2002, Alex Schroeder wrote: > Most of the code I write fits into an elisp file. Instead of writing > texinfo, and worrying about correct installation, and copyright info, > and layouting, and cross references, I would rather just put the stuff > in the Commentary section, and provide as much help as possible in the > defgroup, defcustom, and defun statements. These docstrings are what > programmers and users use in their daily life. The manuals are not > used very often. The doc strings have a disadvantage that they lack a broader context. That is, a doc string documents its parent object, and sometimes a small number of related objects, but it doesn't give you a large-scale view. Comments are nice, but they lack an efficient mechanism for looking up the information. Texinfo solves these problems (the latter one is solved via index-search and other ways of searching Info manuals). So a well-indexed Texinfo manual is IMHO a necessary element of documenting software.