function arguments downcased in help buffers

function arguments downcased in help buffers

[Dan Nicolaescu]

emacs -Q 
C-h f defun RET

which CVS HEAD shows this:


defun is a special form in `C source code'.

(defun name arglist [docstring] body...)

Define name as a function.
The definition is (lambda arglist [docstring] body...).
See also the function `interactive'.

In 22.2 and older version from CVS HEAD used to show this:

defun is a special form in `C source code'.

(defun NAME ARGLIST [DOCSTRING] BODY...)

Define NAME as a function.
The definition is (lambda ARGLIST [DOCSTRING] BODY...).
See also the function `interactive'.


not sure why this happens, but it does not seem like a good idea, the
upper case used for arguments is quite helpful when trying to spot what
a certain argument does.

Re: function arguments downcased in help buffers

[Juanma Barranquero]

On Tue, Apr 15, 2008 at 2:20 AM, Dan Nicolaescu <dann@ics.uci.edu> wrote:

>  In 22.2 and older version from CVS HEAD used to show this:
>
>  defun is a special form in `C source code'.
>
>  (defun NAME ARGLIST [DOCSTRING] BODY...)

That's a feature, but it is not new, it was introduced in 22.1. Also,
in the default emacs -q setup, the arguments are lowercase *italics*.

>  not sure why this happens, but it does not seem like a good idea, the
>  upper case used for arguments is quite helpful when trying to spot what
>  a certain argument does.

You can customize the help-argument-name face. Or, if you really want
your uppercase args back, you can do

(defun help-default-arg-highlight (arg) arg)

FWIW, for cases like these I think there should be a
help-argument-highlight-function var, set to
help-default-arg-highlight, so the user could just assign another
function to it instead of having to redefine the existing one. But
Richard opposed adding such a variable:

> To say that a user can customize something does not necessarily mean
> introducing a defcustom to customize it.  That is one of many
> customization mechanisms in Emacs.  Another customization mechanism
> is to redefine a function.

 Juanma

Re: function arguments downcased in help buffers

[Glenn Morris]

"Juanma Barranquero" wrote:

> That's a feature, but it is not new, it was introduced in 22.1. Also,
> in the default emacs -q setup, the arguments are lowercase *italics*.

For me in the current CVS trunk with emacs -Q, they arguments are in
the default face. This is another problem of the font-backend, because
with --disable-font-backend the arguments are uppercase once more. I
guess the font-backend gets the `face-differs-from-default-p'
calculation wrong in help-default-arg-highlight.

Re: function arguments downcased in help buffers

[Juanma Barranquero]

On Tue, Apr 15, 2008 at 4:04 AM, Glenn Morris <rgm@gnu.org> wrote:

>  For me in the current CVS trunk with emacs -Q, they arguments are in
>  the default face.

I don't see that on Windows, with or without the new font backend.
After emacs -Q the args are in help-argument-name face, which is
italized.

> This is another problem of the font-backend, because
>  with --disable-font-backend the arguments are uppercase once more. I
>  guess the font-backend gets the `face-differs-from-default-p'
>  calculation wrong in help-default-arg-highlight.

That could be a bug in `face-differs-from-default-p', yes.

 Juanma

Re: function arguments downcased in help buffers

[Dan Nicolaescu]

Glenn Morris <rgm@gnu.org> writes:

  > "Juanma Barranquero" wrote:
  > 
  > > That's a feature, but it is not new, it was introduced in 22.1. Also,
  > > in the default emacs -q setup, the arguments are lowercase *italics*.
  > 
  > For me in the current CVS trunk with emacs -Q, they arguments are in
  > the default face. 

As they are in 22.[12], but in that version they are upper case.

That is probably why nobody noticed this before... 

