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

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

[Drew Adams]

This is mainly about the Elisp manual, but some of it might also apply
to the Emacs manual.
 
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'.
 
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. (BTW, shouldn't that always be
"graphic", not "graphical"?)
 
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)?
 
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"). 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).
 
And "graphical menu bar" (is there a non-graphical one?), "graphical
environment"... And there are undefined terms, such as
"multi-monitor", that are quoted (they should not be). Quoting a term
is not a substitute for explaining or defining it. (BTW, there is
quite a bit of such inappropriate quoting in the manuals -
e.g. "function keys".)
 
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.) Node Multiple Displays is a start,
but it doesn't bring it all together (as it shouldn't, since it is
only about multiple displays). And then please add xrefs back to that
section in places where the various terms are used.
 
Perhaps if I reread the whole manual front to back it would become
clear, but this is a muddle for me, so far.
 
My ignorance and confusion are no doubt due partly to the fact that I
haven't used Emacs without graphics support for 20 years, and if I did
perhaps I'd dig in an find out what gives. But I suspect that this
could be better presented for everyone.
 
Thanks.
 
 
 

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#3035: 23.0.92; doc, terminology for graphics, display, terminal, etc.

[Chong Yidong]

> 1. `display-graphic-p' has apparently been with us since Emacs 22, but
> there is still no mention of it in the Elisp manual.

See Display Feature Testing.

> 2. In the Elisp manual, I see the use of terms such as "graphical
> terminal" .. without any real explanation or definition.

See Frames.

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

Yes.  Try `emacs -q -nw'.

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

[Drew Adams]

Your reply hardly replies to all that is in the bug report.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 17 Apr 2009 19:03:19 -0700
> Cc: 3035@emacsbugs.donarmstrong.com
> 
> Your reply hardly replies to all that is in the bug report.

Which is why the bug isn't closed yet.

Really, Drew, you need to learn not to be so hard on people who are
trying to give serious attention to your report.  If you think your
attitude helps boost motivation, think again.

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

[Eli Zaretskii]

> 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.

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

[Drew Adams]

> > Your reply hardly replies to all that is in the bug report.
> Which is why the bug isn't closed yet.

I understand that.

> Really, Drew, you need to learn not to be so hard on people who are
> trying to give serious attention to your report.  If you think your
> attitude helps boost motivation, think again.

Giving attention to a bug report is not somehow doing a favor for the person who
reported the bug. Reporting a bug and fixing a bug are similarly (if not
equally) contributions to all Emacs users. I'm not asking for a favor; I'm
reporting a context in which one user found the doc confusing or wanting. HTH.
If that feedback helps, fine; if not, move on.

Really Eli, you need to stop telling others what they need to do. ;-) In
particular with regard to presumed attitudes, intentions, and motivations. Tell
your dog or your 2-year old what he needs to do, if you really have a need to
preach. Spare the rest of us your presumptuous sermons.

Do you have something to contribute to the bug thread? I'll bet you might, as
you often make improvements to the doc. But if not... 

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

[Drew Adams]

> > 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.

Yes, that helps wrt "graphical terminal" and "text terminal" (but not with the
rest).

It might help to add a cross-reference to node Frames from some of the nodes
that use the terms it defines/explains. (Judgment call, on a case-by-case
basis.)

> > 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.

Yes, got it. Thanks.

> 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.

