From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Rajesh Vaidheeswarran Newsgroups: gmane.emacs.devel Subject: Re: `whitespace-describe' function missing Date: Tue, 13 May 2003 10:38:39 -0400 (EDT) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <5xfzolxfuv.fsf@kfs2.cua.dk> Reply-To: rv@gnu.org NNTP-Posting-Host: main.gmane.org X-Trace: main.gmane.org 1052838803 26981 80.91.224.249 (13 May 2003 15:13:23 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Tue, 13 May 2003 15:13:23 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Tue May 13 17:13:21 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19FbDn-0005UX-00 for ; Tue, 13 May 2003 16:57:39 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 19FbKj-000510-00 for ; Tue, 13 May 2003 17:04:49 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19FbEs-0003ww-00 for emacs-devel@quimby.gnus.org; Tue, 13 May 2003 10:58:46 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19FbEb-0003vR-00 for emacs-devel@gnu.org; Tue, 13 May 2003 10:58:29 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19Fb6I-00010H-00 for emacs-devel@gnu.org; Tue, 13 May 2003 10:49:54 -0400 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19FavP-0004qB-00 for emacs-devel@gnu.org; Tue, 13 May 2003 10:38:39 -0400 Original-Received: from localhost ([127.0.0.1] helo=gnu.org) by fencepost.gnu.org with esmtp (Exim 4.10) id 19FavP-0006Er-00; Tue, 13 May 2003 10:38:39 -0400 Original-Received: by fencepost.gnu.org with BradMail(MH 6.8.4); Tue, 13 May 2003 10:38:39 -0400 (EDT) Original-To: storm@cua.dk (Kim F. Storm) In-reply-to: Message from storm@cua.dk (Kim F. Storm) of "14 Apr 2003 17:23:36 N." <5xfzolxfuv.fsf@kfs2.cua.dk> X-LoopDetect: rv@gnu.org Original-cc: bob@rattlesnake.com X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Emacs development discussions. List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:13832 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:13832 Sorry for a long delay... I just got the access to subversions fixed.. and added the :link to the commentary section as you suggested.. However, I'm not sure there was any pereptible change in the customization section. Please feel free to diff the change and let me know if there was anything that I missed. Regarding the `whitespace-describe' ... It seemed appropriate to me that there be something central that described the library and its purpose. The doc strings in each of the defuns, I believed, were to describe what the defun did, and not to describe any higher level functionality of the library itself. In the case of whitespace.el, I'd have had to duplicate a lot of the docstrings all over the place, since all the defuns basically are checking / fixing the same set of whitespaces. If you feel there is a better way, whereby we wouldn't have to duplicate docstrings, and also present documentation on the library itself, please let me know.. I thought the Commentary link was neat, but it didn't seem to work for me. If it did, I'd have nixed whitespace-describe and moved the lib description to the Commentary section. Thanks rv In a previous message, Kim F. Storm writes: > "Robert J. Chassell" writes: > > > (whitespace-describe): Remove. Move the text to `Commentary:'. > > IMO, it doesn't really make sense to have a function which produces > the help for a given package, as there sufficient other ways to > provide that information (BTW printing.el is another package which > does this). > > In any case, when the source file has valuable inforation in the > commentary section, there should at least be a Commentary link on the > customization section for whitespace-global-mode; I believe one can be > added to the define-minor-mode as > :link '(emacs-commentary-link :tag "Commentary" "whitespace.el") > but I haven't tried it. > > > > Incidentally, while you could re-include your function definition of > > `whitespace-describe' in the CVS, it is surprising to see > > documentation like that. I would expect to see the full documentation > > in the documentation strings of: > > > > whitespace-buffer > > whitespace-region > > whitespace-cleanup > > > > as well as in the commentary and in the Texinfo documentation. > > Maybe we could find a way to make commentary links from doc strings > to the lisp file? E.g. with an extra button like "See also" ... > > > | whitespace-global-mode's value is nil > | > | Non-nil if Whitespace-Global mode is enabled. > | See the command `whitespace-global-mode' for a description of this minor-mo > de. > | Setting this variable directly does not take effect; > | use either M-x customize or the function `whitespace-global-mode'. > + > + See also _Commentary_ > | > | You can customize this variable. > | > | Defined in `whitespace'. > > > -- > Kim F. Storm http://www.cua.dk > > > > _______________________________________________ > Emacs-devel mailing list > Emacs-devel@gnu.org > http://mail.gnu.org/mailman/listinfo/emacs-devel >