Faces customization group linked from mode groups

Faces customization group linked from mode groups

[Lennart Borgman]

There was recently a question on the gnu-emacs-help list from someone 
trying to customize the faces used in syntax highlighting C mode. He 
looked in C mode customization group but could not find it.

Maybe it would be a good idea to have a link to the faces customization 
from each mode customization group? (If that is possible in a simple way?)

Re: Faces customization group linked from mode groups

[Juri Linkov]

> There was recently a question on the gnu-emacs-help list from someone
> trying to customize the faces used in syntax highlighting C mode. He
> looked in C mode customization group but could not find it.
>
> Maybe it would be a good idea to have a link to the faces customization
> from each mode customization group? (If that is possible in a simple way?)

One solution is to add the parent group `font-lock-highlighting-faces'
to all groups of modes that support font-lock.  But this has one negative
effect: the `group' link is two-directional, so the customization group
`font-lock-highlighting-faces' will display too many children links
to all such groups.

A better solution is to implement a new one-directional link to another
customization group.  Currently `:link' supports four link types, and a
new link type could have the name `custom-group'.  It could create a
one-directional link in the customization buffer leading to the specified
group, e.g.:

(defgroup c nil
  "Support for the C language and related languages."
  :link '(custom-manual "(ccmode)")    ;; this is already existing link
  :link '(custom-group font-lock-highlighting-faces) ;; a new link type
  :group 'languages)

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

    There was recently a question on the gnu-emacs-help list from someone 
    trying to customize the faces used in syntax highlighting C mode. He 
    looked in C mode customization group but could not find it.

    Maybe it would be a good idea to have a link to the faces customization 
    from each mode customization group? (If that is possible in a simple way?)

We could give the font-lock-highlighting-faces group
many parent groups, including the C mode group.

That is basically trivial--the only hard part is finding
all the desired parent groups.  Would you like to do it?

Re: Faces customization group linked from mode groups

[Lennart Borgman]

Juri Linkov wrote:

>>There was recently a question on the gnu-emacs-help list from someone
>>trying to customize the faces used in syntax highlighting C mode. He
>>looked in C mode customization group but could not find it.
>>
>>Maybe it would be a good idea to have a link to the faces customization
>>from each mode customization group? (If that is possible in a simple way?)
>>    
>>
>
>One solution is to add the parent group `font-lock-highlighting-faces'
>to all groups of modes that support font-lock.  But this has one negative
>effect: the `group' link is two-directional, so the customization group
>`font-lock-highlighting-faces' will display too many children links
>to all such groups.
>  
>
Is not this the opposite way of the way Richard suggested? But the 
problem you mention should essentially be the same, or?

>A better solution is to implement a new one-directional link to another
>customization group.  Currently `:link' supports four link types, and a
>new link type could have the name `custom-group'.  It could create a
>one-directional link in the customization buffer leading to the specified
>group, e.g.:
>
>(defgroup c nil
>  "Support for the C language and related languages."
>  :link '(custom-manual "(ccmode)")    ;; this is already existing link
>  :link '(custom-group font-lock-highlighting-faces) ;; a new link type
>  :group 'languages)
>  
>
To me this seems like the way to go.

When it comes to updating these defgroup:s, is there an easy way to find 
all these modes?

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

    Is not this the opposite way of the way Richard suggested? But the 
    problem you mention should essentially be the same, or?

The possible problem is that a custom buffer for
font-lock-highlighting-faces would include lots of parent groups.
I agree it would be nicer to add a one-way link.

Re: Faces customization group linked from mode groups

[Juri Linkov]

>     Is not this the opposite way of the way Richard suggested? But the
>     problem you mention should essentially be the same, or?
>
> The possible problem is that a custom buffer for
> font-lock-highlighting-faces would include lots of parent groups.
> I agree it would be nicer to add a one-way link.

To my surprise the suitable link type is already implemented but not
documented.  The name of such one-way link type is `custom-group-link'.

After adding it for example to the `cpp' group like:

(defgroup cpp nil
  "Highlight or hide text according to cpp conditionals."
  :group 'c
  :link '(custom-group-link :tag "Font Lock Highlighting Faces group"
			    font-lock-highlighting-faces)
  :prefix "cpp-")

it displays in the customization buffer an additional line:

   See also [Font Lock Highlighting Faces group].

