From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: INFO on add-ons Date: Wed, 04 Sep 2002 22:46:53 -0400 Sender: emacs-devel-admin@gnu.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: rms@gnu.org NNTP-Posting-Host: localhost.gmane.org X-Trace: main.gmane.org 1031194284 21701 127.0.0.1 (5 Sep 2002 02:51:24 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 5 Sep 2002 02:51:24 +0000 (UTC) Cc: alex@emacswiki.org, emacs-devel@gnu.org Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 17mmjr-0005dt-00 for ; Thu, 05 Sep 2002 04:51:23 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 17mnJL-0001ho-00 for ; Thu, 05 Sep 2002 05:28:03 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10) id 17mmlR-0005Lh-00; Wed, 04 Sep 2002 22:53:01 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10) id 17mmfZ-0003Z9-00 for emacs-devel@gnu.org; Wed, 04 Sep 2002 22:46:57 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10) id 17mmfW-0003Xn-00 for emacs-devel@gnu.org; Wed, 04 Sep 2002 22:46:56 -0400 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by monty-python.gnu.org with esmtp (Exim 4.10) id 17mmfW-0003XJ-00 for emacs-devel@gnu.org; Wed, 04 Sep 2002 22:46:54 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.10) id 17mmfV-000792-00; Wed, 04 Sep 2002 22:46:53 -0400 Original-To: miles@gnu.org In-Reply-To: (message from Miles Bader on 04 Sep 2002 10:39:37 +0900) Errors-To: emacs-devel-admin@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.0.11 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: Xref: main.gmane.org gmane.emacs.devel:7501 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:7501 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. A real manual is nothing like a collection of doc strings. If you use the doc strings as a starting point for writing a manual, you will have to do a lot of rewriting to make it into a good manual. 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, Rewriting the doc strings into a real manual is a lot of work. Nobody who has done this job properly would consider redoing it just because the doc strings have changed. It is much less work to update the manual directly, and that's what people do. If you are using `makedoc' over and over, for different versions of one program, you are not using it right. so anything we could do to make the automatic result better would be good. This would be a grave mistake, because it would encourage people to use the output of `makedoc' as a manual itself, without the necessary rewriting to make a good manual. In fact, I think that having a `makedoc' at all is a grave mistake for the same reason. Assuming you intend to write a manual starting from doc strings, the work of collecting them from a .el file is nothing compared with the work of rewriting them. What I think might be useful would be a mode with interactive commands that help convert from doc string style to Texinfo style. They would have to be interactive commands, because there is not enough info in a doc string to produce proper Texinfo automatically. Suitable commands could make this editing task easier, but could not make it automatic. As for indexing in doc strings, that might perhaps be a useful help feature in its own right, and it might be worth implementing for that reason, but that alone won't make `makedoc' produce adequate output.