R2L: helper packages for biditext
"""

Q: What is R2L?

A: R2L is a package which contains biditext, along with a couple of accessory
programs.

Q: What is biditext?
A: biditext is a library that adds a degree of bidirectional (bidi) support to
any X program. This means that an X program that is run under biditext
will display hebrew text properly, and not "reversed".

Q: What else is in the package?
A: The package also includes:

 - r2l programs (r2l, r2lgnomeapplet, r2ldockapp, r2lterminal, r2ltcl). 
   Those programs control the behaviour of runing copies of the biditext 
   libraries (e.g: allow you to disable biditext temporarily if it confuses 
   you).

 - refreshd: Whenever an r2l program enables or diables biditext, the changes
   are only visible when that window gets refreshed. refreshd (Refresh Daemon)
   refreshes the relevant windows automatically.

 - r2llib: The library that provides the interface used by biditext and r2l
   clients. Useful if you want to write your own r2l program.

Q: Is It Free
A: Yes. The package r2l is available under the terms of the GNU GPL/LGPL (see
Legal below) and can bedownloaded and used for no extra cost. We hope you'll
find it useful.

Building
""""""""
You should have the fribidi library installed. See http://fribidi.sf.net/ if
you don't have it.

Optionally you should have a gnome building environment (either the source
tree itself, or the rpm package 'gnome-core-devel' or an equivalent) to build
the gnome applet and libdockapp (from the WindowMaker distribuition) to build
the dock applet.

Then you run the usual:

  ./configure
  make
  make install (may require root permissions)

Note, however, that the configure script is still a very partial one.
Specifically, it will ignore the option '--prefix'.

If you want to build with a prefix other than /usr/local, you should pass a
parameter to make (on each time you run make). e.g:

  make install PREFIX=$HOME 

to install it under your home directory.

Some useful options of the configure script:

  --disable-refreshd (don't build refreshd, in case it gives you trouble)

  --disable-plugins (if you don't want to build all the r2l clients)

  --disable-dynamic-fribidi (build with fribidi static)

  --enable-dynamic-libdockapp (build with libdockapp dynamic)

It is known to build well on linux (Mandrake 8.1, Redhat 6.2) and Solaris 8
(there is an issue with the system's 'install' use ginstall instead, if
available). On cygwin It probably compiles, but will have no effect, because
Xlib there is statically linked.


Using
"""""

If you want to run a program under biditext you simply run 'biditext
command_line' . For instance, to run licq:

  biditext licq 

or:

  biditext licq -p qt-gui

This will run the program (licq in this case) with biditext.so loaded. 
biditext.so has code that hijacks every call to the X-Windows routines that 
draw text on the screen and "reverses hebrew" in that text, if necessary. 

Biditext can be disabled temporarily. You can also control the base
directionality of the way bidi is performed. Those changed normally don't
affect strings that already displayed on the screen.

See biditext (1) for more details.

If you want programs to automatically refresh when you give such a control
instructions, you should use refreshd. refreshd is a daemon process, that runs
in the background (so you can run it, e.g., in your .xinitrc).

You should first run:

  refreshd &

After that you can run:

  biditext --auto-refresh licq

Now this licq will update automatically whenever you modify the bidi status
(e.g: by running 'r2l s'

See refreshd (1) for more information.


All Build Options
"""""""""""""""""

  --x-includes=DIR

    Look for X-windows header files in DIR 

  --x-libraries=DIR

    Look for X-windows library files in DIR
    

  --with-fribidi-prefix=PFX

    Directory under which fribidi is installed

  --with-fribidi-exec-prefix=PFX

    Directory in which fribidi-config can be found

  --disable-dynamic-fribidi

    Link fribidi staticly. Note that on certain platforms (e.g: solaris 8)
    this produces a link-time error with biditext.so and can't be used.


  --disable-refreshd

    Disable building of the refresh-daemon

  --enable-debug-refreshd

    Build refreshd with the option -DNOISY. This will log debug messages to
    syslog.


  --disable-plugins

    Don't build r2l-plugins (r2lterminal, r2lgnomeapplet, r2ldockapp)


  --disable-gnome

    Don't build the gnome applet (avoids running a test for the existance of
    gnome libs). Gnome support is only required for building r2lgnomeapplet.

  --with-gnome-prefix=PFX
  --with-gnome-exec-prefix=PFX

    similar to the ones for fribidi

  --with-libdockapp-prefix=DIR
  --with-libdockapp-headers=DIR
  --with-libdockapp-libs=DIR

    Get libdockapp from <prefix>/include , <prefix>/lib or specify libdockapp
    headers and libraries directory.
    Libdockapp is only required for building r2ldockapp.

  --enable-dynamic-libdockapp

    By default libdockapp is linked statically, as it is not common. However,
    if you build this for your personal system, there is no reason to avoid
    linking to libdockapp dynamically.


  --with-tcltk-program=PROG

    Use PROG as the tcl/tk interpeter. Typically this is 'wish', and normally
    it is automatically detected. This allows you to override the automatic
    detection, or to add a program that is not on the path or with a standard
    name.
    A tcl/tk interpeter is only needed for running r2ltcl .


  --prefix
  --bindir
  --libdir
  --mandir
  ...

    IGNORED!

    Sorry, the current makefiles don't support setting the prefix from the
    configure script. Use:

      make PREFIX=<prefix>

    e.g.:

      make PREFIX=$HOME

      make PREFIX=/tmp/root MANDIR=/tmp/root/share/man

      (BINDIR and LIBDIR can probably be overriden as well)

    Or patch the makefiles and send me the patch ;-)

Known Problems:
""""""""""""""
* No man page for r2l{terminal|dockapp|gnomeapplet|terminal}
* No documentation for r2llib 
* If a gtk program running under biditext crashes immidietly, the cause maybe
  incompatibility of the library fribidi. Try rebuilding the fribidi library,
  or upgrading to fribidi >= 0.10.1
* 'make test' builds some test programs of refreshd. However the last one of
  them (test_refreshd_cnt) fails to build.
* Only biditext.so is stripped. Other programs/libraries are not stripped.


Legal Stuff
"""""""""""
biditext:    (c) Matan Ziv-Av and Ilya Konstantinov. 
r2llib:      (c) mulix
r2l-plugins: (c) Guy Keren
refreshd:    (c) Emil Dan Kohn
Other files: (c) Tzafrir Cohen

The files in this package are availalbe under the terms of the GNU GPL,
version 2.1 . A copy of that license is availalbe from
http://www.gnu.org/licenses/gpl.txt
As an exception to that, the sources of biditext.so, refreshd_hook.so , 
r2llib.a and refreshd_cnt.a  are licensed under the terms of the GNU LGPL. A
copy of that license is available from:
http://www.gnu.org/licenses/lgpl.txt

Also note that we give you NO WARANTY as for the behaviour of r2l. We wrote
this package to be a non-harmful package, but we will take no responsibility
should any of the components of this package starts to distort your display,
erase your files, chew-up your network bandwidth or any other action.


Contact
"""""""
R2L Is a project of the Haifa Linux Club (http://linuxclub.il.eu.org/) .

The homepage is http://www.technion.ac.il/~tzafrir/R2L/

The relevant mailing list is lin-prj@vipe.technion.ac.il . See:
http://linuxclub.il.eu.org/#MailingList


      Tzafrir Cohen <tzafrir@technion.ac.il>