with the button that creates a new customization buffer with the
`font-lock-highlighting-faces' group.

The cost is adding this link is losing another link in the same buffer
which looks like:

   Parent documentation: [Manual].

It seems the logic of Customize assumes that if the group has a link
explicitly specified in `defgroup', then adding another default link
to the parent manual is not necessary.  I don't think this logic is valid
for `custom-group-link' link type.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Juri Linkov]

> To me this seems like the way to go.
>
> When it comes to updating these defgroup:s, is there an easy way to find
> all these modes?

I guess the easiest way is to grep for "font-lock-keywords" and
"font-lock-defaults".  This should find most files with font-lock
supported modes.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

    The cost is adding this link is losing another link in the same buffer
    which looks like:

       Parent documentation: [Manual].

I don't understand what such a link would mean.
What is "parent documentation"?  What is "Manual" the name of?

What in the source code produces such a link?

Re: Faces customization group linked from mode groups

[Juri Linkov]

>     The cost is adding this link is losing another link in the same buffer
>     which looks like:
>
>        Parent documentation: [Manual].
>
> I don't understand what such a link would mean.
> What is "parent documentation"?  What is "Manual" the name of?

It is a link in the parent group pointing to the Info manual.

For example, with group definitions:

(defgroup c nil
  :link '(custom-manual "(ccmode)"))

(defgroup cpp nil
  :group 'c)

the customization buffer of the `cpp' group has the link to the Info
manual "ccmode".  The customization buffer of the `c' group has the
same link too.

> What in the source code produces such a link?

The function `custom-add-parent-links' in cus-edit.el:

    (and (null (get name 'custom-links)) ;No links of its own.
         (= (length parents) 1)         ;A single parent.
         (let* ((links (get (car parents) 'custom-links))
                (many (> (length links) 2)))
           (when links
             (insert "\nParent documentation: ")
             (while links
               (push (widget-create-child-and-convert widget (car links))
               ...

adds a link to the manual from the parent, if the group has no own links.

There is nothing bad not having a parent documentation link, since the
user can go to the parent group, and find the same link in the parent
customization buffer.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

    There is nothing bad not having a parent documentation link, since the
    user can go to the parent group, and find the same link in the parent
    customization buffer.

I agree.  However, I don't see how this relates to the issue.
The question was how to make it easy to find all the faces
you could customize that affect Font Lock mode, right?
What is the solution you propose?

Re: Faces customization group linked from mode groups

[Juri Linkov]

> The question was how to make it easy to find all the faces
> you could customize that affect Font Lock mode, right?
> What is the solution you propose?

I propose to add

  :link '(custom-group-link :tag "Font Lock Faces group"
			    font-lock-highlighting-faces)

to `defgroup's of all modes that use font-lock faces defined in the
group `font-lock-highlighting-faces'.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

    I propose to add

      :link '(custom-group-link :tag "Font Lock Faces group"
				font-lock-highlighting-faces)

    to `defgroup's of all modes that use font-lock faces defined in the
    group `font-lock-highlighting-faces'.

Does anyone see any problem with this?

If no one reports a problem in a week, please do that.

Re: Faces customization group linked from mode groups

[Juri Linkov]

> To my surprise the suitable link type is already implemented but not
> documented.  The name of such one-way link type is `custom-group-link'.

There are more undocumented link types:

find . -type f -print0 | xargs -0 -e grep -inH -e "define-widget.*link"
./cus-edit.el:1655:(define-widget 'custom-manual 'info-link
./cus-edit.el:3470:(define-widget 'custom-group-link 'link
./wid-edit.el:1737:(define-widget 'link 'item
./wid-edit.el:1747:(define-widget 'info-link 'link
./wid-edit.el:1757:(define-widget 'url-link 'link
./wid-edit.el:1767:(define-widget 'function-link 'link
./wid-edit.el:1777:(define-widget 'variable-link 'link
./wid-edit.el:1787:(define-widget 'file-link 'link
./wid-edit.el:1797:(define-widget 'emacs-library-link 'link
./wid-edit.el:1807:(define-widget 'emacs-commentary-link 'link
./wid-edit.el:2800:(define-widget 'documentation-link 'link

>From all these link types only four are documented in the Emacs Lisp
manual in the node (info "(elisp)Common Keywords"): custom-manual,
info-link, url-link and emacs-commentary-link.  What about documenting
remaining six types: custom-group-link, function-link, variable-link,
file-link, emacs-library-link and documentation-link?  Maybe
Widget link types should be documented in the Widget manual, and
the Emacs Lisp manual should have a cross reference from
(info "(elisp)Common Keywords") to (info "(widget)Basic Types")?

Also the docstring of `defcustom' documents only three link types.
I'm not sure about duplicating full descriptions from the manual,
but at least the docstring could mention all available link types.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Juri Linkov]

>     I propose to add
>
>       :link '(custom-group-link :tag "Font Lock Faces group"
> 				font-lock-highlighting-faces)
>
>     to `defgroup's of all modes that use font-lock faces defined in the
>     group `font-lock-highlighting-faces'.
>
> Does anyone see any problem with this?
>
> If no one reports a problem in a week, please do that.

Please note that the group name is "Font Lock Highlighting Faces", but
I proposed the button [Font Lock Faces group], because a long button
text [Font Lock Highlighting Faces group] is too awkward.  Perhaps
the group `font-lock-highlighting-faces' should be renamed to
`font-lock-faces'.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

    >From all these link types only four are documented in the Emacs Lisp
    manual in the node (info "(elisp)Common Keywords"): custom-manual,
    info-link, url-link and emacs-commentary-link.  What about documenting
    remaining six types: custom-group-link, function-link, variable-link,
    file-link, emacs-library-link and documentation-link?

In principle it sounds good.  Please write a patch we could consider.

    Maybe
    Widget link types should be documented in the Widget manual, and

No, no, no!  That idea comes from trying to organize things in the
most logical structure--which is the wrong approach to structuring
documentation.  The main goal of the manual is _to be convenient_.

I put this info in the Emacs Lisp Manual because people need it for
writing ordinary Lisp programs well.  To put it somewhere else would
be a more logical structure, but it would be less convenient.

Logical structuring of the documentation sometimes increases
convenience, and sometimes gets in the way.  When it increases
convenience, it is good.  When it gets in the way, it is bad.

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

      Perhaps
    the group `font-lock-highlighting-faces' should be renamed to
    `font-lock-faces'.

I would agree with that.

Re: Faces customization group linked from mode groups

[Juri Linkov]

>     From all these link types only four are documented in the Emacs Lisp
>     manual in the node (info "(elisp)Common Keywords"): custom-manual,
>     info-link, url-link and emacs-commentary-link.  What about documenting
>     remaining six types: custom-group-link, function-link, variable-link,
>     file-link, emacs-library-link and documentation-link?
>
> In principle it sounds good.  Please write a patch we could consider.

Index: lispref/customize.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/customize.texi,v
retrieving revision 1.48
diff -c -r1.48 customize.texi
*** lispref/customize.texi	17 Oct 2005 06:46:14 -0000	1.48
--- lispref/customize.texi	17 Nov 2005 07:45:35 -0000
***************
*** 51,75 ****
  This is a sentence containing an active field which references some
  other documentation.
  
! There are four alternatives you can use for @var{link-data}:
  
  @table @code
  @item (custom-manual @var{info-node})
  Link to an Info node; @var{info-node} is a string which specifies the
  node name, as in @code{"(emacs)Top"}.  The link appears as
! @samp{[manual]} in the customization buffer.
  
  @item (info-link @var{info-node})
  Like @code{custom-manual} except that the link appears
  in the customization buffer with the Info node name.
  
  @item (url-link @var{url})
! Link to a web page; @var{url} is a string which specifies the @acronym{URL}.
! The link appears in the customization buffer as @var{url}.
  
  @item (emacs-commentary-link @var{library})
  Link to the commentary section of a library; @var{library} is a string
  which specifies the library name.
  @end table
  
  You can specify the text to use in the customization buffer by adding
--- 51,97 ----
  This is a sentence containing an active field which references some
  other documentation.
  
! There are several alternatives you can use for @var{link-data}:
  
  @table @code
  @item (custom-manual @var{info-node})
  Link to an Info node; @var{info-node} is a string which specifies the
  node name, as in @code{"(emacs)Top"}.  The link appears as
! @samp{[Manual]} in the customization buffer.  When this link is
! invoked, the built-in Info reader is started on @var{info-node}.
  
  @item (info-link @var{info-node})
  Like @code{custom-manual} except that the link appears
  in the customization buffer with the Info node name.
  
  @item (url-link @var{url})
! Link to a web page; @var{url} is a string which specifies the
! @acronym{URL}.  The link appears in the customization buffer as
! @var{url}.  When this link is invoked, the WWW browser specified by
! `browse-url-browser-function' will be called with @var{url}.
  
  @item (emacs-commentary-link @var{library})
  Link to the commentary section of a library; @var{library} is a string
  which specifies the library name.
+ 
+ @item (emacs-library-link @var{library})
+ Link to an Emacs Lisp library file; @var{library} is a string which
+ specifies the library name.
+ 
+ @item (file-link @var{file})
+ Link to a file; @var{file} is a string which specifies the file name.
+ 
+ @item (function-link @var{function})
+ Link to the documentation of a function; @var{function} is a string
+ which specifies the function name.
+ 
+ @item (variable-link @var{variable})
+ Link to the documentation of a variable; @var{variable} is a string
+ which specifies the variable name.
+ 
+ @item (custom-group-link @var{group})
+ Link to another customization group.  Invoking it creates a new
+ customization buffer for @var{group}.
  @end table
  
  You can specify the text to use in the customization buffer by adding

Index: lisp/custom.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/custom.el,v
retrieving revision 1.104
diff -c -r1.104 custom.el
*** lisp/custom.el	24 Oct 2005 16:17:11 -0000	1.104
--- lisp/custom.el	17 Nov 2005 07:45:35 -0000
***************
*** 210,221 ****
          item.  This is a sentence containing an active field which
          references some other documentation.
  
!         There are three 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
--- 210,220 ----
          item.  This is a sentence containing an active field which
          references some other documentation.
  
!         There are several 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\".
  
          (info-link INFO-NODE)
               Like `custom-manual' except that the link appears in the
***************
*** 223,229 ****
  
          (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.
  
          You can specify the text to use in the customization buffer by
          adding `:tag NAME' after the first element of the LINK-DATA; for
--- 222,245 ----
  
          (url-link URL)
               Link to a web page; URL is a string which specifies the URL.
! 
!         (emacs-commentary-link LIBRARY)
!              Link to the commentary section of LIBRARY.
! 
!         (emacs-library-link LIBRARY)
!              Link to an Emacs Lisp LIBRARY file.
! 
!         (file-link FILE)
!              Link to FILE.
! 
!         (function-link FUNCTION)
!              Link to the documentation of FUNCTION.
! 
!         (variable-link VARIABLE)
!              Link to the documentation of VARIABLE.
! 
!         (custom-group-link GROUP)
!              Link to another customization GROUP.
  
          You can specify the text to use in the customization buffer by
          adding `:tag NAME' after the first element of the LINK-DATA; for

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Faces customization group linked from mode groups

[Richard M. Stallman]

      node name, as in @code{"(emacs)Top"}.  The link appears as
    ! @samp{[Manual]} in the customization buffer.  When this link is
    ! invoked, the built-in Info reader is started on @var{info-node}.

Could you rewrite that in active voice?

    ! Link to a web page; @var{url} is a string which specifies the
    ! @acronym{URL}.  The link appears in the customization buffer as
    ! @var{url}.  When this link is invoked, the WWW browser specified by
    ! `browse-url-browser-function' will be called with @var{url}.

That too.

    + @item (emacs-library-link @var{library})
    + Link to an Emacs Lisp library file; @var{library} is a string which
    + specifies the library name.
    + 
    + @item (file-link @var{file})
    + Link to a file; @var{file} is a string which specifies the file name.

I am not sure what it means to "link to a file".
I think you need to explain what that means.

    + @item (function-link @var{function})
    + Link to the documentation of a function; @var{function} is a string
    + which specifies the function name.
    + 
    + @item (variable-link @var{variable})
    + Link to the documentation of a variable; @var{variable} is a string
    + which specifies the variable name.

Likewise here--what does it mean to "link to" these things?

    + 
    + @item (custom-group-link @var{group})
    + Link to another customization group.  Invoking it creates a new
    + customization buffer for @var{group}.

That's example of saying clearly what the link means.