Re: new *Help* argument highlighting

[Juanma Barranquero <lektu@mi.madritel.es>]

On 09 May 2004 20:25:13 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> I think you're wrong.  There's a lot of problems with adding colors.

Sure. But we already have lots of faces, some of which add colors with
not much remorse:

(defface comint-highlight-prompt
  '((((background dark)) (:foreground "cyan"))
    (t (:foreground "dark blue")))
  "Face to use to highlight prompts."
  :group 'comint)

(defface hi-yellow
  '((((background dark)) (:background "yellow" :foreground "black"))
    (t (:background "yellow")))
  "Default face for hi-lock mode."
  :group 'hi-lock-faces)

(defface smerge-mine-face
  '((((background light))
     (:foreground "blue"))
    (((background dark))
     (:foreground "cyan")))
  "Face for your code."
  :group 'smerge)

(defface speedbar-button-face '((((class color) (background light))
                                 (:foreground "green4"))
                                (((class color) (background dark))
                                 (:foreground "green3")))
  "Face used for +/- buttons."
  :group 'speedbar-faces)

That said, I wouldn't advocate adding colors to this as a default.


> But playing with font size is pretty safe (at least, I can't remember
> a single complaint from the font-size change in Info-mode, for example).

As I said, it's OK to me if that's what's decided.

> As said, it's not the fact of highlighting that surprises, it's just the
> fact that args and only args are highlighted as if they were so
> very special.

Aren't? In an elisp function's help, I honestly don't know what else
could be special... Perhaps if we had a more structured style guide for
function docstrings, with sections à la:


 MYFUNCTION is a function in .emacs.el.              # where/bindings
 It is bound to H-z.

 (myfunction A B &optional C)                        # function header

 MYFUNCTION is an obsolete function                  # obsolescence info
 since the beginning of time; do not use it.

 The object of MYFUNCTION is serving as an example.  # function description
 You can use it at your leisure.

 Argument A is for whatever you want.                # argument usage
 B, on the other hand, is unused.
 Optional C defaults to nil, and should stay so.

 Example:                                            # example

   (myfunction 7 "I'm being ignored")

 Notes:                                              # additional notes

   You really shouldn't use this function.
   It hasn't been tested on the wild so
   it could misfire.

then I'd understand why highlighting just arguments would be weird.

> Note that I try to consistently say "surprise" rather than
> "bother".  I'm not opposed to it, but I think it currently looks odd.

Yeah, I understand. Let's see whether we can agree on something
generally useful and non-surprising/non-bothering. 

Thanks,

                                                           /L/e/k/t/u