Re: cannot understand Elisp manual node Glyphs

[storm@cua.dk (Kim F. Storm)]

storm@cua.dk (Kim F. Storm) writes:

> Furthermore, the unicode branch only allows the first 511 faces
> defined to be used in glyph-code (vs. 4088 in Emacs 22) ... so maybe
> the whole implementation of glyph-codes need to be revised in Emacs 23
> -- yet another reason for making a clean interface for this NOW.

I've thought a little more about the Emacs 23 issue with glyph codes.

The current implementation (using a Lisp integer) is simply inadequate
for Emacs 23, so a solution must be found for it (perhaps using a cons
(char . face) or a float to represent glyph codes with faces.

This means that we will have to introduce the suggested functions
anyway at some point ... but by introducing them now, we prepare the
necessary framework for Emacs 23.

Consequently, mentioning at all how faces are encoded in glyph codes
in the lisp reference is a mistake - as this implementation will change
in the next Emacs release.

Here is a shot at rewording the glyph code section of the lispref
in an "Emacs 23 compatible" way (using the proposed new glyph API
functions):

*** display.texi	02 Feb 2007 11:06:10 +0100	1.247
--- display.texi	09 Feb 2007 14:57:07 +0100
***************
*** 5266,5291 ****

  @cindex glyph
    A @dfn{glyph} is a generalization of a character; it stands for an
! image that takes up a single character position on the screen.  Glyphs
! are represented in Lisp as integers, just as characters are.  Normally
! glyph come from vectors in the display table (@pxref{Display Tables}).
!
!   A glyph code can be @dfn{simple} or it can be defined by the
! @dfn{glyph table}.  A simple glyph code is just a way of specifying a
! character and a face to output it in.  When a glyph code is simple,
! the code, mod 524288, is the character to output, and the code divided
! by 524288 specifies the face number (@pxref{Face Functions}) to use
! while outputting it.  (524288 is
! @ifnottex
! 2**19.)
! @end ifnottex
! @tex
! $2^{19}$.)
! @end tex
! @xref{Faces}.

    On character terminals, you can set up a @dfn{glyph table} to define
! the meaning of glyph codes.

  @defvar glyph-table
  The value of this variable is the current glyph table.  It should be
--- 5266,5297 ----

  @cindex glyph
    A @dfn{glyph} is a generalization of a character; it stands for an
! image that takes up a single character position on the screen.  Normally
! glyphs come from vectors in the display table (@pxref{Display Tables}).
!
!   A glyph is represented in Lisp as a @dfn{glyph code}.  A glyph code
! can be @dfn{simple} or it can be defined by the @dfn{glyph table}.  A
! simple glyph code is just a way of specifying a character and a face
! to output it in.  @xref{Faces}.
!
!   The following functions are used to manipulate simple glyph codes:
!
! @defun make-glyph-code char &optional face
! This function returns a simple glyph code representing char @var{char}
! with face @var{face}.
! @end defun
!
! @defun glyph-char glyph
! This function returns the character of simple glyph code @var{glyph}.
! @end defun
!
! @defun glyph-face glyph
! This function returns face of simple glyph code @var{glyph}, or
! @code{nil} if @var{glyph} has the default face (face-id 0).
! @end defun

    On character terminals, you can set up a @dfn{glyph table} to define
! the meaning of glyph codes (represented as small integers).

  @defvar glyph-table
  The value of this variable is the current glyph table.  It should be
***************
*** 5307,5316 ****
  Send the characters in @var{string} to the terminal to output
  this glyph code.

! @item @var{integer}
! Define this glyph code as an alias for glyph code @var{integer}.  You
! can use such an alias to define a small-numbered glyph code which
! specifies a face.

  @item @code{nil}
  This glyph code is simple.
--- 5313,5322 ----
  Send the characters in @var{string} to the terminal to output
  this glyph code.

! @item @var{code}
! Define this glyph code as an alias for glyph code @var{code} created
! by @code{make-glyph-code}.  You can use such an alias to define a
! small-numbered glyph code which specifies a character with a face.

  @item @code{nil}
  This glyph code is simple.

--
Kim F. Storm <storm@cua.dk> http://www.cua.dk