Updates for Display chapter of Lisp manual.
* doc/lispref/display.texi (Image Formats): Add imagemagick type. (Image Descriptors): Mention how they are used. (ImageMagick Images): Clarify role of imagemagick-register-types. (Character Display): Don't mention glyph tables. (Display Tables): Use make-glyph-code in example. (Glyphs): Avoid "simple glyph code" terminology. Note that glyph tables are semi-obsolete. De-document create-glyph. (Glyphless Chars): Note that display tables override this. (Bidirectional Display): Copyedits. Introduce "bidirectional reordering" terminology, and use it. * doc/emacs/files.texi (File Conveniences): Clarify Imagemagick discussion. * lisp/image.el (imagemagick-types-inhibit) (imagemagick-register-types): Doc fix.
This commit is contained in:
Chong Yidong
parent
dc1783452e
commit
5319014e4f
7 changed files with 383 additions and 358 deletions
|
|
@ -191,7 +191,7 @@ compile.texi cyd
|
|||
control.texi cyd
|
||||
customize.texi cyd
|
||||
debugging.texi cyd
|
||||
display.texi
|
||||
display.texi cyd
|
||||
edebug.texi
|
||||
elisp.texi
|
||||
errors.texi rgm
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
2012-03-30 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* files.texi (File Conveniences): Clarify Imagemagick discussion.
|
||||
|
||||
2012-03-22 Glenn Morris <rgm@gnu.org>
|
||||
|
||||
* dired.texi (Operating on Files): Fix dired-recursive-copies default.
|
||||
|
|
|
|||
|
|
@ -1911,27 +1911,35 @@ point. Partial Completion mode offers other features extending
|
|||
@cindex images, viewing
|
||||
@cindex image animation
|
||||
@cindex animated images
|
||||
Visiting image files automatically selects Image mode. This major
|
||||
mode allows you to toggle between displaying the file as an image in
|
||||
the Emacs buffer, and displaying its underlying text representation,
|
||||
using the command @kbd{C-c C-c} (@code{image-toggle-display}). This
|
||||
works only when Emacs can display the specific image type@footnote{If
|
||||
your Emacs was compiled with ImageMagick support, then after using
|
||||
@code{imagemagick-register-types}, you can view in Image mode any
|
||||
image type that ImageMagick supports; @pxref{ImageMagick Images,,,
|
||||
elisp, The Emacs Lisp Reference Manual}}. If the displayed image is wider
|
||||
Visiting image files automatically selects Image mode. In this
|
||||
major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display})
|
||||
to toggle between displaying the file as an image in the Emacs buffer,
|
||||
and displaying its underlying text (or raw byte) representation.
|
||||
Displaying the file as an image works only if Emacs is compiled with
|
||||
support for displaying such images. If the displayed image is wider
|
||||
or taller than the frame, the usual point motion keys (@kbd{C-f},
|
||||
@kbd{C-p}, and so forth) cause different parts of the image to be
|
||||
displayed. If the image can be animated, then the command @kbd{RET}
|
||||
(@code{image-toggle-animation}), will start (or stop) animating it.
|
||||
displayed. If the image can be animated, the command @kbd{RET}
|
||||
(@code{image-toggle-animation}) starts or stops the animation.
|
||||
Animation plays once, unless the option @code{image-animate-loop} is
|
||||
non-@code{nil}. Currently, Emacs only supports animated GIF files
|
||||
(@pxref{Animated Images,,, elisp, The Emacs Lisp Reference Manual}).
|
||||
non-@code{nil}. Currently, Emacs only supports animation in GIF
|
||||
files.
|
||||
|
||||
@cindex ImageMagick support
|
||||
If your Emacs was compiled with ImageMagick support, it is possible
|
||||
to view a much wider variety of image types in Image mode, by
|
||||
rendering the images via ImageMagick. However, this feature is
|
||||
currently disabled by default. To enable it, add the following line
|
||||
to your init file:
|
||||
|
||||
@example
|
||||
(imagemagick-register-types)
|
||||
@end example
|
||||
|
||||
@findex thumbs-mode
|
||||
@findex mode, thumbs
|
||||
See also the Image-Dired package (@pxref{Image-Dired}) for viewing
|
||||
images as thumbnails.
|
||||
The Image-Dired package can also be used to view images as
|
||||
thumbnails. @xref{Image-Dired}.
|
||||
|
||||
@node Filesets
|
||||
@section Filesets
|
||||
|
|
|
|||
|
|
@ -1,3 +1,16 @@
|
|||
2012-03-30 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* display.texi (Image Formats): Add imagemagick type.
|
||||
(Image Descriptors): Mention how they are used.
|
||||
(ImageMagick Images): Clarify role of imagemagick-register-types.
|
||||
(Character Display): Don't mention glyph tables.
|
||||
(Display Tables): Use make-glyph-code in example.
|
||||
(Glyphs): Avoid "simple glyph code" terminology. Note that glyph
|
||||
tables are semi-obsolete. De-document create-glyph.
|
||||
(Glyphless Chars): Note that display tables override this.
|
||||
(Bidirectional Display): Copyedits. Introduce "bidirectional
|
||||
reordering" terminology, and use it.
|
||||
|
||||
2012-03-30 Glenn Morris <rgm@gnu.org>
|
||||
|
||||
* edebug.texi (Jumping): Give name of `i' binding.
|
||||
|
|
|
|||
|
|
@ -1402,7 +1402,7 @@ of them:
|
|||
@table @code
|
||||
@item priority
|
||||
@kindex priority @r{(overlay property)}
|
||||
This property's value (which should be a nonnegative integer number)
|
||||
This property's value (which should be a non-negative integer number)
|
||||
determines the priority of the overlay. No priority, or @code{nil},
|
||||
means zero.
|
||||
|
||||
|
|
@ -1557,7 +1557,7 @@ sense---only on the screen.
|
|||
This property specifies a display spec to prepend to each
|
||||
non-continuation line at display-time. @xref{Truncation}.
|
||||
|
||||
@itemx wrap-prefix
|
||||
@item wrap-prefix
|
||||
This property specifies a display spec to prepend to each continuation
|
||||
line at display-time. @xref{Truncation}.
|
||||
|
||||
|
|
@ -4118,95 +4118,103 @@ displayed (@pxref{Display Feature Testing}).
|
|||
@cindex image formats
|
||||
@cindex image types
|
||||
|
||||
Emacs can display a number of different image formats; some of them
|
||||
are supported only if particular support libraries are installed on
|
||||
your machine. In some environments, Emacs can load support libraries
|
||||
on demand; if so, the variable @code{dynamic-library-alist}
|
||||
(@pxref{Dynamic Libraries}) can be used to modify the set of known
|
||||
names for these dynamic libraries (though it is not possible to add
|
||||
new image formats). Note that image types @code{pbm} and @code{xbm}
|
||||
do not depend on external libraries and are always available in Emacs.
|
||||
Emacs can display a number of different image formats. Some of
|
||||
these image formats are supported only if particular support libraries
|
||||
are installed. On some platforms, Emacs can load support libraries on
|
||||
demand; if so, the variable @code{dynamic-library-alist} can be used
|
||||
to modify the set of known names for these dynamic libraries.
|
||||
@xref{Dynamic Libraries}.
|
||||
|
||||
The supported image formats (and the necessary library files)
|
||||
include XBM, XPM (@code{libXpm} and @code{libz}), GIF (@code{libgif}
|
||||
or @code{libungif}), PostScript, PBM, JPEG (@code{libjpeg}), TIFF
|
||||
Supported image formats (and the required support libraries) include
|
||||
PBM and XBM (which do not depend on support libraries and are always
|
||||
available), XPM (@code{libXpm}), GIF (@code{libgif} or
|
||||
@code{libungif}), PostScript (@code{gs}), JPEG (@code{libjpeg}), TIFF
|
||||
(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}).
|
||||
|
||||
You specify one of these formats with an image type symbol. The image
|
||||
type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
|
||||
@code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}.
|
||||
Each of these image formats is associated with an @dfn{image type
|
||||
symbol}. The symbols for the above formats are, respectively,
|
||||
@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
|
||||
@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}.
|
||||
|
||||
Furthermore, if you build Emacs with ImageMagick
|
||||
(@code{libMagickWand}) support, Emacs can display any image format
|
||||
that ImageMagick can. @xref{ImageMagick Images}. All images
|
||||
displayed via ImageMagick have type symbol @code{imagemagick}.
|
||||
|
||||
@defvar image-types
|
||||
This variable contains a list of those image type symbols that are
|
||||
potentially supported in the current configuration.
|
||||
@emph{Potentially} here means that Emacs knows about the image types,
|
||||
not necessarily that they can be loaded (they could depend on
|
||||
unavailable dynamic libraries, for example).
|
||||
This variable contains a list of type symbols for image formats which
|
||||
are potentially supported in the current configuration.
|
||||
|
||||
To know which image types are really available, use
|
||||
@code{image-type-available-p}.
|
||||
``Potentially'' means that Emacs knows about the image types, not
|
||||
necessarily that they can be used (for example, they could depend on
|
||||
unavailable dynamic libraries). To know which image types are really
|
||||
available, use @code{image-type-available-p}.
|
||||
@end defvar
|
||||
|
||||
@defun image-type-available-p type
|
||||
This function returns non-@code{nil} if image type @var{type} is
|
||||
available, i.e., if images of this type can be loaded and displayed in
|
||||
Emacs. @var{type} should be one of the types contained in
|
||||
@code{image-types}.
|
||||
This function returns non-@code{nil} if images of type @var{type} can
|
||||
be loaded and displayed. @var{type} must be an image type symbol.
|
||||
|
||||
For image types whose support libraries are statically linked, this
|
||||
function always returns @code{t}; for other image types, it returns
|
||||
@code{t} if the dynamic library could be loaded, @code{nil} otherwise.
|
||||
function always returns @code{t}. For image types whose support
|
||||
libraries are dynamically loaded, it returns @code{t} if the library
|
||||
could be loaded and @code{nil} otherwise.
|
||||
@end defun
|
||||
|
||||
@node Image Descriptors
|
||||
@subsection Image Descriptors
|
||||
@cindex image descriptor
|
||||
|
||||
An image description is a list of the form @code{(image . @var{props})},
|
||||
where @var{props} is a property list containing alternating keyword
|
||||
symbols (symbols whose names start with a colon) and their values.
|
||||
You can use any Lisp object as a property, but the only properties
|
||||
that have any special meaning are certain symbols, all of them keywords.
|
||||
An @dfn{image descriptor} is a list which specifies the underlying
|
||||
data for an image, and how to display it. It is typically used as the
|
||||
value of a @code{display} overlay or text property (@pxref{Other
|
||||
Display Specs}); but @xref{Showing Images}, for convenient helper
|
||||
functions to insert images into buffers.
|
||||
|
||||
Every image descriptor must contain the property @code{:type
|
||||
@var{type}} to specify the format of the image. The value of @var{type}
|
||||
should be an image type symbol; for example, @code{xpm} for an image in
|
||||
XPM format.
|
||||
Each image descriptor has the form @code{(image . @var{props})},
|
||||
where @var{props} is a property list of alternating keyword symbols
|
||||
and values, including at least the pair @code{:type @var{TYPE}} which
|
||||
specifies the image type.
|
||||
|
||||
Here is a list of other properties that are meaningful for all image
|
||||
types:
|
||||
The following is a list of properties that are meaningful for all
|
||||
image types (there are also properties which are meaningful only for
|
||||
certain image types, as documented in the following subsections):
|
||||
|
||||
@table @code
|
||||
@item :type @var{type}
|
||||
The image type.
|
||||
@ifnottex
|
||||
@xref{Image Formats}.
|
||||
@end ifnottex
|
||||
Every image descriptor must include this property.
|
||||
|
||||
@item :file @var{file}
|
||||
The @code{:file} property says to load the image from file
|
||||
@var{file}. If @var{file} is not an absolute file name, it is expanded
|
||||
in @code{data-directory}.
|
||||
This says to load the image from file @var{file}. If @var{file} is
|
||||
not an absolute file name, it is expanded in @code{data-directory}.
|
||||
|
||||
@item :data @var{data}
|
||||
The @code{:data} property says the actual contents of the image.
|
||||
Each image must use either @code{:data} or @code{:file}, but not both.
|
||||
For most image types, the value of the @code{:data} property should be a
|
||||
string containing the image data; we recommend using a unibyte string.
|
||||
This specifies the raw image data. Each image descriptor must have
|
||||
either @code{:data} or @code{:file}, but not both.
|
||||
|
||||
Before using @code{:data}, look for further information in the section
|
||||
below describing the specific image format. For some image types,
|
||||
@code{:data} may not be supported; for some, it allows other data types;
|
||||
for some, @code{:data} alone is not enough, so you need to use other
|
||||
image properties along with @code{:data}.
|
||||
For most image types, the value of a @code{:data} property should be a
|
||||
string containing the image data. Some image types do not support
|
||||
@code{:data}; for some others, @code{:data} alone is not enough, so
|
||||
you need to use other image properties along with @code{:data}. See
|
||||
the following subsections for details.
|
||||
|
||||
@item :margin @var{margin}
|
||||
The @code{:margin} property specifies how many pixels to add as an
|
||||
extra margin around the image. The value, @var{margin}, must be a
|
||||
non-negative number, or a pair @code{(@var{x} . @var{y})} of such
|
||||
numbers. If it is a pair, @var{x} specifies how many pixels to add
|
||||
horizontally, and @var{y} specifies how many pixels to add vertically.
|
||||
If @code{:margin} is not specified, the default is zero.
|
||||
This specifies how many pixels to add as an extra margin around the
|
||||
image. The value, @var{margin}, must be a non-negative number, or a
|
||||
pair @code{(@var{x} . @var{y})} of such numbers. If it is a pair,
|
||||
@var{x} specifies how many pixels to add horizontally, and @var{y}
|
||||
specifies how many pixels to add vertically. If @code{:margin} is not
|
||||
specified, the default is zero.
|
||||
|
||||
@item :ascent @var{ascent}
|
||||
The @code{:ascent} property specifies the amount of the image's
|
||||
height to use for its ascent---that is, the part above the baseline.
|
||||
The value, @var{ascent}, must be a number in the range 0 to 100, or
|
||||
the symbol @code{center}.
|
||||
This specifies the amount of the image's height to use for its
|
||||
ascent---that is, the part above the baseline. The value,
|
||||
@var{ascent}, must be a number in the range 0 to 100, or the symbol
|
||||
@code{center}.
|
||||
|
||||
If @var{ascent} is a number, that percentage of the image's height is
|
||||
used for its ascent.
|
||||
|
|
@ -4219,16 +4227,15 @@ properties and overlays that apply to the image.
|
|||
If this property is omitted, it defaults to 50.
|
||||
|
||||
@item :relief @var{relief}
|
||||
The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
|
||||
around the image. The value, @var{relief}, specifies the width of the
|
||||
shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
|
||||
so that the image appears as a pressed button; otherwise, it appears as
|
||||
an unpressed button.
|
||||
This adds a shadow rectangle around the image. The value,
|
||||
@var{relief}, specifies the width of the shadow lines, in pixels. If
|
||||
@var{relief} is negative, shadows are drawn so that the image appears
|
||||
as a pressed button; otherwise, it appears as an unpressed button.
|
||||
|
||||
@item :conversion @var{algorithm}
|
||||
The @code{:conversion} property, if non-@code{nil}, specifies a
|
||||
conversion algorithm that should be applied to the image before it is
|
||||
displayed; the value, @var{algorithm}, specifies which algorithm.
|
||||
This specifies a conversion algorithm that should be applied to the
|
||||
image before it is displayed; the value, @var{algorithm}, specifies
|
||||
which algorithm.
|
||||
|
||||
@table @code
|
||||
@item laplace
|
||||
|
|
@ -4498,30 +4505,41 @@ specifying the bounding box of the PostScript image, analogous to the
|
|||
@cindex ImageMagick images
|
||||
@cindex images, support for more formats
|
||||
|
||||
If you build Emacs with ImageMagick (@url{http://www.imagemagick.org})
|
||||
support, you can use the ImageMagick library to load many image formats.
|
||||
If you build Emacs with ImageMagick support, you can use the
|
||||
ImageMagick library to load many image formats. The image type symbol
|
||||
for images loaded via ImageMagick is @code{imagemagick}, regardless of
|
||||
the actual underlying image format.
|
||||
|
||||
@findex imagemagick-types
|
||||
@findex imagemagick-register-types
|
||||
The function @code{imagemagick-types} returns a list of image file
|
||||
extensions that your installation of ImageMagick supports. To enable
|
||||
support, you must call the function @code{imagemagick-register-types}.
|
||||
This enables Emacs to visit these file types in @code{image-mode}
|
||||
(@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}).
|
||||
If your Emacs was not compiled with ImageMagick support, then
|
||||
@code{imagemagick-types} will be undefined and
|
||||
@code{imagemagick-register-types} will do nothing.
|
||||
@defun imagemagick-types
|
||||
This function returns a list of image file extensions supported by the
|
||||
current ImageMagick installation.
|
||||
@end defun
|
||||
|
||||
By default, Emacs does not use ImageMagick to display images in
|
||||
Image mode, e.g.@: when visiting such files with @kbd{C-x C-f}. This
|
||||
feature is enabled by calling @code{imagemagick-register-types}.
|
||||
|
||||
@defun imagemagick-register-types
|
||||
This function enables using Image mode to visit image files supported
|
||||
by ImageMagick. @xref{File Conveniences,,, emacs, The GNU Emacs
|
||||
Manual}. It also causes @code{create-image} and other helper
|
||||
functions to associate such file names with the @code{imagemagick}
|
||||
image type (@pxref{Defining Images}).
|
||||
|
||||
All image file extensions supported by ImageMagick are registered,
|
||||
except those specified in @code{imagemagick-types-inhibit}. If Emacs
|
||||
was not compiled with ImageMagick support, this function does nothing.
|
||||
@end defun
|
||||
|
||||
@defopt imagemagick-types-inhibit
|
||||
This variable specifies a list of image types that should @emph{not}
|
||||
be registered by @code{imagemagick-register-types}. Each entry in
|
||||
this list should be one of the symbols returned by
|
||||
@code{imagemagick-types}. The default value lists several file types
|
||||
that are considered ``images'' by ImageMagick, but which should not be
|
||||
considered as images by Emacs, including C files and HTML files.
|
||||
@end defopt
|
||||
|
||||
@vindex imagemagick-types-inhibit
|
||||
The variable @code{imagemagick-types-inhibit} specifies a list of
|
||||
image types that you do @emph{not} want ImageMagick to handle. It is
|
||||
a list of symbols, each of which has the same name as one of the
|
||||
format tags used internally by ImageMagick (i.e., as
|
||||
@code{imagemagick-types} returns). ImageMagick has a very broad
|
||||
definition of what an image is, for example it includes such file
|
||||
types as C files and HTML files. It is not appropriate to treat these
|
||||
as images in Emacs. You can add any other ImageMagick type that you
|
||||
wish to this list.
|
||||
@ignore
|
||||
@c I don't know what this means. I suspect it means eg loading jpg
|
||||
@c images via libjpeg or ImageMagick. But it doesn't work.
|
||||
|
|
@ -4538,17 +4556,9 @@ loaders).
|
|||
For example, if you never want to use the ImageMagick loader to view
|
||||
JPEG files, add @code{JPG} to this list.
|
||||
@end ignore
|
||||
Note that ImageMagick often distinguishes between several different
|
||||
types of a particular format (e.g., @code{JPG}, @code{JPEG},
|
||||
@code{PJPEG}, etc.), and you may need to add all versions to this
|
||||
list.
|
||||
|
||||
@c Not sure this should even be in the manual at all.
|
||||
@vindex imagemagick-render-type
|
||||
If you wish to experiment with the performance of the ImageMagick
|
||||
loader, see the variable @code{imagemagick-render-type}.
|
||||
|
||||
Images loaded with ImageMagick support a few new display specifications:
|
||||
Images loaded with ImageMagick support the following additional
|
||||
image descriptor properties:
|
||||
|
||||
@table @code
|
||||
@item :width, :height
|
||||
|
|
@ -4568,7 +4578,6 @@ such as DJVM. You can use the @code{image-metadata} function to
|
|||
retrieve the total number of images in an image bundle.
|
||||
@end table
|
||||
|
||||
|
||||
@node Other Image Types
|
||||
@subsection Other Image Types
|
||||
@cindex PBM
|
||||
|
|
@ -4767,10 +4776,10 @@ This function inserts @var{image} in the current buffer at point, like
|
|||
@code{insert-image}, but splits the image into @var{rows}x@var{cols}
|
||||
equally sized slices.
|
||||
|
||||
If an image is inserted ``sliced'', then the Emacs display engine will
|
||||
treat each slice as a separate image, and allow more intuitive
|
||||
scrolling up/down, instead of jumping up/down the entire image when
|
||||
paging through a buffer that displays (large) images.
|
||||
If an image is inserted ``sliced'', Emacs displays each slice as a
|
||||
separate image, and allow more intuitive scrolling up/down, instead of
|
||||
jumping up/down the entire image when paging through a buffer that
|
||||
displays (large) images.
|
||||
@end defun
|
||||
|
||||
@defun put-image image pos &optional string area
|
||||
|
|
@ -5624,9 +5633,6 @@ Here is an example of calling this function explicitly.
|
|||
@smallexample
|
||||
@group
|
||||
(defun interactive-blink-matching-open ()
|
||||
@c Do not break this line! -- rms.
|
||||
@c The first line of a doc string
|
||||
@c must stand alone.
|
||||
"Indicate momentarily the start of sexp before point."
|
||||
(interactive)
|
||||
@end group
|
||||
|
|
@ -5642,23 +5648,19 @@ Here is an example of calling this function explicitly.
|
|||
@node Character Display
|
||||
@section Character Display
|
||||
|
||||
@cindex glyph
|
||||
This section describes how characters are actually displayed by Emacs.
|
||||
Typically, a character is displayed as a @dfn{glyph} (a graphical
|
||||
symbol which occupies one character position on the screen), whose
|
||||
appearance corresponds to the character itself. For example, the
|
||||
character @samp{a} (character code 97) is displayed as @samp{a}. Some
|
||||
characters, however, are displayed specially. For example, the
|
||||
This section describes how characters are actually displayed by
|
||||
Emacs. Typically, a character is displayed as a @dfn{glyph} (a
|
||||
graphical symbol which occupies one character position on the screen),
|
||||
whose appearance corresponds to the character itself. For example,
|
||||
the character @samp{a} (character code 97) is displayed as @samp{a}.
|
||||
Some characters, however, are displayed specially. For example, the
|
||||
formfeed character (character code 12) is usually displayed as a
|
||||
sequence of two glyphs, @samp{^L}, while the newline character
|
||||
(character code 10) starts a new screen line.
|
||||
|
||||
You can modify how each character is displayed by defining a
|
||||
@dfn{display table}, which maps each character code into a sequence of
|
||||
glyphs. @xref{Display Tables}. A related feature, called the
|
||||
@dfn{glyph table}, allows you to control how each character is
|
||||
displayed on a text terminal. @xref{Glyphs}.
|
||||
|
||||
glyphs. @xref{Display Tables}.
|
||||
|
||||
@menu
|
||||
* Usual Display:: The usual conventions for displaying characters.
|
||||
|
|
@ -5671,8 +5673,8 @@ displayed on a text terminal. @xref{Glyphs}.
|
|||
@node Usual Display
|
||||
@subsection Usual Display Conventions
|
||||
|
||||
Here are the usual conventions for display each character code (in
|
||||
the absence of a display table, which can override these
|
||||
Here are the conventions for displaying each character code (in the
|
||||
absence of a display table, which can override these
|
||||
@iftex
|
||||
conventions).
|
||||
@end iftex
|
||||
|
|
@ -5685,8 +5687,7 @@ conventions; @pxref{Display Tables}).
|
|||
@item
|
||||
The @dfn{printable @acronym{ASCII} characters}, character codes 32
|
||||
through 126 (consisting of numerals, English letters, and symbols like
|
||||
@samp{#}) are displayed literally, i.e.@: they map onto glyph codes 32
|
||||
through 126.
|
||||
@samp{#}) are displayed literally.
|
||||
|
||||
@item
|
||||
The tab character (character code 9) displays as whitespace stretching
|
||||
|
|
@ -5695,8 +5696,8 @@ Emacs Manual}. The variable @code{tab-width} controls the number of
|
|||
spaces per tab stop (see below).
|
||||
|
||||
@item
|
||||
The newline character (character code 10) has the effect of ending the
|
||||
preceding line and starting a new line.
|
||||
The newline character (character code 10) has a special effect: it
|
||||
ends the preceding line and starts a new line.
|
||||
|
||||
@cindex ASCII control characters
|
||||
@item
|
||||
|
|
@ -5825,16 +5826,21 @@ when there are no scroll bars; if scroll bars are supported and in use,
|
|||
a scroll bar separates the two windows.
|
||||
@end table
|
||||
|
||||
For example, here is how to construct a display table that mimics the
|
||||
effect of setting @code{ctl-arrow} to a non-@code{nil} value:
|
||||
For example, here is how to construct a display table that mimics
|
||||
the effect of setting @code{ctl-arrow} to a non-@code{nil} value
|
||||
(@pxref{Glyphs}, for the function @code{make-glyph-code}):
|
||||
|
||||
@example
|
||||
(setq disptab (make-display-table))
|
||||
(dotimes (i 32)
|
||||
(or (= i ?\t)
|
||||
(= i ?\n)
|
||||
(aset disptab i (vector ?^ (+ i 64)))))
|
||||
(aset disptab 127 (vector ?^ ??))
|
||||
(aset disptab i
|
||||
(vector (make-glyph-code ?^ 'escape-glyph)
|
||||
(make-glyph-code (+ i 64) 'escape-glyph)))))
|
||||
(aset disptab 127
|
||||
(vector (make-glyph-code ?^ 'escape-glyph)
|
||||
(make-glyph-code ?? 'escape-glyph)))))
|
||||
@end example
|
||||
|
||||
@defun display-table-slot display-table slot
|
||||
|
|
@ -5906,122 +5912,82 @@ the standard display table.
|
|||
|
||||
@node Glyphs
|
||||
@subsection Glyphs
|
||||
@cindex glyph
|
||||
|
||||
A @dfn{glyph} is a graphical symbol which occupies a single
|
||||
character position on the screen. Each 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:
|
||||
as a @dfn{glyph code}, which specifies a character and optionally a
|
||||
face to display it in (@pxref{Faces}). The main use of glyph codes is
|
||||
as the entries of display tables (@pxref{Display Tables}). The
|
||||
following functions are used to manipulate glyph codes:
|
||||
|
||||
@defun make-glyph-code char &optional face
|
||||
This function returns a simple glyph code representing char @var{char}
|
||||
with face @var{face}.
|
||||
This function returns a glyph code representing char @var{char} with
|
||||
face @var{face}. If @var{face} is omitted or @code{nil}, the glyph
|
||||
uses the default face; in that case, the glyph code is an integer. If
|
||||
@var{face} is non-@code{nil}, the glyph code is not necessarily an
|
||||
integer object.
|
||||
@end defun
|
||||
|
||||
@defun glyph-char glyph
|
||||
This function returns the character of simple glyph code @var{glyph}.
|
||||
This function returns the character of 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).
|
||||
@xref{Face Functions}.
|
||||
This function returns face of glyph code @var{glyph}, or @code{nil} if
|
||||
@var{glyph} uses the default face.
|
||||
@end defun
|
||||
|
||||
On character terminals, you can set up a @dfn{glyph table} to define
|
||||
the meaning of glyph codes (represented as small integers).
|
||||
@ifnottex
|
||||
You can set up a @dfn{glyph table} to change how glyph codes are
|
||||
actually displayed on text terminals. This feature is semi-obsolete;
|
||||
use @code{glyphless-char-display} instead (@pxref{Glyphless Chars}).
|
||||
|
||||
@defvar glyph-table
|
||||
The value of this variable is the current glyph table. It should be
|
||||
@code{nil} or a vector whose @var{g}th element defines glyph code
|
||||
@var{g}.
|
||||
|
||||
If a glyph code is greater than or equal to the length of the glyph
|
||||
table, that code is automatically simple. If @code{glyph-table} is
|
||||
@code{nil} then all glyph codes are simple.
|
||||
|
||||
The glyph table is used only on character terminals. On graphical
|
||||
displays, all glyph codes are simple.
|
||||
@end defvar
|
||||
|
||||
Here are the meaningful types of elements in the glyph table:
|
||||
The value of this variable, if non-@code{nil}, is the current glyph
|
||||
table. It takes effect only on character terminals; on graphical
|
||||
displays, all glyphs are displayed literally. The glyph table should
|
||||
be a vector whose @var{g}th element specifies how to display glyph
|
||||
code @var{g}, where @var{g} is the glyph code for a glyph whose face
|
||||
is unspecified. Each element should be one of the following:
|
||||
|
||||
@table @asis
|
||||
@item @var{string}
|
||||
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.
|
||||
Display this glyph literally.
|
||||
|
||||
@item a string
|
||||
Display this glyph by sending the specified string to the terminal.
|
||||
|
||||
@item a glyph code
|
||||
Display the specified glyph code instead.
|
||||
@end table
|
||||
|
||||
@defun create-glyph string
|
||||
This function returns a newly-allocated glyph code which is set up to
|
||||
display by sending @var{string} to the terminal.
|
||||
@end defun
|
||||
|
||||
@node Beeping
|
||||
@section Beeping
|
||||
@c @cindex beeping "beep" is adjacent
|
||||
@cindex bell
|
||||
|
||||
This section describes how to make Emacs ring the bell (or blink the
|
||||
screen) to attract the user's attention. Be conservative about how
|
||||
often you do this; frequent bells can become irritating. Also be
|
||||
careful not to use just beeping when signaling an error is more
|
||||
appropriate. (@xref{Errors}.)
|
||||
|
||||
@defun ding &optional do-not-terminate
|
||||
@cindex keyboard macro termination
|
||||
This function beeps, or flashes the screen (see @code{visible-bell} below).
|
||||
It also terminates any keyboard macro currently executing unless
|
||||
@var{do-not-terminate} is non-@code{nil}.
|
||||
@end defun
|
||||
|
||||
@defun beep &optional do-not-terminate
|
||||
This is a synonym for @code{ding}.
|
||||
@end defun
|
||||
|
||||
@defopt visible-bell
|
||||
This variable determines whether Emacs should flash the screen to
|
||||
represent a bell. Non-@code{nil} means yes, @code{nil} means no.
|
||||
This is effective on graphical displays, and on text terminals
|
||||
provided the terminal's Termcap entry defines the visible bell
|
||||
capability (@samp{vb}).
|
||||
@end defopt
|
||||
|
||||
@defvar ring-bell-function
|
||||
If this is non-@code{nil}, it specifies how Emacs should ``ring the
|
||||
bell.'' Its value should be a function of no arguments. If this is
|
||||
non-@code{nil}, it takes precedence over the @code{visible-bell}
|
||||
variable.
|
||||
Any integer glyph code greater than or equal to the length of the
|
||||
glyph table is displayed literally.
|
||||
@end defvar
|
||||
@end ifnottex
|
||||
|
||||
@node Glyphless Chars
|
||||
@subsection Glyphless Character Display
|
||||
@cindex glyphless characters
|
||||
|
||||
@dfn{Glyphless characters} are not displayed in the usual way when
|
||||
they appear in a buffer, but in some special way (e.g. as a box
|
||||
containing a hexadecimal code). These include characters that cannot
|
||||
be displayed with any available font (on a graphical display), or that
|
||||
cannot be encoded by the terminal's coding system (on a text
|
||||
terminal). Specific characters can also be defined to be glyphless.
|
||||
@dfn{Glyphless characters} are characters which are displayed in a
|
||||
special way, e.g.@: as a box containing a hexadecimal code, instead of
|
||||
being displayed literally. These include characters which are
|
||||
explicitly defined to be glyphless, as well as characters for which
|
||||
there is no available font (on a graphical display), and characters
|
||||
which cannot be encoded by the terminal's coding system (on a text
|
||||
terminal).
|
||||
|
||||
@defvar glyphless-char-display
|
||||
The value of this variable is a char-table that defines glyphless
|
||||
characters and how they are displayed. If an entry is @code{nil}, the
|
||||
corresponding character is displayed in its usual way. Otherwise, an
|
||||
entry should be one of the following display methods:
|
||||
The value of this variable is a char-table which defines glyphless
|
||||
characters and how they are displayed. Each entry must be one of the
|
||||
following display methods:
|
||||
|
||||
@table @asis
|
||||
@item @code{nil}
|
||||
Display the character in the usual way.
|
||||
|
||||
@item @code{zero-width}
|
||||
Don't display the character.
|
||||
|
||||
|
|
@ -6038,27 +6004,34 @@ hexadecimal notation.
|
|||
|
||||
@item an @acronym{ASCII} string
|
||||
Display a box containing that string.
|
||||
|
||||
@item a cons cell @code{(@var{graphical} . @var{text})}
|
||||
Display with @var{graphical} on graphical displays, and with
|
||||
@var{text} on text terminals. Both @var{graphical} and @var{text}
|
||||
must be one of the display methods described above.
|
||||
@end table
|
||||
|
||||
@noindent
|
||||
Except for @code{zero-width}, these methods display using the
|
||||
The @code{thin-space}, @code{empty-box}, @code{hex-code}, and
|
||||
@acronym{ASCII} string display methods are drawn with the
|
||||
@code{glyphless-char} face.
|
||||
|
||||
An entry can also be a cons cell @code{(@var{graphical}
|
||||
. @var{text})}, where @var{graphical} and @var{text} are the display
|
||||
methods on graphical displays and text terminals respectively.
|
||||
|
||||
The char-table has one extra slot, which determines how to display any
|
||||
character that cannot be displayed with any available font, or cannot
|
||||
be encoded by the terminal's coding system. Its value should be one
|
||||
of the above display methods, except @code{zero-width} or a cons cell.
|
||||
|
||||
If a character has a non-@code{nil} entry in an active display table,
|
||||
the display table takes effect; in this case, Emacs does not consult
|
||||
@code{glyphless-char-display} at all.
|
||||
@end defvar
|
||||
|
||||
@defopt glyphless-char-display-control
|
||||
This user option provides a convenient way to set
|
||||
@code{glyphless-char-display} for groups of similar characters. It
|
||||
takes effect via a custom @code{:set} function (@pxref{Variable
|
||||
Definitions}), which update @code{glyphless-char-display}.
|
||||
@code{glyphless-char-display} for groups of similar characters. Do
|
||||
not set its value directly from Lisp code; the value takes effect only
|
||||
via a custom @code{:set} function (@pxref{Variable Definitions}),
|
||||
which updates @code{glyphless-char-display}.
|
||||
|
||||
Its value should be an alist of elements @code{(@var{group}
|
||||
. @var{method})}, where @var{group} is a symbol specifying a group of
|
||||
|
|
@ -6097,6 +6070,42 @@ The @var{method} symbol should be one of @code{zero-width},
|
|||
the same meanings as in @code{glyphless-char-display}, above.
|
||||
@end defopt
|
||||
|
||||
@node Beeping
|
||||
@section Beeping
|
||||
@cindex bell
|
||||
|
||||
This section describes how to make Emacs ring the bell (or blink the
|
||||
screen) to attract the user's attention. Be conservative about how
|
||||
often you do this; frequent bells can become irritating. Also be
|
||||
careful not to use just beeping when signaling an error is more
|
||||
appropriate (@pxref{Errors}).
|
||||
|
||||
@defun ding &optional do-not-terminate
|
||||
@cindex keyboard macro termination
|
||||
This function beeps, or flashes the screen (see @code{visible-bell} below).
|
||||
It also terminates any keyboard macro currently executing unless
|
||||
@var{do-not-terminate} is non-@code{nil}.
|
||||
@end defun
|
||||
|
||||
@defun beep &optional do-not-terminate
|
||||
This is a synonym for @code{ding}.
|
||||
@end defun
|
||||
|
||||
@defopt visible-bell
|
||||
This variable determines whether Emacs should flash the screen to
|
||||
represent a bell. Non-@code{nil} means yes, @code{nil} means no.
|
||||
This is effective on graphical displays, and on text terminals
|
||||
provided the terminal's Termcap entry defines the visible bell
|
||||
capability (@samp{vb}).
|
||||
@end defopt
|
||||
|
||||
@defvar ring-bell-function
|
||||
If this is non-@code{nil}, it specifies how Emacs should ``ring the
|
||||
bell.'' Its value should be a function of no arguments. If this is
|
||||
non-@code{nil}, it takes precedence over the @code{visible-bell}
|
||||
variable.
|
||||
@end defvar
|
||||
|
||||
@node Window Systems
|
||||
@section Window Systems
|
||||
|
||||
|
|
@ -6166,61 +6175,56 @@ interfere with it.
|
|||
@cindex right-to-left text
|
||||
|
||||
Emacs can display text written in scripts, such as Arabic, Farsi,
|
||||
and Hebrew, whose natural ordering of horizontal text for display is
|
||||
from right to left. However, digits and Latin text embedded in these
|
||||
scripts are still displayed left to right. It is also not uncommon to
|
||||
have small portions of text in Arabic or Hebrew embedded in otherwise
|
||||
Latin document, e.g., as comments and strings in a program source
|
||||
file. Likewise, small portions of Latin text can be embedded in an
|
||||
Arabic or Farsi document. For these reasons, text that uses these
|
||||
scripts is actually @dfn{bidirectional}: a mixture of runs of
|
||||
left-to-right and right-to-left characters.
|
||||
|
||||
This section describes the facilities and options provided by Emacs
|
||||
for editing and displaying bidirectional text.
|
||||
and Hebrew, whose natural ordering for horizontal text display runs
|
||||
from right to left. Furthermore, segments of Latin script and digits
|
||||
embedded in right-to-left text are displayed left-to-right, while
|
||||
segments of right-to-left script embedded in left-to-right text
|
||||
(e.g.@: Arabic or Hebrew text in comments or strings in a program
|
||||
source file) are appropriately displayed right-to-left. We call such
|
||||
mixtures of left-to-right and right-to-left text @dfn{bidirectional
|
||||
text}. This section describes the facilities and options for editing
|
||||
and displaying bidirectional text.
|
||||
|
||||
@cindex logical order
|
||||
@cindex reading order
|
||||
@cindex visual order
|
||||
@cindex unicode bidirectional algorithm
|
||||
Emacs stores right-to-left and bidirectional text in the so-called
|
||||
@dfn{logical} (or @dfn{reading}) order: the buffer or string position
|
||||
of the first character you read precedes that of the next character.
|
||||
Reordering of bidirectional text into the @dfn{visual} order happens
|
||||
at display time. As result, character positions no longer increase
|
||||
monotonically with their positions on display. Emacs implements the
|
||||
Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}) described in
|
||||
the Unicode Standard Annex #9, for reordering of bidirectional text
|
||||
for display. Reordering of bidirectional text for display in Emacs is
|
||||
a ``Full bidirectionality'' class implementation of the @acronym{UBA}.
|
||||
@cindex bidirectional reordering
|
||||
Text is stored in Emacs buffers and strings in @dfn{logical} (or
|
||||
@dfn{reading}) order, i.e.@: the order in which a human would read
|
||||
each character. In right-to-left and bidirectional text, the order in
|
||||
which characters are displayed on the screen (called @dfn{visual
|
||||
order}) is not the same as logical order; the characters' screen
|
||||
positions do not increase monotonically with string or buffer
|
||||
position. In performing this @dfn{bidirectional reordering}, Emacs
|
||||
follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}),
|
||||
which is described in Annex #9 of the Unicode standard
|
||||
(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full
|
||||
Bidirectionality'' class implementation of the @acronym{UBA}.
|
||||
|
||||
@defvar bidi-display-reordering
|
||||
This buffer-local variable controls whether text in the buffer is
|
||||
reordered for display. If its value is non-@code{nil}, Emacs reorders
|
||||
characters that have right-to-left directionality when they are
|
||||
displayed. The default value is @code{t}. Text in overlay strings
|
||||
(@pxref{Overlay Properties,,before-string}), display strings
|
||||
(@pxref{Overlay Properties,,display}), and @code{display} text
|
||||
properties (@pxref{Display Property}) is also reordered for display if
|
||||
the buffer whose text includes these strings is reordered. Turning
|
||||
off @code{bidi-display-reordering} for a buffer turns off reordering
|
||||
of all the overlay and display strings in that buffer.
|
||||
If the value of this buffer-local variable is non-@code{nil} (the
|
||||
default), Emacs performs bidirectional reordering for display. The
|
||||
reordering affects buffer text, as well as display strings and overlay
|
||||
strings from text and overlay properties in the buffer (@pxref{Overlay
|
||||
Properties}, and @pxref{Display Property}). If the value is
|
||||
@code{nil}, Emacs does not perform bidirectional reordering in the
|
||||
buffer.
|
||||
|
||||
Reordering of strings that are unrelated to any buffer, such as text
|
||||
displayed on the mode line (@pxref{Mode Line Format}) or header line
|
||||
(@pxref{Header Lines}), is controlled by the default value of
|
||||
@code{bidi-display-reordering}.
|
||||
The default value of @code{bidi-display-reordering} controls the
|
||||
reordering of strings which are not directly supplied by a buffer,
|
||||
including the text displayed in mode lines (@pxref{Mode Line Format})
|
||||
and header lines (@pxref{Header Lines}).
|
||||
@end defvar
|
||||
|
||||
@cindex unibyte buffers, and bidi reordering
|
||||
Emacs does not reorder text in unibyte buffers, even if
|
||||
@code{bidi-display-reordering} is non-@code{nil} in such a buffer.
|
||||
This is because unibyte buffers contain raw bytes, not characters, and
|
||||
thus don't have bidirectional properties defined for them which are
|
||||
required for correct reordering. Therefore, to test whether text in a
|
||||
buffer will be reordered for display, it is not enough to test the
|
||||
value of @code{bidi-display-reordering} alone. The correct test is
|
||||
this:
|
||||
Emacs never reorders the text of a unibyte buffer, even if
|
||||
@code{bidi-display-reordering} is non-@code{nil} in the buffer. This
|
||||
is because unibyte buffers contain raw bytes, not characters, and thus
|
||||
lack the directionality properties required for reordering.
|
||||
Therefore, to test whether text in a buffer will be reordered for
|
||||
display, it is not enough to test the value of
|
||||
@code{bidi-display-reordering} alone. The correct test is this:
|
||||
|
||||
@example
|
||||
(if (and enable-multibyte-characters
|
||||
|
|
@ -6229,12 +6233,11 @@ this:
|
|||
)
|
||||
@end example
|
||||
|
||||
In contrast to unibyte buffers, unibyte display and overlay strings
|
||||
@emph{are} reordered, if their parent buffer is reordered. This is
|
||||
because plain-@sc{ascii} strings are stored by Emacs as unibyte
|
||||
strings. If a unibyte display or overlay string includes
|
||||
non-@sc{ascii} characters, these characters are assumed to have
|
||||
left-to-right direction.
|
||||
However, unibyte display and overlay strings @emph{are} reordered if
|
||||
their parent buffer is reordered. This is because plain-@sc{ascii}
|
||||
strings are stored by Emacs as unibyte strings. If a unibyte display
|
||||
or overlay string includes non-@sc{ascii} characters, these characters
|
||||
are assumed to have left-to-right direction.
|
||||
|
||||
@cindex display properties, and bidi reordering of text
|
||||
Text covered by @code{display} text properties, by overlays with
|
||||
|
|
@ -6242,7 +6245,7 @@ left-to-right direction.
|
|||
properties that replace buffer text, is treated as a single unit when
|
||||
it is reordered for display. That is, the entire chunk of text
|
||||
covered by these properties is reordered together. Moreover, the
|
||||
bidirectional properties of the characters in this chunk of text are
|
||||
bidirectional properties of the characters in such a chunk of text are
|
||||
ignored, and Emacs reorders them as if they were replaced with a
|
||||
single character @code{U+FFFC}, known as the @dfn{Object Replacement
|
||||
Character}. This means that placing a display property over a portion
|
||||
|
|
@ -6252,36 +6255,34 @@ properties on text whose directionality is identical with text that
|
|||
surrounds it.
|
||||
|
||||
@cindex base direction of a paragraph
|
||||
Each paragraph of bidirectional text can have its own @dfn{base
|
||||
direction}, either right-to-left or left-to-right. Text in
|
||||
left-to-right paragraphs is displayed beginning at the left margin of
|
||||
the window and is truncated or continued when it reaches the right
|
||||
margin. By contrast, display of text in right-to-left paragraphs
|
||||
begins at the right margin and is continued or truncated at the left
|
||||
margin.
|
||||
Each paragraph of bidirectional text has a @dfn{base direction},
|
||||
either right-to-left or left-to-right. Left-to-right paragraphs are
|
||||
displayed beginning at the left margin of the window, and are
|
||||
truncated or continued when the text reaches the right margin.
|
||||
Right-to-left paragraphs are displayed beginning at the right margin,
|
||||
and are continued or truncated at the left margin.
|
||||
|
||||
By default, Emacs determines the base direction of each paragraph by
|
||||
looking at the text at its beginning. The precise method of
|
||||
determining the base direction is specified by the @acronym{UBA}; in a
|
||||
nutshell, the first character in a paragraph that has an explicit
|
||||
directionality determines the base direction of the paragraph.
|
||||
However, sometimes a buffer may need to force a certain base direction
|
||||
for its paragraphs. For example, buffers containing program source
|
||||
code should force all paragraphs to be displayed left-to-right. You
|
||||
can use following variable to do this:
|
||||
|
||||
@defvar bidi-paragraph-direction
|
||||
By default, Emacs determines the base direction of each paragraph
|
||||
dynamically, based on the text at the beginning of the paragraph. The
|
||||
precise method of determining the base direction is specified by the
|
||||
@acronym{UBA}; in a nutshell, the first character in a paragraph that
|
||||
has an explicit directionality determines the base direction of the
|
||||
paragraph. However, sometimes a buffer may need to force a certain
|
||||
base direction for its paragraphs. For example, a buffer that visits
|
||||
a source code of a program should force all its paragraphs to be
|
||||
displayed left to right. The variable
|
||||
@code{bidi-paragraph-direction}, if non-@code{nil}, disables the
|
||||
dynamic determination of the base direction, and instead forces all
|
||||
paragraphs in the buffer to have the direction specified by its
|
||||
buffer-local value. The value can be either @code{right-to-left} or
|
||||
@code{left-to-right}. Any other value is interpreted as @code{nil}.
|
||||
The default is @code{nil}.
|
||||
If the value of this buffer-local variable is the symbol
|
||||
@code{right-to-left} or @code{left-to-right}, all paragraphs in the
|
||||
buffer are assumed to have that specified direction. Any other value
|
||||
is equivalent to @code{nil} (the default), which means to determine
|
||||
the base direction of each paragraph from its contents.
|
||||
|
||||
@cindex @code{prog-mode}, and @code{bidi-paragraph-direction}
|
||||
Modes that are meant to display program source code should force a
|
||||
@code{left-to-right} paragraph direction. The easiest way of doing so
|
||||
is to derive the mode from Prog Mode, which already sets
|
||||
@code{bidi-paragraph-direction} to that value.
|
||||
Modes for program source code should set this to @code{left-to-right}.
|
||||
Prog mode does this by default, so modes derived from Prog mode do not
|
||||
need to set this explicitly (@pxref{Basic Major Modes}).
|
||||
@end defvar
|
||||
|
||||
@defun current-bidi-paragraph-direction &optional buffer
|
||||
|
|
@ -6300,22 +6301,18 @@ buffers, this function always returns @code{left-to-right}.
|
|||
@cindex layout on display, and bidirectional text
|
||||
@cindex jumbled display of bidirectional text
|
||||
@cindex concatenating bidirectional strings
|
||||
Reordering of bidirectional text for display can have surprising and
|
||||
unpleasant effects when two strings with bidirectional content are
|
||||
juxtaposed in a buffer, or otherwise programmatically concatenated
|
||||
into a string of text. A typical example is a buffer whose lines are
|
||||
actually sequences of items, or fields, separated by whitespace or
|
||||
punctuation characters. This is used in specialized modes such as
|
||||
Buffer-menu Mode or various email summary modes, like Rmail Summary
|
||||
Mode. Because these separator characters are @dfn{weak}, i.e.@: have
|
||||
no strong directionality, they take on the directionality of
|
||||
surrounding text. As result, a numeric field that follows a field
|
||||
with bidirectional content can be displayed @emph{to the left} of the
|
||||
preceding field, producing a jumbled display and messing up the
|
||||
expected layout.
|
||||
|
||||
To countermand this, we recommend that you use one of the following
|
||||
techniques for forcing correct order of fields on display:
|
||||
Bidirectional reordering can have surprising and unpleasant effects
|
||||
when two strings with bidirectional content are juxtaposed in a
|
||||
buffer, or otherwise programmatically concatenated into a string of
|
||||
text. A typical problematic case is when a buffer consists of
|
||||
sequences of text ``fields'' separated by whitespace or punctuation
|
||||
characters, like Buffer Menu mode or Rmail Summary Mode. Because the
|
||||
punctuation characters used as separators have @dfn{weak
|
||||
directionality}, they take on the directionality of surrounding text.
|
||||
As result, a numeric field that follows a field with bidirectional
|
||||
content can be displayed @emph{to the left} of the preceding field,
|
||||
messing up the expected layout. There are several ways to avoid this
|
||||
problem:
|
||||
|
||||
@itemize @minus
|
||||
@item
|
||||
|
|
@ -6325,28 +6322,23 @@ content, or prepend it to the beginning of the following field. The
|
|||
function @code{bidi-string-mark-left-to-right}, described below, comes
|
||||
in handy for this purpose. (In a right-to-left paragraph, use
|
||||
@code{U+200F}, RIGHT-TO-LEFT MARK, or @acronym{RLM}, instead.) This
|
||||
is one of the solutions recommended by
|
||||
@uref{http://www.unicode.org/reports/tr9/#Separators, the
|
||||
@acronym{UBA}}.
|
||||
is one of the solutions recommended by the UBA.
|
||||
|
||||
@item
|
||||
Include the tab character in the field separator. The tab character
|
||||
plays the role of @dfn{segment separator} in the @acronym{UBA}
|
||||
reordering, whose effect is to make each field a separate segment, and
|
||||
thus reorder them separately.
|
||||
plays the role of @dfn{segment separator} in bidirectional reordering,
|
||||
causing the text on either side to be reordered separately.
|
||||
|
||||
@cindex @code{space} display spec, and bidirectional text
|
||||
@item
|
||||
Separate fields with a @code{display} property or overlay with the
|
||||
Separate fields with a @code{display} property or overlay with a
|
||||
property value of the form @code{(space . PROPS)} (@pxref{Specified
|
||||
Space}). This display specification is treated by Emacs as a
|
||||
@dfn{paragraph separator}; the text before and after the separator is
|
||||
reordered separately, which avoids the influence of any field on its
|
||||
neighboring fields.
|
||||
Space}). Emacs treats this display specification as a @dfn{paragraph
|
||||
separator}, and reorders the text on either side separately.
|
||||
@end itemize
|
||||
|
||||
@defun bidi-string-mark-left-to-right string
|
||||
This subroutine returns its argument @var{string}, possibly modified,
|
||||
This function returns its argument @var{string}, possibly modified,
|
||||
such that the result can be safely concatenated with another string,
|
||||
or juxtaposed with another string in a buffer, without disrupting the
|
||||
relative layout of this string and the next one on display. If the
|
||||
|
|
@ -6356,7 +6348,8 @@ of the text that follows it. The function works by examining the
|
|||
characters of its argument, and if any of those characters could cause
|
||||
reordering on display, the function appends the @acronym{LRM}
|
||||
character to the string. The appended @acronym{LRM} character is made
|
||||
@emph{invisible} (@pxref{Invisible Text}), to hide it on display.
|
||||
invisible by giving it an @code{invisible} text property of @code{t}
|
||||
(@pxref{Invisible Text}).
|
||||
@end defun
|
||||
|
||||
The reordering algorithm uses the bidirectional properties of the
|
||||
|
|
|
|||
|
|
@ -1,3 +1,8 @@
|
|||
2012-03-30 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* image.el (imagemagick-types-inhibit)
|
||||
(imagemagick-register-types): Doc fix.
|
||||
|
||||
2012-03-30 Agustín Martín Domingo <agustin.martin@hispalinux.es>
|
||||
|
||||
* ispell.el (ispell-get-extended-character-mode): Disable
|
||||
|
|
|
|||
|
|
@ -686,14 +686,13 @@ The minimum delay between successive frames is 0.01s."
|
|||
|
||||
(defcustom imagemagick-types-inhibit
|
||||
'(C HTML HTM TXT PDF)
|
||||
"ImageMagick types that Emacs should not use ImageMagick to handle.
|
||||
This should be a list of symbols, each of which has the same
|
||||
name as one of the format tags used internally by ImageMagick;
|
||||
see `imagemagick-types'. Entries in this list are excluded from
|
||||
being registered by `imagemagick-register-types', so if you change
|
||||
this variable you must do so before you call that function.
|
||||
"ImageMagick types that should not be visited in Image mode.
|
||||
This should be a list of symbols, each of which should be one of
|
||||
the ImageMagick types listed in `imagemagick-types'. These image
|
||||
types are not registered by `imagemagick-register-types'.
|
||||
|
||||
If Emacs is compiled without ImageMagick, this variable has no effect."
|
||||
If Emacs is compiled without ImageMagick support, this variable
|
||||
has no effect."
|
||||
:type '(choice (const :tag "Let ImageMagick handle all types it can" nil)
|
||||
(repeat symbol))
|
||||
;; Ideally, would have a :set function that checks if we already did
|
||||
|
|
@ -704,10 +703,13 @@ If Emacs is compiled without ImageMagick, this variable has no effect."
|
|||
;;;###autoload
|
||||
(defun imagemagick-register-types ()
|
||||
"Register file types that can be handled by ImageMagick.
|
||||
This adds the file types returned by `imagemagick-types'
|
||||
\(excluding the ones in `imagemagick-types-inhibit') to
|
||||
`auto-mode-alist' and `image-type-file-name-regexps', so that
|
||||
Emacs visits them in Image mode.
|
||||
This registers the ImageMagick types listed in `imagemagick-types',
|
||||
excluding those listed in `imagemagick-types-inhibit'.
|
||||
|
||||
Registered image types are added to `auto-mode-alist', so that
|
||||
Emacs visits them in Image mode. They are also added to
|
||||
`image-type-file-name-regexps', so that the `image-type' function
|
||||
recognizes these files as having image type `imagemagick'.
|
||||
|
||||
If Emacs is compiled without ImageMagick support, do nothing."
|
||||
(when (fboundp 'imagemagick-types)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue