--- a/man/lispref/display.texi	Mon Aug 13 11:17:10 2007 +0200
+++ b/man/lispref/display.texi	Mon Aug 13 11:18:11 2007 +0200
@@ -996,6 +996,71 @@
 to a ``glyph table'' and such.  Note that ``glyph'' has a different
 meaning in XEmacs.)
 
+@defvar current-display-table
+
+The display table currently in use.  This is a specifier.
+
+Display tables are used to control how characters are displayed.  Each
+time that redisplay processes a character, it is looked up in all the
+display tables that apply (obtained by calling @code{specifier-instance}
+on @code{current-display-table} and any overriding display tables
+specified in currently active faces).  The first entry found that
+matches the character determines how the character is displayed.  If
+there is no matching entry, the default display method is
+used. (Non-control characters are displayed as themselves and control
+characters are displayed according to the buffer-local variable
+@code{ctl-arrow}.  Control characters are further affected by
+@code{control-arrow-glyph} and @code{octal-escape-glyph}.)
+
+Each instantiator in this specifier and the display-table specifiers
+in faces is a display table or a list of such tables.  If a list, each
+table will be searched in turn for an entry matching a particular
+character.  Each display table is one of
+
+@itemize @bullet
+@item
+A vector, specifying values for characters starting at 0.
+@item
+A char table, either of type @code{char} or @code{generic}.
+@item
+A range table.
+@end itemize
+
+Each entry in a display table should be one of
+
+@itemize @bullet
+@item
+nil (this entry is ignored and the search continues).
+@item
+A character (use this character; if it happens to be the same as
+the original character, default processing happens, otherwise
+redisplay attempts to display this character directly;
+#### At some point recursive display-table lookup will be
+implemented).
+@item
+A string (display each character in the string directly;
+#### At some point recursive display-table lookup will be
+implemented).
+@item
+A glyph (display the glyph;
+#### At some point recursive display-table lookup will be
+implemented when a string glyph is being processed).
+@item
+A cons of the form (format "@var{string}") where @var{string} is a
+printf-like spec used to process the character. #### Unfortunately no
+formatting directives other than %% are implemented.
+@item
+A vector (each element of the vector is processed recursively;
+in such a case, nil elements in the vector are simply ignored).
+
+#### At some point in the near future, display tables are likely to
+be expanded to include other features, such as referencing characters
+in particular fonts and allowing the character search to continue
+all the way up the chain of specifier instantiators.  These features
+are necessary to properly display Unicode characters.
+@end itemize
+@end defvar
+
   Individual faces can also specify an overriding display table;
 this is set using @code{set-face-display-table}.  @xref{Faces}.