Am I the only one thinking that downcasing the arguments is a misfeature?

  > This is another problem of the font-backend, because
  > with --disable-font-backend the arguments are uppercase once more. I
  > guess the font-backend gets the `face-differs-from-default-p'
  > calculation wrong in help-default-arg-highlight.

Re: function arguments downcased in help buffers

[Juanma Barranquero]

On Tue, Apr 15, 2008 at 7:03 AM, Dan Nicolaescu <dann@ics.uci.edu> wrote:

>   > For me in the current CVS trunk with emacs -Q, they arguments are in
>   > the default face.
>
>  As they are in 22.[12], but in that version they are upper case.

They are not (in the default face, or shown uppercase). They are in
the help-argument-name face. That change is in since around may 2004.

>  That is probably why nobody noticed this before...

You're talking as if this was a bug, instead of a feature that was
(long) discussed and consensuated. Please take a look at the mailing
list archive.

>  Am I the only one thinking that downcasing the arguments is a misfeature?

You're the only one to report a problem with it since mid-2004.

 Juanma

RE: function arguments downcased in help buffers

[Drew Adams]

> You're talking as if this was a bug, instead of a feature that was
> (long) discussed and consensuated. Please take a look at the mailing
> list archive.
> 
> > Am I the only one thinking that downcasing the arguments 
> > is a misfeature?
> 
> You're the only one to report a problem with it since mid-2004.

Rereading the 2004 archive thread "new *Help* argument highlighting" wasn't too
reassuring. It didn't seem that there was such a complete consensus as you
suggest, with some people, e.g. Stefan, saying that this was a giant waste of
time for little, if any, gain:

 "The current convention is simple and safe, and as far as I can tell it's
  quite sufficient as well.  The changes discussed here seem to be about
  a new convention which is not simple, and more importantly not safe."

Your answer to Stefan's opinion was that then was not the time to question this
feature, presumably since it was late in the 22 release cycle (!), and that it
could always be revisited later:

 "But certainly now is not the time to discuss it.  If we decide that more
  information (structure, highlighting, or whatever) is necessary or
  helpful in docstrings, we can design the new features on the 22.X
  timeframe."

FWIW, I don't mind the feature. I do think it's good to have a face for this, so
that users can customize the behavior. But I think the default of italic doesn't
stand out enough, at least in emacs -Q on Windows. IMO, bold italic is better,
and italic uppercase (bold or non-bold) is even better.

BTW, using Customize to change the face, and then setting it for the current
session, changes the text in an existing *Help* buffer immediately (good),
_except_ when you change to the default face by removing all checkmarks in
Customize. In that case, you need to use the help command again (e.g. C-h f) in
order to get the uppercase. No big deal, but a slight inconsistency.

Re: function arguments downcased in help buffers

[Dan Nicolaescu]

"Juanma Barranquero" <lekktu@gmail.com> writes:

  > On Tue, Apr 15, 2008 at 7:03 AM, Dan Nicolaescu <dann@ics.uci.edu> wrote:
  > 
  > >   > For me in the current CVS trunk with emacs -Q, they arguments are in
  > >   > the default face.
  > >
  > >  As they are in 22.[12], but in that version they are upper case.
  > 
  > They are not (in the default face, or shown uppercase). They are in

Maybe they are lower case in your setup (Windows?), they very much are
in mine.

emacs-22.2 -Q -fn lucidasanstypewriter-12 

clearly shows that arguments in upper case.


  > the help-argument-name face. That change is in since around may 2004.

And help-argument-name is not distinguishable from the default case in
that setup:

Face: help-argument-name (sample) (customize this face)
Documentation: Face to highlight argument names in *Help* buffers.
Defined in `help-fns.el'.

         Family: unspecified
          Width: unspecified
         Height: unspecified
         Weight: unspecified
          Slant: unspecified
     Foreground: unspecified
     Background: unspecified
      Underline: unspecified
       Overline: unspecified
 Strike-through: unspecified
            Box: unspecified
        Inverse: unspecified
        Stipple: unspecified
Font or fontset: unspecified
        Inherit: unspecified

lucidasanstypewriter used to be (maybe still is) the
one of the more popular fixed width fonts.  
So this change had absolutely no effect on everyone using that font
(and maybe other fonts too).

Probably with the changes in the font backend something in that code
changed, and not the help-argument-name appears the same, but the
arguments are downcased now, that is what made this old change apparent
now.

The face is not a problem, but it is just odd to downcase the text.
I do consider this a bug, but if everyone likes that as a default, then
so be it.

Re: function arguments downcased in help buffers

[Juanma Barranquero]

On Tue, Apr 15, 2008 at 4:16 PM, Drew Adams <drew.adams@oracle.com> wrote:

>  Rereading the 2004 archive thread "new *Help* argument highlighting" wasn't too
>  reassuring. It didn't seem that there was such a complete consensus as you
>  suggest

I didn't say "complete consensus". That does not exist in emacs-devel.
But if you've read the thread, most of the initial complains were (as
usual) about the choice of face and whether it was too intrusive, or
too little ;-) Once someone (not me, I think it was Richard) suggested
italics and lowercase (to follow the printed docs) there was pretty
much no more complains until now.

In fact, there was considerable discussion (and some agreement, I'd
say) about ways to *add* more markup to the docstrings, like using
@v{VAR} to unequivocally distinguish variable referencies.

