Imported Upstream version 0.19.5
[platform/upstream/fribidi.git] / README
1 This is GNU FriBidi
2 The Free Implementation of the Unicode Bidirectional Algorithm.
3
4 Background
5 ==========
6
7 One of the missing links stopping the penetration of free software in Middle
8 East is the lack of support for the Arabic and Hebrew alphabets. In order to
9 have proper Arabic and Hebrew support, the BiDi algorithm should have been
10 implemented. It is our hope that this library will stimulate more free
11 software in the Middle Eastern countries.
12
13 Audience
14 ========
15
16 It is our hope that this library will stimulate the implementation of Hebrew
17 and Arabic in lots of free software. Here is a small list of projects that
18 would benefit from the use of the GNU FriBidi library, but of course there are
19 many more: Wine, Mozilla, Qt, KDE, lynx, OpenOffice.
20
21 GNU FriBidi is already being used in projects like Pango (resulting in GTK+
22 and GNOME using GNU FriBidi), AbiWord, MLTerm, MPlayer, and BiCon.
23
24 Dependencies
25 ============
26
27 Currently GNU FriBidi does not depend on any other library, but uses Glib if
28 available.  It uses GNU Build System for build and installation on POSIX
29 systems.
30
31 Downloading
32 ===========
33
34 The latest version of GNU FriBidi may be found at:
35
36    http://fribidi.org/
37
38 Building
39 ========
40
41 See INSTALL for a description of how to build and install GNU FriBidi.
42
43 License
44 =========
45
46 GNU FriBidi is free software; you can redistribute it and/or
47 modify it under the terms of the GNU Lesser General Public License
48 as published by the Free Software Foundation; either version 2.1
49 of the License, or (at your option) any later version.
50
51 GNU FriBidi is distributed in the hope that it will be useful,
52 but WITHOUT ANY WARRANTY; without even the implied warranty of
53 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
54 GNU Lesser General Public License for more details.
55
56 You should have received a copy of the GNU Lesser General Public License
57 along with GNU FriBidi, in a file named COPYING; if not, write to the
58 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
59 Boston, MA  02110-1301  USA
60
61 For licensing issues, contact <license@farsiweb.info>.
62
63 Implementation
64 ==============
65
66 The library implements the algorithm described in the "Unicode Standard
67 Annex #9, The Bidirectional Algorithm", available at
68 http://www.unicode.org/unicode/reports/tr9/. GNU Fribidi has been tested
69 exhaustively against the Unicode Reference Code, and to the best of our
70 knowledge, it completely conforms to the specification, always producing
71 the same result as the Reference Code.
72
73 The library uses Unicode (UTF32) entirely. The character properties are
74 automatically extracted from the Unicode data files, available from:
75
76         http://www.unicode.org/Public/UNIDATA/
77
78 This means that every Unicode character is treated in strict accordance
79 with the Unicode specification.
80
81 There is a limited support for character set conversion from/to the UTF32
82 encoding.  Data in these character sets must be converted into UTF32 before
83 the library may be used.  iconv(3) can always do a better job on that, so you
84 may find that the character sets conversion code is typically turned off on
85 POSIX machines.
86
87 The reordering of characters is typically done through the function:
88       
89      fribidi_boolean
90      fribidi_log2vis(/* input */
91                      FriBidiChar *str,
92                      FriBidiStrIndex len,
93                      FriBidiCharType *pbase_dir,
94                      /* output */
95                      FriBidiChar *visual_str,
96                      FriBidiStrIndex *position_L_to_V_list,
97                      FriBidiStrIndex *position_V_to_L_list,
98                      FriBidiLevel    *embedding_level_list
99                      )
100     
101
102 where
103      str                    is the Unicode input string
104      len                    is the length of the unicode string
105      pbase_dir              is the input and output base direction. If 
106                             base == FRIBIDI_TYPE_ON then fribidi_log2vis 
107                             calculates the base direction on its own
108                             according to the BiDi algorithm.
109      visual_str             The reordered output unicode string.
110      position_L_to_V_list   Maps the positions in the logical string to 
111                             positions in the visual string.
112      position_V_to_L_list   Maps the positions in the visual string to 
113                             the positions in the logical string.
114      embedding_level_list   Returns the classification of each character. Even
115                             levels indicate LTR characters, and odd levels
116                             indicate RTL characters. The main use of this
117                             list is in interactive applications when the
118                             embedding e.g. level determines cursor display.
119
120 In any of the output pointers == NULL, then that information is not 
121 calculated.
122
123 How it looks like
124 =================
125
126 Have a look at tests directory, to see some input and outputs, which
127 CapRTL charset means that CAPITAL letters are right to left, and digits
128 6, 7, 8, 9 are Arabic digits, try 'fribidi --charsetdesc CapRTL' for the
129 full description.
130
131 Executable
132 ==========
133
134 There is also a command-line utilitity called fribidi that loops over
135 the text of a file and performs the BiDi algorithm on each line, also
136 used for testing the algorithm. Run fribidi with the --help option to
137 learn about usage.  The command-line utility is known to have problems
138 with line-breaking and ltov/vtol lists.
139
140 Bugs and comments
141 =================
142
143 Report GNU FriBidi bugs at:
144
145         http://fribidi.org/bug
146
147 And send your comments to:
148
149         fribidi@freedesktop.org
150
151
152 Behdad Esfahbod
153 behdad@gnu.org