GNU bug report logs - #4510
23.1; Separate help-argument-face from downcasing

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 4510 in the body.
You can then email your comments to 4510 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 23.1; Separate help-argument-face from downcasing
Date: Mon, 21 Sep 2009 14:35:00 -0700

Emacs 22 introduced face `help-argument-name' and function
`help-default-arg-highlight'.  The Emacs 22 NEWS says this:
 
  To change the default, customize face `help-argument-name' or
  redefine the function `help-default-arg-highlight'.
 
The problem is that function `help-default-arg-highlight' couples
(a) the use of a face to highlight the arguments with (b) downcasing
the arguments.  These two should be separated, so users can highlight
without downcasing (or downcase without highlighting).
 
I, for instance, find lowercase italics (the default, starting with
Emacs 22) to be much less readable than uppercase non-italics (the
default before Emacs 22).  But I would really prefer uppercase
italics.  There is no way to get this, short of redefining the
function `help-default-arg-highlight'.
 
That should not be the only alternative for users.  Users should not
be expected to redefine basic functions in order to customize such
appearances.  And in any case, it makes no sense for the face and
the letter case to be hard-code-coupled.

This is the definition of `help-default-arg-highlight':

(defun help-default-arg-highlight (arg)
  "Default function to highlight arguments in *Help* buffers.
It returns ARG in face `help-argument-name'; ARG is also
downcased if it displays differently than the default
face (according to `face-differs-from-default-p')."
  (propertize (if (face-differs-from-default-p 'help-argument-name)
                  (downcase arg)
                arg)
              'face 'help-argument-name))
 
If face `help-argument-name' is different from the default face,
then the args are downcased. The logic should simply be to apply
the face systematically: if it is the same as the default, then
the face would have no effect. And then provide a separate option
to control upcasing/downcasing.

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

Message #10 received at 4510 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 4510 <at> debbugs.gnu.org
Subject: Re: bug#4510: 23.1; Separate help-argument-face from downcasing
Date: Tue, 22 Sep 2009 00:17:12 +0200

On Mon, Sep 21, 2009 at 23:35, Drew Adams <drew.adams <at> oracle.com> wrote:

> That should not be the only alternative for users.  Users should not
> be expected to redefine basic functions in order to customize such
> appearances.  And in any case, it makes no sense for the face and
> the letter case to be hard-code-coupled.

I agree.

When help argument highlighting was introduced, there was some
resistance to adding more configuration options (surely because we
were in the long road to Emacs 22 and everybody was tired and wanting
to speed things up), and the argument was put forward (by Richard,
IIRC) that variables were just one option for the user to customize
his Emacs environment, redefining functions being another.

I was unconvinced then and I'm still unconvinced now. Redefining a
standard Emacs function (or advising around it) in your .emacs is not
a good idea; any change in the source of the original function will
catch you off guard.

    Juanma

Message #15 received at 4510 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 4510 <at> debbugs.gnu.org
Subject: Re: bug#4510: 23.1; Separate help-argument-face from downcasing
Date: Tue, 22 Sep 2009 01:21:15 +0200

On Mon, Sep 21, 2009 at 23:35, Drew Adams <drew.adams <at> oracle.com> wrote:

> The problem is that function `help-default-arg-highlight' couples
> (a) the use of a face to highlight the arguments with (b) downcasing
> the arguments.  These two should be separated, so users can highlight
> without downcasing (or downcase without highlighting).

This is the proposed patch; it also renames
`help-default-arg-highlight', which has an unfitting name.

  Juanma



2009-09-21  Juanma Barranquero  <lekktu <at> gmail.com>

	* help-fns.el (help-downcase-arguments): New option.
	(help-default-arg-highlight): Obsolete.
	(help-highlight-arg): New function.
	(help-do-arg-highlight): Use it.
	Suggested by Drew Adams <drew.adams <at> oracle.com>.  (Bug#4510)


diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 2425310..fc80966 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -158,15 +158,22 @@ KIND should be `var' for a variable or `subr'
for a subroutine."
 	    (concat "src/" file)
 	  file)))))

-(defun help-default-arg-highlight (arg)
-  "Default function to highlight arguments in *Help* buffers.
-It returns ARG in face `help-argument-name'; ARG is also
-downcased if it displays differently than the default
-face (according to `face-differs-from-default-p')."
-  (propertize (if (face-differs-from-default-p 'help-argument-name)
-                  (downcase arg)
-                arg)
-              'face 'help-argument-name))
+(defcustom help-downcase-arguments
+  (and (face-differs-from-default-p 'help-argument-name) t)
+  "If non-nil, argument names in *Help* buffers are downcased."
+  :type 'boolean
+  :group 'help
+  :version "23.2")
+
+(defun help-highlight-arg (arg)
+  "Highlight ARG as an argument name for a *Help* buffer.
+Return ARG in face `help-argument-name'; ARG is also downcased
+if the variable `help-downcase-arguments' is non-nil."
+  (propertize (if help-downcase-arguments (downcase arg) arg)
+	      'face 'help-argument-name))
+
+(define-obsolete-function-alias 'help-default-arg-highlight
+    'help-highlight-arg "23.2")

 (defun help-do-arg-highlight (doc args)
   (with-syntax-table (make-syntax-table emacs-lisp-mode-syntax-table)
@@ -184,7 +191,7 @@ face (according to `face-differs-from-default-p')."
                          "\\(?:-[a-z0-9-]+\\)?"  ; for ARG-xxx, ARG-n
                          "\\(?:-[{([<`\"].*?\\)?"; for ARG-{x}, (x),
<x>, [x], `x'
                          "\\>")                  ; end of word
-                 (help-default-arg-highlight arg)
+                 (help-highlight-arg arg)
                  doc t t 1)))))

 (defun help-highlight-arguments (usage doc &rest args)

Message #20 received at 4510 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juanma Barranquero'" <lekktu <at> gmail.com>
Cc: <4510 <at> debbugs.gnu.org>
Subject: RE: bug#4510: 23.1; Separate help-argument-face from downcasing
Date: Tue, 22 Sep 2009 07:35:57 -0700

> This is the proposed patch; it also renames
> `help-default-arg-highlight', which has an unfitting name.

That works for me.

Thx - Drew 

Message #25 received at 4510 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 4510 <at> debbugs.gnu.org
Subject: Re: bug#4510: 23.1; Separate help-argument-face from downcasing
Date: Tue, 22 Sep 2009 16:41:25 +0200

On Tue, Sep 22, 2009 at 16:35, Drew Adams <drew.adams <at> oracle.com> wrote:

> That works for me.

I'll commit it if nobody objects.

    Juanma

Message #30 received at 4510-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, Dan Nicolaescu <dann <at> ics.uci.edu>
Cc: 4510-done <at> debbugs.gnu.org, 4520-done <at> debbugs.gnu.org
Subject: Re: bug#4510: 23.1; Separate help-argument-face from downcasing
Date: Thu, 24 Sep 2009 21:25:22 +0200

I've installed the patch, defaulting `help-downcase-arguments' to nil
as per Dan's request in bug#4520.

If someone objects to the change in the default appearance of argument
names we'll know soon enough...

    Juanma

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.