Re: `whitespace-describe' function missing

[Rajesh Vaidheeswarran]

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" <address@hidden> 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 <address@hidden> http://www.cua.dk
> 
> 
> 
> _______________________________________________
> Emacs-devel mailing list
> address@hidden
> http://mail.gnu.org/mailman/listinfo/emacs-devel
>