From a0ab164431e18fa7cdf5b0a8ce4fcbe26f7b022b Mon Sep 17 00:00:00 2001 From: Behnam Esfahbod Date: Mon, 6 Nov 2017 17:35:28 -0800 Subject: Update README.md --- HACKING | 2 - README | 158 +------------------------------------------------------- README.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 175 insertions(+), 159 deletions(-) delete mode 100644 HACKING mode change 100644 => 120000 README create mode 100644 README.md diff --git a/HACKING b/HACKING deleted file mode 100644 index e3f8d9a..0000000 --- a/HACKING +++ /dev/null @@ -1,2 +0,0 @@ -So you are interested in hacking GNU FriBidi? Great... -Join the mailing list and lets talk. diff --git a/README b/README deleted file mode 100644 index f7e4d02..0000000 --- a/README +++ /dev/null @@ -1,157 +0,0 @@ -This is GNU FriBidi -The Free Implementation of the Unicode Bidirectional Algorithm. - -Background -========== - -One of the missing links stopping the penetration of free software in Middle -East is the lack of support for the Arabic and Hebrew alphabets. In order to -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. - -Audience -======== - -It is our hope that this library will stimulate the implementation of -Hebrew and Arabic support in lots of free software. Here is a small -list of projects that would benefit from the use of the GNU FriBidi -library, but of course there are many more: Wine, Mozilla, Qt, KDE, -lynx, OpenOffice. - -GNU FriBidi is already being used in projects like Pango (resulting in GTK+ -and GNOME using GNU FriBidi), AbiWord, MLTerm, MPlayer, and BiCon. - -Dependencies -============ - -Currently GNU FriBidi does not depend on any other library, but uses Glib if -available. It uses GNU Build System for build and installation on POSIX -systems. - -Downloading -=========== - -The latest version of GNU FriBidi may be found at: - - http://fribidi.org/ - -Building -======== - -See INSTALL for a description of how to build and install GNU FriBidi. - -License -========= - -GNU FriBidi is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public License -as published by the Free Software Foundation; either version 2.1 -of the License, or (at your option) any later version. - -GNU FriBidi is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU Lesser General Public License for more details. - -You should have received a copy of the GNU Lesser General Public License -along with GNU FriBidi, in a file named COPYING; if not, write to the -Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -Boston, MA 02110-1301 USA - -For licensing issues, contact . - -Implementation -============== - -The library implements the algorithm described in the "Unicode Standard -Annex #9, The Bidirectional Algorithm", available at -http://www.unicode.org/unicode/reports/tr9/. GNU Fribidi has been tested -exhaustively against the Unicode Reference Code, and to the best of our -knowledge, it completely conforms to the specification, always producing -the same result as the Reference Code. - -The library uses Unicode (UTF32) entirely. The character properties are -automatically extracted from the Unicode data files, available from: - - http://www.unicode.org/Public/UNIDATA/ - -This means that every Unicode character is treated in strict accordance -with the Unicode specification. - -There is a limited support for character set conversion from/to the UTF32 -encoding. Data in these character sets must be converted into UTF32 before -the library may be used. iconv(3) can always do a better job on that, so you -may find that the character sets conversion code is typically turned off on -POSIX machines. - -The reordering of characters is typically done through the function: - - fribidi_boolean - fribidi_log2vis(/* input */ - FriBidiChar *str, - FriBidiStrIndex len, - FriBidiCharType *pbase_dir, - /* output */ - FriBidiChar *visual_str, - FriBidiStrIndex *position_L_to_V_list, - FriBidiStrIndex *position_V_to_L_list, - FriBidiLevel *embedding_level_list - ) - - -where - str is the Unicode input string - len is the length of the unicode string - pbase_dir is the input and output base direction. If - base == FRIBIDI_TYPE_ON then fribidi_log2vis - calculates the base direction on its own - according to the BiDi algorithm. - visual_str The reordered output unicode string. - position_L_to_V_list Maps the positions in the logical string to - positions in the visual string. - position_V_to_L_list Maps the positions in the visual string to - the positions in the logical string. - embedding_level_list Returns the classification of each character. Even - levels indicate LTR characters, and odd levels - indicate RTL characters. The main use of this - list is in interactive applications when the - embedding e.g. level determines cursor display. - -In any of the output pointers == NULL, then that information is not -calculated. - -How it looks like -================= - -Have a look at tests directory, to see some input and outputs, which -CapRTL charset means that CAPITAL letters are right to left, and digits -6, 7, 8, 9 are Arabic digits, try 'fribidi --charsetdesc CapRTL' for the -full description. - -Executable -========== - -There is also a command-line utilitity called fribidi that loops over -the text of a file and performs the BiDi algorithm on each line, also -used for testing the algorithm. Run fribidi with the --help option to -learn about usage. The command-line utility is known to have problems -with line-breaking and ltov/vtol lists. - -Bugs and comments -================= - -Report GNU FriBidi bugs at: - - http://fribidi.org/bug - -And send your comments to: - - fribidi@freedesktop.org - - -Behdad Esfahbod -behdad@gnu.org - -Dov Grobgeld -dov.grobgeld@gmail.com diff --git a/README b/README new file mode 120000 index 0000000..42061c0 --- /dev/null +++ b/README @@ -0,0 +1 @@ +README.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..faa53fe --- /dev/null +++ b/README.md @@ -0,0 +1,174 @@ +# GNU FriBidi + +The Free Implementation of the [Unicode Bidirectional Algorithm]. + + +## Background + +One of the missing links stopping the penetration of free software in Middle +East is the lack of support for the Arabic and Hebrew alphabets. In order to +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. + +See [`HISTORY`](./HISTORY) on how the project started and evolved. + + +## Audience + +It is our hope that this library will stimulate the implementation of Hebrew and +Arabic support in lots of Free Software. Here is a small list of projects that +would benefit from the use of the GNU FriBidi library, but of course there are +many more: Wine, Mozilla, Qt, KDE, lynx, OpenOffice. + +GNU FriBidi is already being used in projects like Pango (resulting in [GTK+] and +[GNOME] using GNU FriBidi), AbiWord, MLTerm, MPlayer, and BiCon. + +See [`USERS`](./USERS) for a list of projects using GNU FriBidi. + + +## Dependencies + +Currently GNU FriBidi does not depend on any other library, but uses Glib if +available. It uses GNU Build System for build and installation on POSIX systems. + + +## Downloading + +The latest version of GNU FriBidi may be found at: + + + +## Building + +Start with running the [`bootstrap`](./bootstrap) script and follow the +isntructions. + + +## License + +GNU FriBidi is Free Software; you can redistribute it and/or modify it under the +terms of the [GNU Lesser General Public License] as published by the Free Software +Foundation; either version 2.1 of the License, or (at your option) any later +version. + +GNU FriBidi is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public License along +with GNU FriBidi, in a file named COPYING; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +For licensing issues, contact . + + +## Implementation + +The library implements the algorithm described in the "Unicode Standard Annex +\#9, The Bidirectional Algorithm", available at +. + +The library uses Unicode (UTF-32) entirely. The character properties are +automatically extracted from the Unicode data files, available from +. This means that every Unicode +character is treated in strict accordance with the Unicode specification. + +There is a limited support for character set conversion from/to the UTF-32 +encoding. Data in these character sets must be converted into UTF-32 before the +library may be used. iconv(3) can always do a better job on that, so you may +find that the character sets conversion code is typically turned off on POSIX +machines. + + +### Conformance Status + +GNU Fribidi has been tested exhaustively against the [Unicode Reference Code], +and to the best of our knowledge, it completely conforms to the specification, +always producing the same result as the Reference Code, except for [Mirroring] +additions, introduced in Unicode 6.3.0 of the specification. + + +### API + +The reordering of characters is typically done through the function: + +```c +fribidi_boolean fribidi_log2vis( + /* input */ + FriBidiChar *str, + FriBidiStrIndex len, + FriBidiCharType *pbase_dir, + /* output */ + FriBidiChar *visual_str, + FriBidiStrIndex *position_L_to_V_list, + FriBidiStrIndex *position_V_to_L_list, + FriBidiLevel *embedding_level_list +) +``` + +Where... + +* `str` is the Unicode input string. +* `len` is the length of the Unicode string (`str`). +* `pbase_dir` is the input and output base direction. If `pbase_dir == + FRIBIDI_TYPE_ON` then `fribidi_log2vis()` calculates the base direction on its + own, according to the bidi algorithm. +* `visual_str` is the reordered output unicode string. +* `position_L_to_V_list` maps the positions in the logical string to positions + in the visual string. +* `position_V_to_L_list` maps the positions in the visual string to the + positions in the logical string. +* `embedding_level_list` returns the classification of each character. Here, + even numerical levels indicate LTR characters, and odd levels indicate RTL + characters. The main use of this list is in interactive applications where, + for example, the embedding level determines cursor display. + +If any of the output pointers is equal to `NULL`, then that information is not +calculated. + + +## How it looks like + +Have a look at [`test/`](./test) directory, to see some input and outputs. + +The `CapRTL` charset means that CAPITAL letters are right to left, and digits +6, 7, 8, 9 are Arabic digits, try 'fribidi --charsetdesc CapRTL' for the full +description. + + +## Executable + +There is also a command-line utilitity called `fribidi` that loops over the text +of a file and performs the bidi algorithm on each line, also used for testing +the algorithm. + +Run `fribidi --help` to learn about usage. + +The command-line utility is known to have problems with line-breaking and +logical-to-vertical/vertical-to-logical lists. + + +## Bug Reports and Feedback + +Report bugs and general feedback at: + +The mailing list is the place for additional technical discussions and user +questions: + + +## Maintainers and Contributors + +* Dov Grobgeld +* Behdad Esfahbod + +See also [`AUTHORS`](./AUTHORS) and [`THANKS`](./THANKS) for the complete list +of contributors. + + +[Unicode Bidirectional Algorithm]: https://www.unicode.org/reports/tr9/ +[Unicode Reference Code]: https://www.unicode.org/reports/tr9/#Reference_Code +[Mirroring]: https://www.unicode.org/reports/tr9/#Mirroring +[GTK+]: https://www.gtk.org/ +[GNOME]: https://www.gnome.org/ +[GNU Lesser General Public License]: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html -- cgit v1.2.1