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

From: "Drew Adams" <[email-masked]>
Date: Sat, 18 Apr 2009 09:23:09 -0700

> > > > 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:...
> > > If this is not good enough, please tell what is missing.
> > 
> > Yes, that helps wrt "graphical terminal" and "text 
> > terminal" (but not with the rest).
> 
> But that's what your Item 2 (above) was all about: the distinction
> between text and graphical terminals.  What else is needed?

Yes and no. Yes for these: "graphical display", "graphics display", and
"graphics-capable display", if one understands that they are synonymous.
Likewise, for "text terminals" and "non-graphical-capable displays".

But that was part of the point of #2: are they all different, or do some of them
mean the same thing? What do the various terms mean?

It's also not clear to me how "graphic characters" and "graphical attributes"
fit in with the others. For instance, are they implied by "graphical display"?
Does any of them alone imply "graphical display"? What does each of them mean?

Then there's the question of "graphic" vs "graphical". If the same thing is
always meant, then it's better to be consistent and use a single term
throughout. This is minor, but not necessarily only cosmetic; users can actually
get confused and wonder whether such things are different.

> > BTW, I see in passing this, in node Multiple Displays: 
> "_the_ selected frame".
> > Is it normal that those underscores are shown as such? 
> 
> That's how emphasis is shown in Info.  In print, it comes out in
> slanted typeface.

OK, I figured it might be something like that. But I wonder if that's a good
idea. In technical doc, names are often considered literally (not in this case,
however) - someone might think that the underscore character was, well, an
underscore character.

In *Help* we now use italics instead of all uppercase. Dunno if that would be
possible or a good idea, but italics is often used for emphasis. Another
possibility would be all uppercase (but then there is the same potential problem
of being taken literally as for underscore).

Dunno if things like italics and bold fonts are feasible in the Info context,
for stuff like this. If so, you might also consider using bold instead of
quoting, for defined terms (another item we discussed). That is a convention
often used in technical doc.

FWIW, in my own code, I use a different face for quotations (likewise, for
`...'), and it is quite helpful in making them stand out. If glossary terms were
bold or some other face, instead of quoted, I think it would be an improvement.
Again, dunno how feasible that is.

For emphasis, I'd suggest that if it's not possible to use something like
italics, then nothing should be used. Emphasis should always be extra anyway;
the text itself should stress what needs to be stressed. IOW, my suggestion
would be to just drop the underscores, if italics (or some other face) is not
possible here.

> > > 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.
> > 
> > I see. That's good.
> > 
> > How do I get to the Glossary node? I tried `g Glossary' and 
> > got no match. I tried `C-h m' and `?' and looked for
> > "Glossary" in the Info mode help and
> > summary, but didn't find it in either.
> 
> Sorry, I mean the Glossary in the Emacs manual, not in ELisp.

OK. Maybe a glossary in Elisp would be helpful too?

My other comments might also help: mention in `?' and `C-h m' (adding "when
present" or something); add as an index item; add a `G' binding.

In particular, it would help to add `glossary' as an index item whenever there
is a glossary. I can tell from help-gnu-emacs questions any users don't yet
think in terms of `g' and node names.