elisp manual, page "Display Tables" is opaque

[Mackenzie, Alan]

Hi, Emacs!

[cc's to acm@muc.de would be appreciated.  Thanks!]

Emacs 21.3 on MS-Windows.

I'm trying to set up a display table (or whatever), so that a carriage
return,
instead of being displayed as "^M", gets displayed as "<CR>".  This
should be
simple - but I've been struggling with the documentation for ~2 hours so
far.

This documentation suffers from "pronounitis" - using terms like "this
widget"
when it is unclear which widget is meant, or even what is meant by
"widget")
and contains too few examples.

So far, I've tried this:

    (defvar explicit-table (make-display-table))
    (defun explicit-display ()
      (aset explicit-table ?\r (vector ?< ?C ?R ?>)))

and this:

    (defvar explicit-table (make-display-table))
    (defun explicit-display ()
      (aset explicit-table ?\r (vector (create-glyph "<CR>"))))

each time attempting to apply the new table with

    (set-window-display-table (selected-window) 'explicit-table)    
    
.  Both of these tries replaced "^M" with an empty square glyph.  :-(

########################################################################
#

Here is an analysis of what is wrong with the info pages.  I don't
currently
have convenient access to the CVS elisp, but a quick glance through the
CVS
display.texi shows it has in essence not been fixed.

Page "Display Table format"

        The ordinary elements of the display table are indexed by
character
     codes; the element at index C says how to display the character
code C.
     The value should be `nil' or a vector of glyph values (*note
     Glyphs::).  If an element is `nil', it says to display that
character
     according to the usual display conventions (*note Usual Display::).

Nowhere is it defined what a "glyph VALUE" is.  It is not immediately
clear
whether "The value" means the value of the entire display table or one
of its
elements, though some mental analysis shows it to be the latter.



Page "Glyphs"

     - Variable: glyph-table
         The value of this variable is the current glyph table.  It
should
         be a vector; the Gth element defines glyph code G.  If the
value
         is `nil' instead of a vector, then all glyphs are simple (see
         below).  The glyph table is not used on windowed displays.

What is a "glyph table", exactly?  What is "code G"?  Is glyph code 65
"A"?
"If THE value is `nil'" ....  Is this the value of `glyph-table', or the
value
of one of its elements?


    STRING
         Send the characters in STRING to the terminal to output this
         glyph.  This alternative is available on character terminals,
but
         not under a window system.

Alternative to what?  Could it be that "STRING" is an old mechanism
which has
been superseded by one which works on both terminals and graphical
screens?


    INTEGER
         Define this glyph code as an alias for glyph code INTEGER.  You
         can use an alias to specify a face code for the glyph; see
below.

WhaaaaT?  What is the significance of "glyph code INTEGER"?  Why on
earth
would I want to define an alias, and how would I use this alias?  WTF is
a
"face code"?


    `nil'
         This glyph is simple.  The glyph code mod 524288 is the
character
         to output, and the glyph code divided by 524288 specifies the
face
         number (*note Face Functions::) to use while outputting it.
         (524288 is 2**19.)  *Note Faces::.

'THE glyph code" - WHAT glyph code?  isn't the glyph code here `nil'?

########################################################################
#

So, how can I make a carriage return display as "<CR>"?  Is it even
possible?
If so, why isn't something like this in the documentation as an example?

-- 
Alan Mackenzie,
Harman Becker, Ittersbach, Germany.


*******************************************
Diese E-Mail enthaelt vertrauliche und/oder rechtlich geschuetzte 
Informationen. Wenn Sie nicht der richtige Adressat sind oder diese E-Mail 
irrtuemlich erhalten haben, informieren Sie bitte sofort den Absender und 
loeschen Sie diese Mail. Das unerlaubte Kopieren sowie die unbefugte Weitergabe 
dieser Mail ist nicht gestattet.
 
This e-mail may contain confidential and/or privileged information. If you are 
not the intended recipient (or have received this e-mail in error) please 
notify the sender immediately and delete this e-mail. Any unauthorized copying, 
disclosure or distribution of the contents in this e-mail is strictly forbidden.
*******************************************