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