bug#3042: 23.0.92; display-visual class doc

bug#3042: 23.0.92; display-visual class doc

[Drew Adams]

The doc does not explain what the possible values mean. There are no
other occurrences of the various values (e.g. `static-color') in the
Elisp manual or other doc strings (that I can find) than what is said
about `display-visual-class'.
 
To use a function, it helps to know its possible values, but if you
have no idea what those values indicate or mean, then you really don't
know much about the function.
 
Grepping the Emacs sources doesn't really help here either. Looking at
the definition of `display-visual-class', you can at least learn
something (partial) about `static-color' and `static-gray', but that's
about it.
 

In GNU Emacs 23.0.92.1 (i386-mingw-nt5.1.2600)
 of 2009-03-30 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#3042: 23.0.92; display-visual class doc

[Drew Adams]

> The doc does not explain what the possible values mean. There are no
> other occurrences of the various values (e.g. `static-color') in the
> Elisp manual or other doc strings (that I can find) than what is said
> about `display-visual-class'.
>  
> To use a function, it helps to know its possible values, but if you
> have no idea what those values indicate or mean, then you really don't
> know much about the function.
>  
> Grepping the Emacs sources doesn't really help here either. Looking at
> the definition of `display-visual-class', you can at least learn
> something (partial) about `static-color' and `static-gray', but that's
> about it.

Not being very knowledgeable in this area, I googled a bit. "Color cell" didn't
turn up much. This term needs explaining, no doubt.

Wikipedia helped with this page, which I got to after looking at the bit-plane
page:
http://en.wikipedia.org/wiki/Color_depth. We might draw on its description of
"direct color" and "true color", for example. I'm guessing that what we call
"static color" might be what that page calls "indexed color"? If so, perhaps we
should also mention that term, if it's commonly used.

HTH.

bug#3042: 23.0.92; display-visual class doc

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> The doc does not explain what the possible values mean. There are no
> other occurrences of the various values (e.g. `static-color') in the
> Elisp manual or other doc strings (that I can find) than what is said
> about `display-visual-class'.

I've now changed the section to this:

@defun display-visual-class &optional display
This function returns the visual class for the screen.  The value is
one of the symbols @code{static-gray} (a limited, unchangeable number
of grays), @code{gray-scale} (a full range of grays),
@code{static-color} (a limited, unchangeable number of colors),
@code{pseudo-color} (a limited number of colors), @code{true-color} (a
full range of colors), and @code{direct-color} (a full range of
colors).
@end defun

I think that's probably somewhat correct, although I'm not sure what
`pseudo-color' really is.  Anybody?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#3042: 23.0.92; display-visual class doc

[Drew Adams]

> I've now changed the section to this:
> 
> @defun display-visual-class &optional display
> This function returns the visual class for the screen.  The value is
> one of the symbols @code{static-gray} (a limited, unchangeable number
> of grays), @code{gray-scale} (a full range of grays),
> @code{static-color} (a limited, unchangeable number of colors),
> @code{pseudo-color} (a limited number of colors), @code{true-color} (a
> full range of colors), and @code{direct-color} (a full range of
> colors).
> @end defun

Thanks; that helps, I think.

> I think that's probably somewhat correct, although I'm not sure what
> `pseudo-color' really is.  Anybody?

Someone else?