This helps me, but perhaps that can also be made explicit in the manual.
(Perhaps it is, but I didn't notice it.)

> > 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.

Dependent vs independent clause. If all graphical terminals support extended
ASCII input, then it should be the latter. If only some of them do, then it
should be the former.

> > 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".

In that case, use "graphic display, which is capable of displaying several
frames and several different fonts".

The part after the comma is extra, non-essential info. It is implied by "graphic
display", since all graphic displays have this property. With no comma, the
phrase restricts the class of graphic displays to only those that have the
property.

> > 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.

I think it will be OK, if the quotes are removed.

(BTW, in my version, it says "On these "multi-monitor" setups, a single DISPLAY
value controls the output to all the physical monitors.")

> > (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?

OK, if it's a convention or a tool artifact, then nothing can be done (and
cancel what I said above about removing the quotes). I didn't realize that was
the convention we use to introduce defined terms.

What's wrong is that quoting is normally for, well, quoting. ;-) No text is
being quoted here. But it's OK to use whatever convention we want, as long as
it's consistent. I didn't know about the convention we use.

BTW, I see in passing this, in node Multiple Displays: "_the_ selected frame".
Is it normal that those underscores are shown as such? 

> > 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.

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. I tried `i' but didn't find "glossary" in
the index. I looked for "Glossary" in the top-level menu. I searched the manual
with C-s for "lossary". What am I missing?

(BTW, maybe `G' could take you to the glossary?)

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <cyd@stupidchicken.com>
> Date: Sat, 18 Apr 2009 00:17:04 -0700
> 
> Do you have something to contribute to the bug thread? I'll bet you might, as
> you often make improvements to the doc. But if not... 

Ha!  I guess by now you know better.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 18 Apr 2009 00:52:08 -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:
> > 
> >        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.
> 
> 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?

> (BTW, in my version, it says "On these "multi-monitor" setups, a single DISPLAY
> value controls the output to all the physical monitors.")

My citation was from today's CVS.

> 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.

> > 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.

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

[Chong Yidong]

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

> Your reply hardly replies to all that is in the bug report.

Obviously.

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

[Drew Adams]

> > > > 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.

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

[Drew Adams]

> > Do you have something to contribute to the bug thread?
> > I'll bet you might, as you often make improvements to the doc.
> > But if not... 
> 
> Ha!  I guess by now you know better.

The quote shows clearly that I was betting on you all along.

And your contribution and help _are_ appreciated.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <3035@emacsbugs.donarmstrong.com>
> 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.

They are synonymous.

> Likewise, for "text terminals" and "non-graphical-capable displays".

Also synonyms.

> 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?

"graphic characters" have nothing to do with displays or terminals.
They are named "graphic" because they match the [:graph:] regexp.

The only place I found "graphical attributes" is in the context of
face attributes.  Since faces are supported on text terminals as well,
these also don't have any direct relation to GUI vs TTY displays.

> Dunno if things like italics and bold fonts are feasible in the Info context,
> for stuff like this.

Someone needs to write code to display _foo_ in italics and *foo* in
bold in Info buffers.

> 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.

I don't think it's a good idea to show bold in Info when it comes out
as slanted in print.  And making this change in the printed output as
well would be unwise, IMO, as this is a very old and well-known
convention of Texinfo.
> Maybe a glossary in Elisp would be helpful too?

Probably.

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

[Drew Adams]

> > > > > > 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.
> 
> They are synonymous.
> 
> > Likewise, for "text terminals" and "non-graphical-capable displays".
> 
> Also synonyms.
> 
> > 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?
> 
> "graphic characters" have nothing to do with displays or terminals.
> They are named "graphic" because they match the [:graph:] regexp.
> 
> The only place I found "graphical attributes" is in the context of
> face attributes.  Since faces are supported on text terminals as well,
> these also don't have any direct relation to GUI vs TTY displays.

OK, so the point for the doc is that these things could perhaps be mentioned. I
appreciate knowing these things, but others might have the same questions or be
similarly confused.

Alternatively this possible confusion could perhaps be avoided, by using the
same term throughout (e.g. always "text terminal", not "non-graphical-capable
display").

> > 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.
> 
> I don't think it's a good idea to show bold in Info when it comes out
> as slanted in print.  And making this change in the printed output as
> well would be unwise, IMO, as this is a very old and well-known
> convention of Texinfo.

I see. But you said the same thing about emphasis (_foo_). If both "some
quotation" and _something emphasized_ appear as slanted text in print, then how
does a reader distinguish these uses?

> > Maybe a glossary in Elisp would be helpful too?
> 
> Probably.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <3035@emacsbugs.donarmstrong.com>
> Date: Sat, 18 Apr 2009 10:29:31 -0700
> 
> > I don't think it's a good idea to show bold in Info when it comes out
> > as slanted in print.  And making this change in the printed output as
> > well would be unwise, IMO, as this is a very old and well-known
> > convention of Texinfo.
> 
> I see. But you said the same thing about emphasis (_foo_). If both "some
> quotation" and _something emphasized_ appear as slanted text in print, then how
> does a reader distinguish these uses?

I think the reader cannot distinguish, indeed, by the typeface alone.
But @emph is really very rarely used, unlike @dfn; and then, there's
context.  So in practice the problem is not very big one, I think.  At
least I myself never had problems.

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

[Drew Adams]

> > > I don't think it's a good idea to show bold in Info when 
> > > it comes out as slanted in print.  And making this change
> > > in the printed output as well would be unwise, IMO, as
> > > this is a very old and well-known convention of Texinfo.
> > 
> > I see. But you said the same thing about emphasis (_foo_). 
> > If both "some quotation" and _something emphasized_ appear
> > as slanted text in print, then how
> > does a reader distinguish these uses?
> 
> I think the reader cannot distinguish, indeed, by the typeface alone.
> But @emph is really very rarely used, unlike @dfn; and then, there's
> context.  So in practice the problem is not very big one, I think.  At
> least I myself never had problems.

OK.

IMO, using slant for a defined term in print is not too good, and having the
same appearance for defined terms and emphasized text (unrelated) is also not
too good. I'm a bit surprised, frankly, given the fine-grained print
representation of things like keys - by contrast, this seems rather coarse. But
if this is the long-established Texinfo convention, so be it.

Here are some possibilities for defined terms in Info - that is, terms that are
defined in place (whether or not they are also listed in a separate glossary). I
assume that both "..." and _..._ will continue to be slant in print. And I
assume emphasis in Info will continue to be shown using italics.

* italics
* bold
* underlining (not underscore wrappers)
* some other face (e.g. color)

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

[Stefan Monnier]

> IMO, using slant for a defined term in print is not too good, and having the
> same appearance for defined terms and emphasized text (unrelated) is also not
> too good.

AFAIK, it's just common practice for definitions.  The italics is used
to emphasize the fact that this term is used with a specific meaning,
which is being explained.


        Stefan

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

[Drew Adams]

> > IMO, using slant for a defined term in print is not too 
> > good, and having the same appearance for defined terms
> > and emphasized text (unrelated) is also not too good.
> 
> AFAIK, it's just common practice for definitions.  The italics is used
> to emphasize the fact that this term is used with a specific meaning,
> which is being explained.

Nope. Not common practice. And that reasoning (defined term is important, so use
emphasis) is an invention.

But you are free to invent your own conventions. ;-)

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

[Stefan Monnier]

>> > IMO, using slant for a defined term in print is not too 
>> > good, and having the same appearance for defined terms
>> > and emphasized text (unrelated) is also not too good.
>> AFAIK, it's just common practice for definitions.  The italics is used
>> to emphasize the fact that this term is used with a specific meaning,
>> which is being explained.
> Nope.  Not common practice.

You're simply wrong.  Maybe in the texts you read it's not
common practice.  But in the texts I read it is.

> And that reasoning (defined term is important, so use
> emphasis) is an invention.

Not at all.  A good example would be when you define what a /type/ is.
Or what an /object/ is, in a programming book.  If you don't emphasize
correctly, the reader may end up not noticing/understanding exactly what
term you're defining because that term already has meaning to
the reader.


        Stefan

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

[Drew Adams]

> >> > IMO, using slant for a defined term in print is not too 
> >> > good, and having the same appearance for defined terms
> >> > and emphasized text (unrelated) is also not too good.
> >>
> >> AFAIK, it's just common practice for definitions.  The 
> >> italics is used to emphasize the fact that this term is
> >> used with a specific meaning, which is being explained.
> >
> > Nope.  Not common practice.
> 
> You're simply wrong. Maybe in the texts you read it's not
> common practice. But in the texts I read it is.

Read more. Technical manuals, in particular, since that is the domain in
question.

Yes, some do adopt the same appearance (e.g. italics) for defined terms as for
emphasis (stress). You might argue that there are enough that do this that it
can be called _a_ common practice, but it is by no means _the_ common practice.

Making it clear that a defined term is a defined term (and not just a stressed
word) helps readability and understanding. If in some medium or context there is
no easy way to do that (limited set of fonts, colors, etc.), then a fallback
approach is to reuse some typography (e.g. italics) that also indicates
something else (e.g. emphasis).

If we had only italics available to font-lock, you might argue that it is great
that all font-lock keywords use italics. But we have more faces available, and
we use them to indicate different things. Why? Because it helps readability.

> > And that reasoning (defined term is important, so use
> > emphasis) is an invention.
> 
> Not at all.  A good example would be when you define what a /type/ is.
> Or what an /object/ is, in a programming book.  If you don't emphasize
> correctly, the reader may end up not noticing/understanding 
> exactly what term you're defining because that term already
> has meaning to the reader.

Red herring. Obviously, such terms need to be made to stand out (emphasized). I
stated that from the beginning.

That's precisely my point: They should stand out not only from the surrounding
text, but also from ordinary emphasis (stress). They should stand out
specifically _as defined terms_: if possible, they should have their own
typography.

This is about reusing emphasis (e.g. slant), as intended for stress, to serve
another purpose (definition terms). I did not propose to change this Texinfo
convention; I simply said that it's not ideal.

A common example of emphasis for stress is the `em' tag in HTML, which is
typically rendered using italics (whereas tag `strong' is typically rendered as
bold). Such emphasis is designed to indicate stress, but there is nothing
stopping someone from abusing it to fill double-duty for other purposes. That
doesn't mean that such abuse is a great idea.

Following your logic, in Emacs Info we should _not_ render definition terms and
emphasis (for stress) differently. That is, you would apparently argue to
collapse _xxx_ and "xxx" into a single appearance, since that "is common
practice". That would be unfortunate for Info, and it is not ideal for print
either.

In technical literature there are a number of other thingies that must also
stand out (parameters, syntax description terms, keywords, constants...) - from
both the surrounding text and from each other. Using the same appearance (e.g.
italics or slant) for several of them makes reading with understanding more
difficult. Different context can help disambiguate, but in the same context
confusion can result.

In any case, I already stated that I'm not proposing to change the Texinfo
convention ("so be it"). So your intervention is off the mark. Unless you do
indeed propose to remove the existing distinction in Info between defined terms
("...") and emphasized text (_..._). That would not be good. But you might
retort that it is common practice... I'll stop here.

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

[Stefan Monnier]

>> You're simply wrong. Maybe in the texts you read it's not
>> common practice. But in the texts I read it is.
> Read more. Technical manuals, in particular, since that is the domain in
> question.

> Yes, some do adopt the same appearance (e.g. italics) for defined
> terms as for emphasis (stress). You might argue that there are enough
> that do this that it can be called _a_ common practice, but it is by
> no means _the_ common practice.

What other convention have you seen?

> Red herring. Obviously, such terms need to be made to stand out
> (emphasized).  I stated that from the beginning.

Sorry, I had missed that part.  I'm glad we agree.


        Stefan

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

[Lars Magne Ingebrigtsen]

Reading the thread here, I think most things were resolved, so I'm
closing the bug report.  If there were some things that weren't handled,
a new report can be opened.

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