>  Your answer to Stefan's opinion was that then was not the time to question this
>  feature, presumably since it was late in the 22 release cycle (!), and that it
>  could always be revisited later:

That's a nice selective reading. Stefan is saying that the simple
feature I implemented is working, and that he thinks we're wasting
time discussing *additional* features, like @var{VAR}. And in my
answer, as your quote shows, I agreed with him about that.

>  FWIW, I don't mind the feature. I do think it's good to have a face for this, so
>  that users can customize the behavior. But I think the default of italic doesn't
>  stand out enough, at least in emacs -Q on Windows. IMO, bold italic is better,
>  and italic uppercase (bold or non-bold) is even better.

I don't mind the default, just the feature. But the current default
was not chosen by accident. Some people didn't like uppercase italics
(I think they're horrible, FWIW), some people liked to get rid of
uppercase altogether, etc. I think you're reopening one of *those*
discussions, but don't let me stop you from doing it :)

>  BTW, using Customize to change the face, and then setting it for the current
>  session, changes the text in an existing *Help* buffer immediately (good),
>  _except_ when you change to the default face by removing all checkmarks in
>  Customize. In that case, you need to use the help command again (e.g. C-h f) in
>  order to get the uppercase. No big deal, but a slight inconsistency.

I try to stay as far away from customize as possible, so, no idea.

 Juanma

Re: function arguments downcased in help buffers

[Juanma Barranquero]

On Tue, Apr 15, 2008 at 4:25 PM, Dan Nicolaescu <dann@ics.uci.edu> wrote:

>  Maybe they are lower case in your setup (Windows?), they very much are
>  in mine.

My point was/is that is defined that way. Whether it is not working
for some font backend / font combination is another issue altogether
(a bug, to be precise).

>  And help-argument-name is not distinguishable from the default case in
>  that setup:

If the italicised font cannot be distinguished from the normal one,
reverting to uppercase it's the safe thing.

>  lucidasanstypewriter used to be (maybe still is) the
>  one of the more popular fixed width fonts.

There are lots of fixed width fonts. DejaVu Sans Mono, for example, is
increasingly popular (and it works OK with this feature).

>  Probably with the changes in the font backend something in that code
>  changed, and not the help-argument-name appears the same, but the
>  arguments are downcased now, that is what made this old change apparent
>  now.

If you have a font which looks the same in italicised and
non-italicised forms, but it is different according to
`face-differs-from-default-p', that's not a bug in help argument
highlighting; it could creep up in other places.

>  The face is not a problem, but it is just odd to downcase the text.
>  I do consider this a bug, but if everyone likes that as a default, then
>  so be it.

It is already clear that it is a feature you don't like, but I find it
a bit insulting that you keep referring to it as a "bug".

 Juanma

RE: function arguments downcased in help buffers

[Drew Adams]

> That's a nice selective reading. Stefan is saying that the simple
> feature I implemented is working, and that he thinks we're wasting
> time discussing *additional* features, like @var{VAR}. And in my
> answer, as your quote shows, I agreed with him about that.

Sorry, I guess I misunderstood his post. I thought he was saying
that the existing uppercase convention was OK.

Re: function arguments downcased in help buffers

[Dan Nicolaescu]

"Juanma Barranquero" <lekktu@gmail.com> writes:

  > On Tue, Apr 15, 2008 at 4:25 PM, Dan Nicolaescu <dann@ics.uci.edu> wrote:
  > 
  > >  Maybe they are lower case in your setup (Windows?), they very much are
  > >  in mine.
  > 
  > My point was/is that is defined that way. 

That might have been your intention, but that is not what you actually
said, and what I was replying to.

  > Whether it is not working for some font backend / font combination
  > is another issue altogether (a bug, to be precise).


  > >  lucidasanstypewriter used to be (maybe still is) the
  > >  one of the more popular fixed width fonts.
  > 
  > There are lots of fixed width fonts. DejaVu Sans Mono, for example, is
  > increasingly popular (and it works OK with this feature).

This is unrelated to what I wrote and the context I wrote it in.  DejaVu
Sans Mono is also not useful to X11 emacs for emacs 22, AFAICT it is not
available as a core X font.

  > >  The face is not a problem, but it is just odd to downcase the text.
  > >  I do consider this a bug, but if everyone likes that as a default, then
  > >  so be it.
  > 
  > It is already clear that it is a feature you don't like, but I find it
  > a bit insulting that you keep referring to it as a "bug".

This type of attitude is one of the reasons emacs-devel is such an
unpleasant environment lately.  
The discussion was about a feature that recently changed behavior, and
the statement you replied to was clearly labeled as _a personal opinion_
and clearly stated that it didn't require a change if that is what most
people want.  Stating that criticism of a feature is an insult is a
clear way to drive people way from any type of discussion.

Re: function arguments downcased in help buffers

[Jason Rumney]

Dan Nicolaescu wrote:
> The face is not a problem, but it is just odd to downcase the text.
> I do consider this a bug, but if everyone likes that as a default, then
> so be it.
>   

I think the bug is in the new font backend. Something is not detecting 
that italic and default are using the same fonts.

Re: function arguments downcased in help buffers

[Juanma Barranquero]

On Tue, Apr 15, 2008 at 5:37 PM, Dan Nicolaescu <dann@ics.uci.edu> wrote:

>  That might have been your intention, but that is not what you actually
>  said, and what I was replying to.

We can discuss forever the meaning of "they are", but I stand for what
I actually said.

>  This is unrelated to what I wrote and the context I wrote it in.  DejaVu
>  Sans Mono is also not useful to X11 emacs for emacs 22,

Why not?

> AFAICT it is not available as a core X font.

That is unrelated to what you wrote, unless your definition of popular
is "available as a core X font".

>  This type of attitude is one of the reasons emacs-devel is such an
>  unpleasant environment lately.

I'd say that the attitude of using "brain-dead", "bug", "stupid" etc
to people's decissions (and, yes, sometimes mistakes) is one reason
why emacs-devel is often unpleasant. That, and the habit of pushing to
change back defaults people don't like, instead of just customizing
them in their .emacs and be done with it.

>  The discussion was about a feature that recently changed behavior

That's one way to see it. Another is to think that the feature has not
changed behavior, but a recent bug is triggering an unindented
misbehavior.

>  and
>  the statement you replied to was clearly labeled as _a personal opinion_
>  and clearly stated that it didn't require a change if that is what most
>  people want.

I fail to see why your statement is "clearly [...] _a personal
opinion_", and my comment, which explicitly said "but I find it
a bit insulting [...]", is not.

>   Stating that criticism of a feature is an insult is a
>  clear way to drive people way from any type of discussion.

Nice strawman, but I wasn't objecting to your disliking of the
feature, or your criticism, just to the election of the word "bug" to
denote an intended feature.

 Juanma

Re: function arguments downcased in help buffers

[Stefan Monnier]

Please can we stop bickering?


        Stefan

Re: function arguments downcased in help buffers

[Dan Nicolaescu]

"Juanma Barranquero" <lekktu@gmail.com> writes:

  > On Tue, Apr 15, 2008 at 5:37 PM, Dan Nicolaescu <dann@ics.uci.edu> wrote:
  > 
  > >  This is unrelated to what I wrote and the context I wrote it in.  DejaVu
  > >  Sans Mono is also not useful to X11 emacs for emacs 22,
  > 
  > Why not?

Because of ...

  > > AFAICT it is not available as a core X font.

... this.  Only core X11 fonts (or) are supported in X11 emacs before
the unicode-2 merge.

Re: function arguments downcased in help buffers

[Kenichi Handa]

In article <4804D10B.8020902@gnu.org>, Jason Rumney <jasonr@gnu.org> writes:

> Dan Nicolaescu wrote:
> > The face is not a problem, but it is just odd to downcase the text.
> > I do consider this a bug, but if everyone likes that as a default, then
> > so be it.
> >   

> I think the bug is in the new font backend. Something is not detecting 
> that italic and default are using the same fonts.

Right.  I've just fixed it in my working version.  I'm going
to make a new branch for that version in a few days.

---
Kenichi Handa
handa@ni.aist.go.jp

Re: function arguments downcased in help buffers

[Dan Nicolaescu]

Glenn Morris <rgm@gnu.org> writes:

  > "Juanma Barranquero" wrote:
  > 
  > > That's a feature, but it is not new, it was introduced in 22.1. Also,
  > > in the default emacs -q setup, the arguments are lowercase *italics*.
  > 
  > For me in the current CVS trunk with emacs -Q, they arguments are in
  > the default face. This is another problem of the font-backend, because
  > with --disable-font-backend the arguments are uppercase once more. I
  > guess the font-backend gets the `face-differs-from-default-p'
  > calculation wrong in help-default-arg-highlight.

Doing what help-default-arg-highlight does has problems with multi-tty.
help-default-arg-highlight can decide to downcase when the help buffer
is created in an X11 frame.  But when looking at the same buffer in a tty
frame the faces are most likely the same, but the content is already
created...