Re: CVS update of gnus/lisp (ChangeLog message.el)

Re: CVS update of gnus/lisp (ChangeLog message.el)

[Jesper Harder]

"Reiner Steib" <reiner.steib@gmx.de> writes:

> Modified: ChangeLog message.el
>
> Added custom-manual links to all variables that have
> an index entry in the message manual.

I'm not sure that this is really a good idea.

It's probably nice when you use `customize-option', but it makes
`customize-group' awfully cluttered with a lot of identical and
redundant links.

Adding :link '(custom-manual ...) in defcustom (was: CVS update of gnus/lisp (ChangeLog message.el))

[Reiner Steib]

On Fri, Nov 28 2003, Jesper Harder wrote:

> "Reiner Steib" <reiner.steib@gmx.de> writes:
>
>> Modified: ChangeLog message.el
>>
>> Added custom-manual links to all variables that have
>> an index entry in the message manual.
>
> I'm not sure that this is really a good idea.
>
> It's probably nice when you use `customize-option', but it makes
> `customize-group' awfully cluttered with a lot of identical and
> redundant links.

`M-x customize-group RET gnus-article-treat RET' ;-)

I'm now aware of a policy when to add them and when not.  Any
pointers? [1] And I couldn't see any usage pattern.  I thought that
they were just missing, because the programmer forgot to add them in
the first place.

I don't have any problem with reverting my patch.  But I don't
understand the purpose of the ":link" entry then.

Bye, Reiner.

[1] (info "(elisp)Variable Definitions") doesn't mention :link at all.
    `C-h f defcustom RET' neither.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo--- PGP key available via WWW   http://rsteib.home.pages.de/

Re: Adding :link '(custom-manual ...) in defcustom

[Reiner Steib]

On Fri, Nov 28 2003, Reiner Steib wrote:

> I'm now aware of a policy when to add them and when not.  Any
      ^^^ not

> pointers? [1] And I couldn't see any usage pattern.  I thought that
> they were just missing, because the programmer forgot to add them in
> the first place.

,----[ <news:rjeljb2rmm.fsf@ssv2.dina.kvl.dk> ]
| From: Per Abrahamsen <abraham@dina.kvl.dk>
| Subject: Re: defgroup / customize-apropos
| Newsgroups: comp.emacs
| Date: Sun, 24 Feb 2002 09:47:29 +0100
| Message-ID: <rjeljb2rmm.fsf@ssv2.dina.kvl.dk>
| 
| "James Crowell" <pcsweb@worldnet.att.net> writes:
| 
| > I looked at the 'defcustom' documentation and did not see any ':tag'
| > description or any ':' parameter that I thought would help me.
| 
| It is documented in the Emacs Lisp Reference Manual, but unfortunately
| omitted from the doc string.  Fixed in Emacs 21.3.
| 
| Even worse, the :link tag was also omitted, and unlike :tag it is
| something everyone should use.
`----

s/21.3/CVS HEAD/

> [1] (info "(elisp)Variable Definitions") doesn't mention :link at all.
>     `C-h f defcustom RET' neither.

FWIW, I found something in (info "(elisp)Common Keywords") of CVS
HEAD.  But no "policy".

,----[ (info "(elisp)Common Keywords") ]
| `:link LINK-DATA'
|      Include an external link after the documentation string for this
|      item.  This is a sentence containing an active field which
|      references some other documentation.
| 
|      There are four alternatives you can use for LINK-DATA:
| 
|     `(custom-manual INFO-NODE)'
|           Link to an Info node; INFO-NODE is a string which specifies
|           the node name, as in `"(emacs)Top"'.  The link appears as
|           `[manual]' in the customization buffer.
| 
|     `(info-link INFO-NODE)'
|           Like `custom-manual' except that the link appears in the
|           customization buffer with the Info node name.
| 
|     `(url-link URL)'
|           Link to a web page; URL is a string which specifies the URL.
|           The link appears in the customization buffer as URL.
| 
|     `(emacs-commentary-link LIBRARY)'
|           Link to the commentary section of a library; LIBRARY is a
|           string which specifies the library name.
| 
|      You can specify the text to use in the customization buffer by
|      adding `:tag NAME' after the first element of the LINK-DATA; for
|      example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
|      Emacs manual which appears in the buffer as `foo'.
| 
|      An item can have more than one external link; however, most items
|      have none at all.
`----

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo--- PGP key available via WWW   http://rsteib.home.pages.de/

