uppercase var names in docstrings

uppercase var names in docstrings

[Stefan]

A few months ago, the help code was changed so that C-h f now looks for the
uppercase variable names and makes them lowercase&italics (if the terminal
supports it).

I waited to see how I'd like it and I must say that I'm actually annoyed by
the lowercasing: it makes it much harder for me to find the spot in
a docstring where the use of a particular argument is described.

Basically the problem is that varnames don't stand out as much as before,
since the only thing that distinguishes them from normal text is
the italics.

Of course I can change my own setting easily, but if I'm not the only
oddball who feels this way, maybe it'd better to change the default so that
such varnames are only made italics but not lowercase.


        Stefan

RE: uppercase var names in docstrings

[Drew Adams]

FWIW, my impression is the same as Stefan's.

I think it might be good to try bold italic (and lowercase); I believe that
would stand out sufficiently. If bold italic is not supported by a given
face, then bold would be a good second choice, plain uppercase being a third
choice. - Drew


-----Original Message-----From: Stefan
A few months ago, the help code was changed so that C-h f now looks for the
uppercase variable names and makes them lowercase&italics (if the terminal
supports it).

I waited to see how I'd like it and I must say that I'm actually annoyed by
the lowercasing: it makes it much harder for me to find the spot in
a docstring where the use of a particular argument is described.

Basically the problem is that varnames don't stand out as much as before,
since the only thing that distinguishes them from normal text is
the italics.

Of course I can change my own setting easily, but if I'm not the only
oddball who feels this way, maybe it'd better to change the default so that
such varnames are only made italics but not lowercase.

Re: uppercase var names in docstrings

[Lennart Borgman]

I am not very fond of italics on screen. They tend to appear rugged, at
least on my screens. Uppercase have been a good alternative for me, but
maybe bold italics is less rugged than just italics?

- Lennart

----- Original Message ----- 
From: "Drew Adams" <drew.adams@oracle.com>
To: "Stefan" <monnier@iro.umontreal.ca>; <emacs-devel@gnu.org>
Sent: Friday, October 22, 2004 10:30 PM
Subject: RE: uppercase var names in docstrings


: FWIW, my impression is the same as Stefan's.
:
: I think it might be good to try bold italic (and lowercase); I believe
that
: would stand out sufficiently. If bold italic is not supported by a given
: face, then bold would be a good second choice, plain uppercase being a
third
: choice. - Drew
:
:
: -----Original Message-----From: Stefan
: A few months ago, the help code was changed so that C-h f now looks for
the
: uppercase variable names and makes them lowercase&italics (if the terminal
: supports it).
:
: I waited to see how I'd like it and I must say that I'm actually annoyed
by
: the lowercasing: it makes it much harder for me to find the spot in
: a docstring where the use of a particular argument is described.
:
: Basically the problem is that varnames don't stand out as much as before,
: since the only thing that distinguishes them from normal text is
: the italics.
:
: Of course I can change my own setting easily, but if I'm not the only
: oddball who feels this way, maybe it'd better to change the default so
that
: such varnames are only made italics but not lowercase.

uppercase var names in docstrings

[Nick Roberts]

 > Of course I can change my own setting easily, but if I'm not the only
 > oddball who feels this way, maybe it'd better to change the default so that
 > such varnames are only made italics but not lowercase.

FWIW I agree. Uppercase stands out fine for me without the need for italics.

Nick

Re: uppercase var names in docstrings

[Miles Bader]

On Fri, Oct 22, 2004 at 10:56:03PM +0200, Lennart Borgman wrote:
> I am not very fond of italics on screen. They tend to appear rugged, at
> least on my screens. Uppercase have been a good alternative for me, but
> maybe bold italics is less rugged than just italics?

Ha ha, try "much more"...

-Miles
-- 
My spirit felt washed.  With blood.  [Eli Shin, on "The Passion of the Christ"]

Re: uppercase var names in docstrings

[David Kastrup]

Miles Bader <miles@gnu.org> writes:

> On Fri, Oct 22, 2004 at 10:56:03PM +0200, Lennart Borgman wrote:
>> I am not very fond of italics on screen. They tend to appear rugged, at
>> least on my screens. Uppercase have been a good alternative for me, but
>> maybe bold italics is less rugged than just italics?
>
> Ha ha, try "much more"...

