cannot understand Elisp manual node Glyphs

cannot understand Elisp manual node Glyphs

[Drew Adams]

I can't tell how much of this problem is me and how much is the text, but I
don't understand this Elisp manual node.

I use the following code, to display ^L using a vector of glyphs that says
this:

__________ Section (Printable Page) __________

(defcustom 1on1-^L-appearance-vector
  (vconcat (make-vector 10 ?_)
           " Section (Printable Page) "
           (make-vector 10 ?_))
 "..." ...)

(aset standard-display-table ?\014 1on1-^L-appearance-vector)

That works fine. However, I'd like to also apply a face to the displayed
glyphs. I figure that manual node Glyphs is trying to tell me, among other
things, how to do that, but I can't figure it out.

It seems to say that the glyphs that I am using, and should be using, have
"simple glyph codes". It does not say what a glyph "code" is, BTW.

It also says that a simple glyph code specifies both a character and a face.
The character is the code mod 524288; the face number is the code / 524288.

So how do I use that information, to apply a face to my vector of glyphs?
Maybe that's not the right way to say it. How can I have the glyph vector
that I use to display ^L appear in a particular face?

There seems to be a wide gulf between the kind of info that is available in
this node (glyph codes, face numbers) and practical use of that information.
I imagine that I'm not too far from my quest, but I haven't a clue where to
head.

Assistance appreciated. Perhaps we can improve the manual a bit in the
process.

Re: cannot understand Elisp manual node Glyphs

[Kim F. Storm]

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

>
> It seems to say that the glyphs that I am using, and should be using, have
> "simple glyph codes". It does not say what a glyph "code" is, BTW.
>
> It also says that a simple glyph code specifies both a character and a face.
> The character is the code mod 524288; the face number is the code / 524288.
>

I also find this part highly dubious - mainly by exposing internal
representation details.

> So how do I use that information, to apply a face to my vector of glyphs?
> Maybe that's not the right way to say it. How can I have the glyph vector
> that I use to display ^L appear in a particular face?
>

These functions are handy:

(defun make-glyph-with-face (c face)
  "Return a glyph code representing char C with face FACE."
  (logior c (lsh (face-id face) 19)))

(defun glyph-char (glyph)
  "Return the character of glyph code GLYPH."
  (logand glyph #x7ffff))

(defun glyph-face (glyph)
  "Return the face of glyph code GLYPH, or nil if glyph has no face."
  (let ((face-id (lsh glyph -19)))
    (car (delq nil (mapcar (lambda (face)
			     (and (eq (get face 'face) face-id)
				  face))
			   (face-list))))))

                               
> There seems to be a wide gulf between the kind of info that is available in
> this node (glyph codes, face numbers) and practical use of that information.
> I imagine that I'm not too far from my quest, but I haven't a clue where to
> head.
>
> ... Perhaps we can improve the manual a bit in the process.


I know this is not "the right time", but IMO adding these functions
could significantly improve both code and documentation.

I guess we wouldn't even need to describe what face numbers are
(actually, we don't -- there's no index entry for it).


So my proposal is to add thosed functions, to:

a) simplify the documentation (and code)
b) hide the technical details of glyph faces, and
c) allow us to change the implementation later without breaking code:

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

RE: cannot understand Elisp manual node Glyphs

[Drew Adams]

> > It seems to say that the glyphs that I am using, and should be
> > using, have "simple glyph codes". It does not say what a glyph
> > "code" is, BTW.
> >
> > It also says that a simple glyph code specifies both a
> > character and a face. The character is the code mod 524288; the
> > face number is the code / 524288.
>
> I also find this part highly dubious - mainly by exposing internal
> representation details.
>
> > So how do I use that information, to apply a face to my vector
> > of glyphs? Maybe that's not the right way to say it. How can I
> > have the glyph vector that I use to display ^L appear in a
> > particular face?
>
> These functions are handy:
...
> > There seems to be a wide gulf between the kind of info that is
> > available in this node (glyph codes, face numbers) and practical
> > use of that information.
> > I imagine that I'm not too far from my quest, but I haven't a
> > clue where to head.

Thanks for those functions Kim. I'll take a look. Offhand, I'm still not
sure how to do what I want. How can I set a character in the display table
to be displayed with a vector of glyphs that have a given face? Do I create
a propertized string, convert it to a vector, and use that as the glyph
vector, or what?

> I know this is not "the right time", but IMO adding these functions
> could significantly improve both code and documentation.

I think so too.

> I guess we wouldn't even need to describe what face numbers are
> (actually, we don't -- there's no index entry for it).
>
> So my proposal is to add thosed functions, to:
>
> a) simplify the documentation (and code)
> b) hide the technical details of glyph faces, and
> c) allow us to change the implementation later without breaking code:

