bug#4510: 23.1; Separate help-argument-face from downcasing

bug#4510: 23.1; Separate help-argument-face from downcasing

[Drew Adams]

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)'
 

bug#4510: 23.1; Separate help-argument-face from downcasing

[Juanma Barranquero]

On Mon, Sep 21, 2009 at 23:35, Drew Adams <drew.adams@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

bug#4510: 23.1; Separate help-argument-face from downcasing

[Juanma Barranquero]

On Mon, Sep 21, 2009 at 23:35, Drew Adams <drew.adams@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@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@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)

bug#4510: 23.1; Separate help-argument-face from downcasing

[Drew Adams]

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

That works for me.

Thx - Drew 

bug#4510: 23.1; Separate help-argument-face from downcasing

[Juanma Barranquero]

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

> That works for me.

I'll commit it if nobody objects.

    Juanma

bug#4510: marked as done (23.1; Separate help-argument-face from downcasing)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 925 bytes --]

Your message dated Thu, 24 Sep 2009 21:25:22 +0200
with message-id <f7ccd24b0909241225x11ab6a76qc2e4bfe437bd046b@mail.gmail.com>
and subject line Re: bug#4510: 23.1; Separate help-argument-face from downcasing
has caused the Emacs bug report #4510,
regarding 23.1; Separate help-argument-face from downcasing
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
4510: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=4510
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 4740 bytes --]

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

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)'
 




[-- Attachment #3: Type: message/rfc822, Size: 2717 bytes --]

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

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

bug#4520: downcasing function arguments by default not appropriate in multi-tty

[Dan Nicolaescu]

*Help* buffers downcase function arguments depending on the font in use
 (if it supports italics?).
Changing a buffer's contents based on the font is use is not appropriate
since we have multi-tty, the same buffer can be shown simultaneously in
an X11 frame and a tty frame, and the properties of the font used in the
X11 frame can be very different from the ones used in a tty frame.

So changing the buffer content _by_default_ is not a good idea.
AFAIK we do not do such a thing anywhere else in emacs.

bug#4520: downcasing function arguments by default not appropriate in multi-tty

[Juanma Barranquero]

On Tue, Sep 22, 2009 at 17:27, Dan Nicolaescu <dann@ics.uci.edu> wrote:

> Changing a buffer's contents based on the font is use is not appropriate
> since we have multi-tty, the same buffer can be shown simultaneously in
> an X11 frame and a tty frame, and the properties of the font used in the
> X11 frame can be very different from the ones used in a tty frame.

Well, when the argument downcasing was implemented multi-tty wasn't in
Emacs, so it's no wonder we didn't think of that.

> So changing the buffer content _by_default_ is not a good idea.
> AFAIK we do not do such a thing anywhere else in emacs.

In the patch I'm planning to commit for #4510 I proposed

(defcustom help-downcase-arguments
  (and (face-differs-from-default-p 'help-argument-name) t)
  ...)

but it's just as easy to initialize it to nil. It's an interface
change, but not too serious; a note on NEWS will suffice, IMO. I'll
adjust my patch.

    Juanma

bug#4520: marked as done (downcasing function arguments by default not appropriate in multi-tty)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 945 bytes --]

Your message dated Thu, 24 Sep 2009 21:25:22 +0200
with message-id <f7ccd24b0909241225x11ab6a76qc2e4bfe437bd046b@mail.gmail.com>
and subject line Re: bug#4510: 23.1; Separate help-argument-face from downcasing
has caused the Emacs bug report #4520,
regarding downcasing function arguments by default not appropriate in multi-tty
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
4520: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=4520
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3024 bytes --]

From: Dan Nicolaescu <dann@ics.uci.edu>
To: bug-gnu-emacs <bug-gnu-emacs@gnu.org>
Subject: downcasing function arguments by default not appropriate in multi-tty
Date: Tue, 22 Sep 2009 08:27:15 -0700 (PDT)
Message-ID: <200909221527.n8MFRFQ7017415@godzilla.ics.uci.edu>


*Help* buffers downcase function arguments depending on the font in use
 (if it supports italics?).
Changing a buffer's contents based on the font is use is not appropriate
since we have multi-tty, the same buffer can be shown simultaneously in
an X11 frame and a tty frame, and the properties of the font used in the
X11 frame can be very different from the ones used in a tty frame.

So changing the buffer content _by_default_ is not a good idea.
AFAIK we do not do such a thing anywhere else in emacs.



[-- Attachment #3: Type: message/rfc822, Size: 2708 bytes --]

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

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