Bold italics don't make sense.  Either italics or bold.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: uppercase var names in docstrings

[Lennart Borgman]

----- Original Message ----- 
From: "Miles Bader" <miles@gnu.org>

: > maybe bold italics is less rugged than just italics?
:
: Ha ha, try "much more"...

They are less rugged, statistically. That is of course what counts. They
just looks more rugged.

Re: uppercase var names in docstrings

[Miles Bader]

On Fri, Oct 22, 2004 at 04:10:53PM -0400, Stefan wrote:
> Of course I can change my own setting easily, but if I'm not the only
> oddball who feels this way, maybe it'd better to change the default so that
> such varnames are only made italics but not lowercase.

I find that the old-style uppercase names actually makes the text hard to
read for the opposite reason -- they stand out way _too_ much, they interrupt
the flow of reading (it's like reading a zippy quote!).

OTOH, I agree that italics-only is sometimes a bit hard to find in the text.
It depends a great deal on the fonts you use though -- at work I don't have
any problem with just italics.

At home, I use: lowercase+underline -- lowercase makes it read naturally like
part of the text, but the underlining makes them hard to miss.  [I realize
that some people may not like this because they look the same as hyperlinks;
I know the the difference between the two, so I don't care, but ...]

So, while maybe a tweak is in order, I think uppercase+(anything) is too much.

-Miles
-- 
(\(\
(^.^)
(")")
*This is the cute bunny virus, please copy this into your sig so it can spread.

Re: uppercase var names in docstrings

[Miles Bader]

On Sat, Oct 23, 2004 at 12:33:12AM +0200, Lennart Borgman wrote:
> : > maybe bold italics is less rugged than just italics?
> :
> : Ha ha, try "much more"...
> 
> They are less rugged, statistically. That is of course what counts. They
> just looks more rugged.

Huh?  Can you give some basis for that statement?

The "ruggedness" I assume that's being talked about comes from lots of
non-straight lines in the characters, and bold-italic has the same general
shape as the italic -- and so the same non-straight lines.  However in many
bold-italic fonts, instead of just a simple single-pixel (jagged) line, you
actually end up with an attempt to represent a thicker line of varying
thickness, which ends up looking even worse.

-Miles
-- 
(\(\
(^.^)
(")")
*This is the cute bunny virus, please copy this into your sig so it can spread.

Re: uppercase var names in docstrings

[Juri Linkov]

Miles Bader <miles@gnu.org> writes:
> At home, I use: lowercase+underline -- lowercase makes it read naturally like
> part of the text, but the underlining makes them hard to miss.  [I realize
> that some people may not like this because they look the same as hyperlinks;
> I know the the difference between the two, so I don't care, but ...]

Instead of italics (which is unreadable with small font sizes) I highlight
lowercase arguments in a dark color (namely, DeepSkyBlue4, but any other
dark color will work): it is close to black (which is the default text
color; however, in help-argument-name's defface it might depend on
dark/light background parameter), so it doesn't attract much attention.
OTOH, it still differs from black enough to stand out sufficiently.
So, lowercase+colors is another solution to try.

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

Re: uppercase var names in docstrings

[Kenichi Handa]

In article <m1is92plin.fsf-monnier+emacs@gnu.org>, Stefan <monnier@iro.umontreal.ca> writes:

> A few months ago, the help code was changed so that C-h f now looks for the
> uppercase variable names and makes them lowercase&italics (if the terminal
> supports it).

> I waited to see how I'd like it and I must say that I'm actually annoyed by
> the lowercasing: it makes it much harder for me to find the spot in
> a docstring where the use of a particular argument is described.

Me too.

> Basically the problem is that varnames don't stand out as much as before,
> since the only thing that distinguishes them from normal text is
> the italics.

> Of course I can change my own setting easily, but if I'm not the only
> oddball who feels this way, maybe it'd better to change the default so that
> such varnames are only made italics but not lowercase.

I fully agree with that.

---
Ken'ichi HANDA
handa@m17n.org

Re: uppercase var names in docstrings

[Richard Stallman]

    At home, I use: lowercase+underline -- lowercase makes it read naturally like
    part of the text, but the underlining makes them hard to miss.

We could use overline, or strike-through.  Using color, as people have
suggested, is also worth considering.