Re: Adding :link '(custom-manual ...) in defcustom

[Jesper Harder]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:

> On Fri, Nov 28 2003, Jesper Harder wrote:
>
>> I'm not sure that this is really a good idea.
>>
>> It's probably nice when you use `customize-option', but it makes
>> `customize-group' awfully cluttered with a lot of identical and
>> redundant links.
>
> `M-x customize-group RET gnus-article-treat RET' ;-)

Exactly!

> I'm now aware of a policy when to add them and when not.  Any
> pointers? [1] And I couldn't see any usage pattern.

The following isn't quite how Custom currently works, but it might be
a solution:

  You can currently add a link in `defgroup'.  If the link in
  `defcustom' would be same as in the group it can be omitted -- it
  ought to be enough to list the same link just once per group.

  If `customize-option' was changed to grab links from the parent
  group of the option, then we wouldn't need to add links to
  individual options (unless the link is different from the group's).

Re: Adding :link '(custom-manual ...) in defcustom

[Per Abrahamsen]

Jesper Harder <harder@ifa.au.dk> writes:

>   You can currently add a link in `defgroup'.  If the link in
>   `defcustom' would be same as in the group it can be omitted -- it
>   ought to be enough to list the same link just once per group.
>
>   If `customize-option' was changed to grab links from the parent
>   group of the option, then we wouldn't need to add links to
>   individual options (unless the link is different from the group's).


Here is a patch that does that.  I'll submit it to emacs-devel.

2003-11-30  Per Abrahamsen  <abraham@dina.kvl.dk>

	* cus-edit.el (custom-add-parent-links): Add documentation links
	for parent, if the item has none of its own.

Index: lisp/cus-edit.el
===================================================================
RCS file: /cvsroot/emacs//emacs/lisp/cus-edit.el,v
retrieving revision 1.187
diff -c -r1.187 cus-edit.el
*** lisp/cus-edit.el	1 Sep 2003 15:45:09 -0000	1.187
--- lisp/cus-edit.el	30 Nov 2003 14:03:56 -0000
***************
*** 1956,1962 ****
  	(type (widget-type widget))
  	(buttons (widget-get widget :buttons))
  	(start (point))
! 	found)
      (insert (or initial-string "Parent groups:"))
      (mapatoms (lambda (symbol)
  		(let ((entry (assq name (get symbol 'custom-group))))
--- 1956,1962 ----
  	(type (widget-type widget))
  	(buttons (widget-get widget :buttons))
  	(start (point))
! 	(parents nil))
      (insert (or initial-string "Parent groups:"))
      (mapatoms (lambda (symbol)
  		(let ((entry (assq name (get symbol 'custom-group))))
***************
*** 1967,1978 ****
  			   :tag (custom-unlispify-tag-name symbol)
  			   symbol)
  			  buttons)
! 		    (setq found t)))))
!     (widget-put widget :buttons buttons)
!     (if found
! 	(insert "\n")
        (delete-region start (point)))
!     found))
  
  ;;; The `custom-comment' Widget.
  
--- 1967,1995 ----
  			   :tag (custom-unlispify-tag-name symbol)
  			   symbol)
  			  buttons)
! 		    (setq parents (cons symbol parents))))))
!     (and (null (get symbol 'custom-links)) ;No links of its own.
!          (= (length parents) 1)         ;A single parent.
!          (let ((links (get (car parents) 'custom-links)))
!            (when links
!              (insert "\nParent documentation: ")
!              (while links
!                (push (widget-create-child-and-convert widget (car links))
!                      buttons)
!                (setq links (cdr links))
!                (cond ((null links)
!                       (insert ".\n"))
!                      ((null (cdr links))
!                       (if many
!                           (insert ", and ")
!                         (insert " and ")))
!                      (t
!                       (insert ", ")))))))
!     (if parents
!         (insert "\n")
        (delete-region start (point)))
!     (widget-put widget :buttons buttons)
!     parents))
  
  ;;; The `custom-comment' Widget.