README

   1 # GNU FriBidi
   2
   3 The Free Implementation of the [Unicode Bidirectional Algorithm].
   4
   5 ## Background
   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 needs to be implemented. It is our hope that this library will stimulate more free software in the Middle Eastern countries.
  10
  11 See [`HISTORY`](./HISTORY) on how the project started and evolved.
  12
  13
  14 ## Audience
  15
  16 It is our hope that this library will stimulate the implementation of Hebrew and
  17 Arabic support in lots of Free Software.
  18
  19 GNU FriBidi is already being used in projects like Pango (resulting in [GTK+] and [GNOME] using GNU FriBidi), AbiWord, MLTerm, MPlayer, BiCon, and vlc.
  20
  21 See [`USERS`](./USERS) for a list of projects using GNU FriBidi.
  22
  23
  24 ## Dependencies
  25
  26 GNU FriBidi does not depend on any other library. It uses either the GNU Build System or meson for build and installation.
  27
  28
  29 ## Downloading
  30
  31 The latest version of GNU FriBidi may be found at:
  32 <https://github.com/fribidi/fribidi>
  33
  34
  35 ## Building
  36
  37 Start with running the [`autogen.sh`](./autogen.sh) script and follow the
  38 instructions. Alternatively use `meson`.
  39
  40
  41 ## License
  42
  43 GNU FriBidi is Free Software; you can redistribute it and/or modify it under the
  44 terms of the [GNU Lesser General Public License] as published by the Free Software
  45
  46 Foundation; either version 2.1 of the License, or (at your option) any later
  47 version.
  48
  49 GNU FriBidi is distributed in the hope that it will be useful, but WITHOUT ANY
  50 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
  51 PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
  52
  53 You should have received a copy of the GNU Lesser General Public License along
  54 with GNU FriBidi, in a file named COPYING; if not, write to the Free Software
  55 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  56
  57 ### Commercial licensing
  58
  59 For commercial licensing options, contact <fribidi.license@gmail.com>.
  60
  61 ## Implementation
  62
  63 The library implements the algorithm described in the "Unicode Standard Annex
  64 \#9, The Bidirectional Algorithm", available at
  65 <http://www.unicode.org/unicode/reports/tr9/>.
  66
  67 The library uses Unicode (UTF-32) entirely. The character properties are
  68 automatically extracted from the Unicode data files, available from
  69 <http://www.unicode.org/Public/UNIDATA/>. This means that every Unicode
  70 character is treated in strict accordance with the Unicode specification.
  71
  72 There is a limited support for character set conversion from/to the UTF-32
  73 encoding. Data in these character sets must be converted into UTF-32 before the
  74 library may be used. iconv(3) can always do a better job on that, so you may
  75 find that the character sets conversion code is typically turned off on POSIX
  76 machines.
  77
  78
  79 ### Conformance Status
  80
  81 GNU FriBidi has been tested exhaustively against the [Unicode Reference Code],
  82 and to the best of our knowledge, it completely conforms to the specification,
  83 always producing the same result as the Reference Code.
  84
  85
  86 ### API
  87
  88 The simplest way of accessing the API is through the convenience function `fribibidi_log2vis` which has the following signature:
  89
  90 ```c
  91 fribidi_boolean fribidi_log2vis(
  92     /* input */
  93     FriBidiChar     *str,
  94     FriBidiStrIndex len,
  95     FriBidiCharType *pbase_dir,
  96     /* output */
  97     FriBidiChar     *visual_str,
  98     FriBidiStrIndex *position_L_to_V_list,
  99     FriBidiStrIndex *position_V_to_L_list,
 100     FriBidiLevel    *embedding_level_list
 101 )
 102 ```
 103
 104 Where...
 105
 106 * `str` is the Unicode input string.
 107 * `len` is the length of the Unicode string (`str`).
 108 * `pbase_dir` is the input and output base direction. If `pbase_dir ==
 109   FRIBIDI_TYPE_ON` then `fribidi_log2vis()` calculates the base direction on its
 110   own, according to the bidi algorithm.
 111 * `visual_str` is the reordered output unicode string.
 112 * `position_L_to_V_list` maps the positions in the logical string to positions
 113   in the visual string.
 114 * `position_V_to_L_list` maps the positions in the visual string to the
 115   positions in the logical string.
 116 * `embedding_level_list` returns the classification of each character. Here,
 117   even numerical levels indicate LTR characters, and odd levels indicate RTL
 118   characters. The main use of this list is in interactive applications where,
 119   for example, the embedding level determines cursor display.
 120
 121 If any of the output pointers is equal to `NULL`, then that information is not
 122 calculated.
 123
 124 Note that a call to `fribidi_log2vis()` is a convenience function to calling the following three functions in order:
 125
 126 1. `fribidi_get_bidi_types()`
 127 2. `fribidi_get_par_embedding_levels_ex()`
 128 3. `fribidi_reorder_line()`
 129
 130 ## How it looks like
 131
 132 Have a look at [`test/`](./test) directory, to see some input and outputs.
 133
 134 The `CapRTL` charset means that CAPITAL letters are right to left, and digits
 135 6, 7, 8, 9 are Arabic digits, try 'fribidi --charsetdesc CapRTL' for the full
 136 description.
 137
 138
 139 ## Executable
 140
 141 There is also a command-line utilitity called `fribidi` that loops over the text
 142 of a file and performs the bidi algorithm on each line, also used for testing
 143 the algorithm.
 144
 145 Run `fribidi --help` to learn about usage.
 146
 147 The command-line utility is known to have problems with line-breaking and
 148 logical-to-vertical/vertical-to-logical lists.
 149
 150
 151 ## Bug Reports and Feedback
 152
 153 Report bugs and general feedback at: <https://github.com/fribidi/fribidi/issues>
 154
 155 The mailing list is the place for additional technical discussions and user
 156 questions: <https://lists.freedesktop.org/mailman/listinfo/fribidi>
 157
 158
 159 ## Maintainers and Contributors
 160
 161 * Dov Grobgeld <dov.grobgeld@gmail.com> - Original author and current maintainer
 162 * Behdad Esfahbod <behdad@gnu.org> - Author of most of the code
 163
 164 See also [`AUTHORS`](./AUTHORS) and [`THANKS`](./THANKS) for the complete list
 165 of contributors.
 166
 167
 168 [Unicode Bidirectional Algorithm]: https://www.unicode.org/reports/tr9/
 169 [Unicode Reference Code]: https://www.unicode.org/reports/tr9/#Reference_Code
 170 [Mirroring]: https://www.unicode.org/reports/tr9/#Mirroring
 171 [GTK+]: https://www.gtk.org/
 172 [GNOME]: https://www.gnome.org/
 173 [GNU Lesser General Public License]: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html