bug#3035: 23.0.92; doc, terminology for graphics, display, terminal, etc.

[Eli Zaretskii <eliz@gnu.org>]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 17 Apr 2009 09:46:36 -0700
> Cc: 
> 
> 1. `display-graphic-p' has apparently been with us since Emacs 22, but
> there is still no mention of it in the Elisp manual. Please document
> how/when it is to be used, compared, for instance with when to use
> `window-system'.

This part is resolved by now, I presume.

> 2. In the Elisp manual, I see the use of terms such as "graphical
> terminal", "graphicical display" (also "graphics display"),
> "(non-)graphics-capable display", "text terminals" (opposed to
> graphical), "graphic characters", and "graphical attributes", without
> any real explanation or definition.

From the node "Frames", near the beginning:

       There are two classes of terminals: text-only terminals and
    graphical terminals.  Text-only terminals are non-graphics-capable
    display devices, including "terminal emulators" such as xterm.  On
    text-only terminals, each frame occupies the entire terminal screen;
    although you can create additional frames and switch between them, only
    one frame can be shown at any given time.  We refer to frames on
    text-only terminals as "terminal frames".  Graphical terminals, on the
    other hand, are graphics-capable windowing systems, such as the X
    Window System.  On a graphical terminal, Emacs can display multiple
    frames simultaneously.  We refer to such frames as "window frames".

If this is not good enough, please tell what is missing.

> Does "graphic" imply mouse support? font support? fringe support?
> color support? menu support? tool-bar support, image support?
> multiple-frame support? All of these? Does non-graphics imply absence
> of all or limited support of some (e.g. frames and colors and fonts)?

The node "Display Feature Testing" includes predicates and other APIs
that will allow you to test specifically for each one of the questions
you ask above.  Exceptions:

  . Menus are supported on all kinds of displays.  If you want to ask
    about pop-up and drop-down menus, use display-popup-menus-p.

  . Tool bar can be on or off even when it is supported, so the proper
    test is to look at the value of tool-bar-mode.

  . Fringe is covered by display-graphic-p.

> And there are apparently finer distinctions (which also don't seem to
> be explained), such as "graphical terminal that supports extended
> ASCII input" (unless what is really meant is "graphical terminal,
> which supports extended ASCII input").

Maybe it's because English nuances evade me, but I don't see any
difference between these two wordings.

> And "graphic display capable of
> displaying several frames and several different fonts" (unless what is
> really meant is that all graphic displays are so capable).

The latter.  Again, see "Display Feature Testing".

> And "graphical menu bar" (is there a non-graphical one?)

Yes, there is.

> And there are undefined terms, such as "multi-monitor"

They are defined, at least as best as someone who wrote that could:

       On some "multi-monitor" setups, a single X display outputs to more
    than one monitor.

If that definition lacks something, please tell what is missing.

> (BTW, there is quite a bit of such inappropriate quoting in the
> manuals - e.g. "function keys".)

Quoting is what makeinfo produces from @dfn, a markup that introduces
new terminology.  It should be followed or preceded by an explanation;
if there is one, what's wrong with this quoting?

> Perhaps it would be good to see all of these terms explained together
> somewhere: display, terminal, monitor, screen, graphic *, frame. (I
> assume none of these are synonyms.)

They are not.  Each one should be explained in its own place, and the
more important ones, although certainly not all, are in the Glossary
node.