Sounds good to me.

Re: cannot understand Elisp manual node Glyphs

[Kim F. Storm]

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

> Thanks for those functions Kim. I'll take a look. Offhand, I'm still not
> sure how to do what I want. How can I set a character in the display table
> to be displayed with a vector of glyphs that have a given face? Do I create
> a propertized string, convert it to a vector, and use that as the glyph
> vector, or what?

You set each element of the vector using make-glyph-with-face, e.g.

(vector (make-glyph-with-face ?x 'bold)
        (make-glyph-with-face ?y 'bold)
        (make-glyph-with-face ?z 'bold))



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

RE: cannot understand Elisp manual node Glyphs

[Drew Adams]

> You set each element of the vector using make-glyph-with-face, e.g.
> 
> (vector (make-glyph-with-face ?x 'bold)
>         (make-glyph-with-face ?y 'bold)
>         (make-glyph-with-face ?z 'bold))

I see; thx.

RE: cannot understand Elisp manual node Glyphs

[Stuart D. Herring]

>> You set each element of the vector using make-glyph-with-face, e.g.
>>
>> (vector (make-glyph-with-face ?x 'bold)
>>         (make-glyph-with-face ?y 'bold)
>>         (make-glyph-with-face ?z 'bold))
>
> I see; thx.

For what it's worth, I offer

(defun string-to-glyphs (str &optional face)
  "Return a glyph vector representing string STR with face FACE."
  (vconcat (mapcar (lambda (c) (make-glyph-with-face c face)) str)))

where I have trivially extended Kim's function:

(defun make-glyph-with-face (c face)
  "Return a glyph code representing char C with face FACE."
  (logior c (lsh (if face (face-id face) 0) 19)))

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

RE: cannot understand Elisp manual node Glyphs

[Drew Adams]

> For what it's worth, I offer
> (defun string-to-glyphs (str &optional face)
>   "Return a glyph vector representing string STR with face FACE."
>   (vconcat (mapcar (lambda (c) (make-glyph-with-face c face)) str)))

Just what I was going to do. But I agree that we might as well have such a
function.
(However, the case where FACE is nil needs to be treated also.)

RE: cannot understand Elisp manual node Glyphs

[Stuart D. Herring]

>> For what it's worth, I offer
>> (defun string-to-glyphs (str &optional face)
>>   "Return a glyph vector representing string STR with face FACE."
>>   (vconcat (mapcar (lambda (c) (make-glyph-with-face c face)) str)))
>
> Just what I was going to do. But I agree that we might as well have such a
> function.
> (However, the case where FACE is nil needs to be treated also.)

I did handle that case; see my modified version of Kim's
make-glyph-with-face function which I included in the same message.  Of
course, since then he's made an equivalent modification, renamed the
function, and packaged the whole thing as a manual and code patch.

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

Re: cannot understand Elisp manual node Glyphs

[Miles Bader]

storm@cua.dk (Kim F. Storm) writes:
> These functions are handy:
>
> (defun make-glyph-with-face (c face)
>   "Return a glyph code representing char C with face FACE."
>   (logior c (lsh (face-id face) 19)))

Good idea, but why not just call it "make-glyph"...?

-miles

-- 
Quidquid latine dictum sit, altum viditur.

Re: cannot understand Elisp manual node Glyphs

[Kim F. Storm]

Miles Bader <miles@gnu.org> writes:

> storm@cua.dk (Kim F. Storm) writes:
>> These functions are handy:
>>
>> (defun make-glyph-with-face (c face)
>>   "Return a glyph code representing char C with face FACE."
>>   (logior c (lsh (face-id face) 19)))
>
> Good idea, but why not just call it "make-glyph"...?

Because Xemacs already has a function named make-glyph with
different semantics.

But maybe we don't need to care about that?

Maybe the face arg should be optional, and we could use the
following names to avoid confusion:

make-display-glyph (char &optional face)
display-glyph-face (glyph)
display-glyph-char (glyph)


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

Re: cannot understand Elisp manual node Glyphs

[David Kastrup]

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

> Miles Bader <miles@gnu.org> writes:
>
>> storm@cua.dk (Kim F. Storm) writes:
>>> These functions are handy:
>>>
>>> (defun make-glyph-with-face (c face)
>>>   "Return a glyph code representing char C with face FACE."
>>>   (logior c (lsh (face-id face) 19)))
>>
>> Good idea, but why not just call it "make-glyph"...?
>
> Because Xemacs already has a function named make-glyph with
> different semantics.
>
> But maybe we don't need to care about that?

In my opinion, we really should.  It is one thing if stuff fails with
undefined functions when porting.  It is another if stuff fails in
mysterious ways (at best because of incompatible argument types).

> Maybe the face arg should be optional, and we could use the
> following names to avoid confusion:
>
> make-display-glyph (char &optional face)
> display-glyph-face (glyph)
> display-glyph-char (glyph)

Well, picking from the doc string, make-glyph-code would seem a
suitable choice, too.

-- 
David Kastrup

Re: cannot understand Elisp manual node Glyphs

[Kim F. Storm]

David Kastrup <dak@gnu.org> writes:

> Well, picking from the doc string, make-glyph-code would seem a
> suitable choice, too.

Good idea.

Here is a complete patch:

*** display.texi	02 Feb 2007 11:06:10 +0100	1.247
--- display.texi	08 Feb 2007 11:32:56 +0100	
***************
*** 5272,5280 ****
  
    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.)
--- 5272,5298 ----
  
    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
! 
!   Internally, a simple glyph code is an integer @var{gc}, where @var{gc}
! modulo 524288 is the character to output, and @var{gc} divided
! by 524288 specifies the face-id (@pxref{Face Functions}) to use
  while outputting it.  (524288 is
  @ifnottex
  2**19.)
***************
*** 5282,5288 ****
  @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.
--- 5300,5305 ----


*** disp-table.el	21 Jan 2007 21:52:32 +0100	1.64
--- disp-table.el	08 Feb 2007 11:34:24 +0100	
***************
*** 172,178 ****
    (aset standard-display-table c
  	(vector
  	 (if window-system
! 	     (logior uc (lsh (face-id 'underline) 19))
  	   (create-glyph (concat "\e[4m" (char-to-string uc) "\e[m"))))))
  
  ;;;###autoload
--- 172,178 ----
    (aset standard-display-table c
  	(vector
  	 (if window-system
! 	     (make-glyph-code uc 'underline)
  	   (create-glyph (concat "\e[4m" (char-to-string uc) "\e[m"))))))
  
  ;;;###autoload
***************
*** 187,192 ****
--- 187,214 ----
    (1- (length glyph-table)))
  
  ;;;###autoload
+ (defun make-glyph-code (char &optional face)
+   "Return a glyph code representing char CHAR with face FACE."
+   (if face
+       (logior char (lsh (face-id face) 19))
+     char))
+ 
+ ;;;###autoload
+ (defun glyph-char (glyph)
+   "Return the character of glyph code GLYPH."
+   (logand glyph #x7ffff))
+ 
+ ;;;###autoload
+ (defun glyph-face (glyph)
+   "Return the face of glyph code GLYPH, or nil if glyph has default face."
+   (let ((face-id (lsh glyph -19)))
+     (and (> face-id 0)
+ 	 (car (delq nil (mapcar (lambda (face)
+ 				  (and (eq (get face 'face) face-id)
+ 				       face))
+ 				(face-list)))))))
+ 
+ ;;;###autoload
  (defun standard-display-european (arg)
    "Semi-obsolete way to toggle display of ISO 8859 European characters.
  
*** descr-text.el	21 Jan 2007 21:52:32 +0100	1.54
--- descr-text.el	08 Feb 2007 10:54:37 +0100	
***************
*** 528,538 ****
  		  (setq char (aref disp-vector i))
  		  (aset disp-vector i
  			(cons char (describe-char-display
! 				    pos (logand char #x7ffff)))))
  		(format "by display table entry [%s] (see below)"
  			(mapconcat
  			 #'(lambda (x)
! 			     (format "?%c" (logand (car x) #x7ffff)))
  			 disp-vector " ")))
  	       (composition
  		(let ((from (car composition))
--- 528,538 ----
  		  (setq char (aref disp-vector i))
  		  (aset disp-vector i
  			(cons char (describe-char-display
! 				    pos (glyph-char char)))))
  		(format "by display table entry [%s] (see below)"
  			(mapconcat
  			 #'(lambda (x)
! 			     (format "?%c" (glyph-char (car x))))
  			 disp-vector " ")))
  	       (composition
  		(let ((from (car composition))
***************
*** 627,651 ****
  	      (progn
  		(insert "these fonts (glyph codes):\n")
  		(dotimes (i (length disp-vector))
! 		  (insert (logand (car (aref disp-vector i)) #x7ffff) ?:
  			  (propertize " " 'display '(space :align-to 5))
  			  (if (cdr (aref disp-vector i))
  			      (format "%s (#x%02X)" (cadr (aref disp-vector i))
  				      (cddr (aref disp-vector i)))
  			    "-- no font --")
  			  "\n")
! 		  (when (> (car (aref disp-vector i)) #x7ffff)
! 		    (let* ((face-id (lsh (car (aref disp-vector i)) -19))
! 			   (face (car (delq nil (mapcar
! 						 (lambda (face)
! 						   (and (eq (face-id face)
! 							    face-id) face))
! 						 (face-list))))))
! 		      (when face
! 			(insert (propertize " " 'display '(space :align-to 5))
! 				"face: ")
! 			(insert (concat "`" (symbol-name face) "'"))
! 			(insert "\n"))))))
  	    (insert "these terminal codes:\n")
  	    (dotimes (i (length disp-vector))
  	      (insert (car (aref disp-vector i))
--- 627,645 ----
  	      (progn
  		(insert "these fonts (glyph codes):\n")
  		(dotimes (i (length disp-vector))
! 		  (insert (glyph-char (car (aref disp-vector i))) ?:
  			  (propertize " " 'display '(space :align-to 5))
  			  (if (cdr (aref disp-vector i))
  			      (format "%s (#x%02X)" (cadr (aref disp-vector i))
  				      (cddr (aref disp-vector i)))
  			    "-- no font --")
  			  "\n")
! 		  (let ((face (glyph-face (car (aref disp-vector i)))))
! 		    (when face
! 		      (insert (propertize " " 'display '(space :align-to 5))
! 			      "face: ")
! 		      (insert (concat "`" (symbol-name face) "'"))
! 		      (insert "\n")))))
  	    (insert "these terminal codes:\n")
  	    (dotimes (i (length disp-vector))
  	      (insert (car (aref disp-vector i))


*** latin1-disp.el	21 Jan 2007 21:53:10 +0100	1.23
--- latin1-disp.el	08 Feb 2007 10:44:28 +0100	
***************
*** 177,190 ****
        (if (eq 'default latin1-display-face)
  	  (standard-display-ascii char (format latin1-display-format display))
  	(aset standard-display-table char
! 	      (vconcat (mapcar (lambda (c)
! 				 (logior c (lsh (face-id latin1-display-face)
! 						19)))
  			       display))))
      (aset standard-display-table char
! 	  (if (eq 'default latin1-display-face)
! 	      display
! 	    (logior display (lsh (face-id latin1-display-face) 19))))))
  
  (defun latin1-display-identities (charset)
    "Display each character in CHARSET as the corresponding Latin-1 character.
--- 177,186 ----
        (if (eq 'default latin1-display-face)
  	  (standard-display-ascii char (format latin1-display-format display))
  	(aset standard-display-table char
! 	      (vconcat (mapcar (lambda (c) (make-glyph-code c latin1-display-face))
  			       display))))
      (aset standard-display-table char
! 	  (make-glyph-code display latin1-display-face))))
  
  (defun latin1-display-identities (charset)
    "Display each character in CHARSET as the corresponding Latin-1 character.

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

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

Please do NOT add a function make-glyph-code now.
This is not the time for new features.

Re: cannot understand Elisp manual node Glyphs

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> Please do NOT add a function make-glyph-code now.
> This is not the time for new features.

It is not actually a new feature but a plain wrapper for an existing
one.  Anyway, it is getting increasingly hard for developers to
maintain sight of _what_ it is the time to do.

-- 
David Kastrup

Re: cannot understand Elisp manual node Glyphs

[Markus Triska]

David Kastrup <dak@gnu.org> writes:

> one.  Anyway, it is getting increasingly hard for developers to
> maintain sight of _what_ it is the time to do.

It's time to look harder.


2007-02-09  Markus Triska  <markus.triska@gmx.at>

	* cmds.c (Fforward_line, Fbackward_char, Fforward_char): Document
	behaviour for omitted optional arguments

*** cmds.c	21 Jan 2007 05:18:16 +0100	1.99
--- cmds.c	09 Feb 2007 10:03:12 +0100	
***************
*** 57,63 ****
  
  DEFUN ("forward-char", Fforward_char, Sforward_char, 0, 1, "p",
         doc: /* Move point right N characters (left if N is negative).
! On reaching end of buffer, stop and signal error.  */)
       (n)
       Lisp_Object n;
  {
--- 57,64 ----
  
  DEFUN ("forward-char", Fforward_char, Sforward_char, 0, 1, "p",
         doc: /* Move point right N characters (left if N is negative).
! On reaching end of buffer, stop and signal error.  N nil or omitted is
! equivalent to N = 1.  */)
       (n)
       Lisp_Object n;
  {
***************
*** 93,99 ****
  
  DEFUN ("backward-char", Fbackward_char, Sbackward_char, 0, 1, "p",
         doc: /* Move point left N characters (right if N is negative).
! On attempt to pass beginning or end of buffer, stop and signal error.  */)
       (n)
       Lisp_Object n;
  {
--- 94,101 ----
  
  DEFUN ("backward-char", Fbackward_char, Sbackward_char, 0, 1, "p",
         doc: /* Move point left N characters (right if N is negative).
! On attempt to pass beginning or end of buffer, stop and signal error.
! N nil or omitted is equivalent to N = 1.  */)
       (n)
       Lisp_Object n;
  {
***************
*** 113,119 ****
  Returns the count of lines left to move.  If moving forward,
  that is N - number of lines moved; if backward, N + number moved.
  With positive N, a non-empty line at the end counts as one line
!   successfully moved (for the return value).  */)
       (n)
       Lisp_Object n;
  {
--- 115,122 ----
  Returns the count of lines left to move.  If moving forward,
  that is N - number of lines moved; if backward, N + number moved.
  With positive N, a non-empty line at the end counts as one line
! successfully moved (for the return value).  N nil or omitted is
! equivalent to N = 1.  */)
       (n)
       Lisp_Object n;
  {

Re: cannot understand Elisp manual node Glyphs

[Nick Roberts]

 >   DEFUN ("forward-char", Fforward_char, Sforward_char, 0, 1, "p",
 >          doc: /* Move point right N characters (left if N is negative).
 > ! On reaching end of buffer, stop and signal error.  N nil or omitted is
 > ! equivalent to N = 1.  */)

The help buffer says:

(forward-char &optional n)

Omitted optional arguments default to nil but it might be a good idea to say
the default value for N is 1, if this isn't already obvious from its name.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

This change is ok with me.

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

      Anyway, it is getting increasingly hard for developers to
    maintain sight of _what_ it is the time to do.

There is no reason why it should be hard.
Now is the time for fixing bugs, and only fixing bugs.

Re: cannot understand Elisp manual node Glyphs

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

> Please do NOT add a function make-glyph-code now.
> This is not the time for new features.

The initial reason behind this change was to improve _documentation_,
for an _existing_ feature which is definitely non-obvious, and
basically has no clean API (or an API at all).

In fact, I have code which I wrote for Emacs 19 / Emacs 20, which
stopped working in Emacs 21 because the encoding of faces in 
glyph codes changed ...  

IMO, it is a very bad API design to force Lisp code to relying on
internal numeric constants, which have already changed once between
Emacs releases.

AND IT WILL CHANGE AGAIN IN EMACS 23 (using 22 bits instead of 19).

So if _this_ is not the right time for cleaning up this mess, I don't
know when is!!



BTW, the unicode-2 branch seems to have bugs in this area, exactly
because the changes to this encoding at the C-leve are not reflected in
the Lisp code.  My patch would fix those bugs too (with the obvious
changes to the new functions) in Emacs 23 too.  

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.

WDOT ??

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

Re: cannot understand Elisp manual node Glyphs

[Juanma Barranquero]

On 2/9/07, Kim F. Storm <storm@cua.dk> wrote:

> WDOT ??

I think it's not a new feature, it's much cleaner that the current
way, and a needed abstraction.

It's a bit absurd IMO to be making deep changes to the way we support
images, user-wise, and then discuss about adding three functions,
almost one-liners, which improve clarity and documentation for a much
misunderstood feature.

(No, the above is not a cheap shot towards the image thread, just an
obvious example of not-so-trivial changes going on Right Now.)

                    /L/e/k/t/u

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

    It's a bit absurd IMO to be making deep changes to the way we support
    images, user-wise,

That is a matter of fixing a serious problem in a new feature.
Otherwise I would not consider such changes now.

Re: cannot understand Elisp manual node Glyphs

[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

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

    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.

Specifying faces thru glyph codes is kludgy and perhaps obsolete.  I
think it calls for a total redesign, perhaps not before Emacs 23.

It was added at a time when there was no other way to specify faces
for buffer text.  It doesn't seem very useful to me now.  So maybe we
should delete it instead of redesigning it.

What are the purposes for which people want to use it now?

RE: cannot understand Elisp manual node Glyphs

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 1816 bytes --]

> Specifying faces thru glyph codes is kludgy and perhaps obsolete.  I
> think it calls for a total redesign, perhaps not before Emacs 23.
>
> It was added at a time when there was no other way to specify faces
> for buffer text.  It doesn't seem very useful to me now.  So maybe we
> should delete it instead of redesigning it.
>
> What are the purposes for which people want to use it now?

To repeat why I started this thread: I modify a display-table entry for ^L,
to display text like this: "Section (Printable Page)" instead of "^L" or
"\014".

I couldn't figure out how to apply a face to that display-table entry.
Thanks to the explanations in the mailing list, in particular from Kim, I
can now do it, and I now understand the doc better. The doc is not clear in
this regard, IMO.

Can I do the same thing somehow without specifying a face through a glyph
code?

Thanks to Kim's one-line convenience function, my code is clear:

(defun ^L-display-table-entry ()
  "Returns the display-table entry for the Control-l (`^L') character.
A vector determining how a Control-l character is displayed.
Either a vector of characters or nil.  The characters are displayed in
place of the Control-l character.  nil means `^L' is displayed."
  (vconcat (mapcar (lambda (c) (make-glyph-code c '^L-highlight))
                   "          Section (Printable Page)          ")))

;; Proposed Emacs helper function from Kim
(defun make-glyph-code (char &optional face)
  "Return a glyph code representing char CHAR with face FACE."
  (if face (logior char (lsh (face-id face) 19)) char))

(aset standard-display-table ?\014 (^L-display-table-entry))

A screenshot is attached. An explanation and the full code are here:
http://www.emacswiki.org/cgi-bin/wiki/PrettyControlL,
http://www.emacswiki.org/cgi-bin/wiki/pp-c-l.el

[-- Attachment #2: drew-emacs-pretty-control-l.png --]
[-- Type: image/png, Size: 17145 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

We could replace the display table feature with a feature to just
specify a face for highlighting a character code.  Or, if it is
important to be able to replace it with a different character code,
we could use (CHAR . FACE).

We can decide this later.

Re: cannot understand Elisp manual node Glyphs

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
> Or, if it is important to be able to replace it with a different
> character code, we could use (CHAR . FACE).

That would be nice.

-Miles
-- 
"Suppose He doesn't give a shit?  Suppose there is a God but He
just doesn't give a shit?"  [George Carlin]

Re: cannot understand Elisp manual node Glyphs

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

> We could replace the display table feature with a feature to just
> specify a face for highlighting a character code.  Or, if it is
> important to be able to replace it with a different character code,
> we could use (CHAR . FACE).

Isn't that exactly what the display table is all about (with the
addition of the "extra slots").

And yes, (CHAR . FACE) is exactly what I had in mind for the Emacs 23
implementation of make-glyph-code, glyph-char, and glyph-face.


The exact reason I would add make-glyph-code, glyph-face and
glyph-char NOW is to allow us to cleanly make that change in Emacs 23
without breaking Emacs 22 complient code (that uses those functions).

> We can decide this later.

I STRONGLY disagree.

To me, it makes no sense to keep the current description of glyph
codes in Emacs 22 when we _KNOW_ that code based on the current text
will _NOT_ work in Emacs 23.

Replacing the text with the text I wrote would give a clean transition
from Emacs 22 to Emacs 23.  

We should note in Emacs 22 NEWS that to generate glyph codes, user
should use the new functions, and that the old method of using numeric
glyph codes is obsolete, and will be removed in Emacs 23.

I honestly don't see why anyone can disagree with this!

And I don't see what _harm_ it can do.

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

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

    To me, it makes no sense to keep the current description of glyph
    codes in Emacs 22 when we _KNOW_ that code based on the current text
    will _NOT_ work in Emacs 23.

    Replacing the text with the text I wrote would give a clean transition

Ok.  Please make the change.

Re: cannot understand Elisp manual node Glyphs

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     To me, it makes no sense to keep the current description of glyph
>     codes in Emacs 22 when we _KNOW_ that code based on the current text
>     will _NOT_ work in Emacs 23.
>
>     Replacing the text with the text I wrote would give a clean transition
>
> Ok.  Please make the change.

Done.

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

Re: cannot understand Elisp manual node Glyphs

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Fri, 09 Feb 2007 18:49:09 -0500
> Cc: emacs-devel@gnu.org, drew.adams@oracle.com, miles@gnu.org
> 
> Specifying faces thru glyph codes is kludgy and perhaps obsolete.  I
> think it calls for a total redesign, perhaps not before Emacs 23.

Agreed.

> It was added at a time when there was no other way to specify faces
> for buffer text.  It doesn't seem very useful to me now.  So maybe we
> should delete it instead of redesigning it.

I think we shouldn't consider deleting it now, for the same reasons we
shouldn't consider redesigning it: we should move aside anything
except bad bugs and remaining copyright problems, anything that might
delay the release for no good reason!

Deleting such a veteran, if kludgy, feature so close to the release
runs a high risk of producing additional bugs, complaints, long
discussions, etc. etc.  Why risk that now?

> What are the purposes for which people want to use it now?

Emacs itself uses that, see dos-unsupported-char-glyph.  (And yes, the
MS-DOS port is still supported in Emacs 22.)  Am I supposed to rewrite
the variable, its doc string, and the associated manual sections, so
close to the release?  To what end??

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

    > It was added at a time when there was no other way to specify faces
    > for buffer text.  It doesn't seem very useful to me now.  So maybe we
    > should delete it instead of redesigning it.

    I think we shouldn't consider deleting it now,

I agree.  I meant later.

Re: cannot understand Elisp manual node Glyphs

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
> Specifying faces thru glyph codes is kludgy and perhaps obsolete.  I
> think it calls for a total redesign, perhaps not before Emacs 23.
>
> What are the purposes for which people want to use it now?

It works in display-table entries; I'm not aware of any other way to do
the same thing.

-Miles
-- 
A zen-buddhist walked into a pizza shop and
said, "Make me one with everything."

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

    > What are the purposes for which people want to use it now?

    It works in display-table entries; I'm not aware of any other way to do
    the same thing.

My question is, for what specific practical purposes do people want to use
this display-table feature?

RE: cannot understand Elisp manual node Glyphs

[Drew Adams]

>     > What are the purposes for which people want to use it now?
>
>     It works in display-table entries; I'm not aware of any other
>     way to do the same thing.
>
> My question is, for what specific practical purposes do people
> want to use this display-table feature?

Did you not get my mail with the screenshot, URL, and explanation of why I
started this thread? Was that "specific practical purpose" not convincing?

The same use case applies to substituting highlighted display-table entries
to indicate non-breaking spaces, TABs, etc. (though there are alternative
ways to do that).

I asked this question - what's the answer?

>  Can I do the same thing somehow without specifying a face
>  through a glyph code?

If the answer is "no", then isn't that a good reason for the feature?

Re: cannot understand Elisp manual node Glyphs

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
>     It works in display-table entries; I'm not aware of any other way to do
>     the same thing.
>
> My question is, for what specific practical purposes do people want to use
> this display-table feature?

I use it for my `visible-whitespace-mode' package.  It uses the
display-table to cause whitespace to appear as graphic characters, and
puts faces on them because they should appear distinct from normal
buffer text.

-Miles

-- 
"An atheist doesn't have to be someone who thinks he has a proof that there
can't be a god.  He only has to be someone who believes that the evidence
on the God question is at a similar level to the evidence on the werewolf
question."  [John McCarthy]

Re: cannot understand Elisp manual node Glyphs

[Richard Stallman]

    I use it for my `visible-whitespace-mode' package.  It uses the
    display-table to cause whitespace to appear as graphic characters, and
    puts faces on them because they should appear distinct from normal
    buffer text.

I gather you remap these whitespace characters to other characters
as well as specifying a face.  Ok, we should keep that capability.

Re: cannot understand Elisp manual node Glyphs

[Stuart D. Herring]

> So if _this_ is not the right time for cleaning up this mess, I don't
> know when is!!
> [...]
> WDOT ??

Certainly; I would really class the existing interface as a bug, even if
its implementation is flawless.  And the resulting bugs in code on which
the standard got switched would be gruesome to see (literally).

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

Re: cannot understand Elisp manual node Glyphs

[Stefan Monnier]

>> Good idea, but why not just call it "make-glyph"...?
> Because Xemacs already has a function named make-glyph with
          ^^^^^^
          XEmacs  ;-)
> different semantics.

> But maybe we don't need to care about that?

I think we should.


        Stefan

Re: cannot understand Elisp manual node Glyphs

[Juanma Barranquero]

On 2/8/07, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> >> Good idea, but why not just call it "make-glyph"...?
> > Because Xemacs already has a function named make-glyph with
>           ^^^^^^
>           XEmacs  ;-)

I've had to restrain myself from sending him a patch :)

                    /L/e/k/t/u

Re: cannot understand Elisp manual node Glyphs

[Stephen J. Turnbull]

Miles Bader writes:

 > Good idea, but why not just call it "make-glyph"...?

FWIW, that has wildly different semantics in XEmacs.