[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r105311: doc/lispref/display.texi (Bi
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r105311: doc/lispref/display.texi (Bidirectional Display): New section. |
Date: |
Sat, 23 Jul 2011 18:36:52 +0300 |
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 105311
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Sat 2011-07-23 18:36:52 +0300
message:
doc/lispref/display.texi (Bidirectional Display): New section.
modified:
doc/lispref/ChangeLog
doc/lispref/display.texi
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2011-07-16 20:05:20 +0000
+++ b/doc/lispref/ChangeLog 2011-07-23 15:36:52 +0000
@@ -1,3 +1,7 @@
+2011-07-23 Eli Zaretskii <address@hidden>
+
+ * display.texi (Bidirectional Display): New section.
+
2011-07-16 Lars Magne Ingebrigtsen <address@hidden>
Tim Cross <address@hidden> (tiny change)
Glenn Morris <address@hidden>
=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi 2011-07-14 17:28:42 +0000
+++ b/doc/lispref/display.texi 2011-07-23 15:36:52 +0000
@@ -34,6 +34,8 @@
* Display Tables:: How to specify other conventions.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
+* Bidirectional Display:: Display of bidirectional scripts, such as
+ Arabic and Farsi.
@end menu
@node Refresh Screen
@@ -5966,3 +5968,131 @@
the window system, and creating the initial window. Users should not
interfere with it.
@end defvar
+
address@hidden Bidirectional Display
address@hidden Bidirectional Display
address@hidden bidirectional display
address@hidden 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.
+
address@hidden logical order
address@hidden visual order
address@hidden unicode bidirectional algorithm
+ Emacs stores right-to-left and bidirectional text in the so-called
address@hidden (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}.
+
address@hidden bidi-display-reordering
+ The buffer-local variable @code{bidi-display-reordering} controls
+whether text in the buffer is reordered for display. If its value is
address@hidden, Emacs reorders characters that have right-to-left
+directionality when they are displayed. The default value is
address@hidden 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 if the buffer whose text
+includes these strings is reordered for display. Turning off
address@hidden for a buffer turns off reordering of
+all the overlay and display strings in that 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
address@hidden
address@hidden defvar
+
address@hidden unibyte buffers, and bidi reordering
+ Emacs does not reorder text in unibyte buffers, even if
address@hidden is address@hidden 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:
+
address@hidden
+ (if (and enable-multibyte-characters
+ bidi-display-reordering)
+ ;; Buffer is being reordered for display
+ )
address@hidden example
+
+ In contrast to unibyte buffers, unibyte display and overlay strings
address@hidden reordered, if their parent buffer is reordered. This is
+because address@hidden strings are stored by Emacs as unibyte
+strings. If a unibyte display or overlay string includes
address@hidden characters, these characters are assumed to have
+left-to-right direction.
+
address@hidden display properties, and bidi reordering of text
+ Text covered by @code{display} text properties, by overlays with
address@hidden properties whose value is a string, and by any other
+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
+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
+of text may change the way that the surrounding text is reordered for
+display. To prevent this unexpected effect, always place such
+properties on text whose directionality is identical with text that
+surrounds it.
+
address@hidden 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.
+
address@hidden bidi-paragraph-direction
+ 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
address@hidden; 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
address@hidden, if address@hidden, 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
address@hidden Any other value is interpreted as @code{nil}.
address@hidden defvar
+
address@hidden current-bidi-paragraph-direction &optional buffer
+This function returns the paragraph direction at point in the named
address@hidden The returned value is a symbol, either
address@hidden or @code{right-to-left}. If @var{buffer} is
+omitted or @code{nil}, it defaults to the current buffer. If the
+buffer-local value of the variable @code{bidi-paragraph-direction} is
address@hidden, the returned value will be identical to that value;
+otherwise, the returned value reflects the paragraph direction
+determined dynamically by Emacs.
address@hidden defun
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r105311: doc/lispref/display.texi (Bidirectional Display): New section.,
Eli Zaretskii <=