
Install
-------

Just do the usual ./configure; make; make install
Of course you need the GGI libraries installed, and optionnally freetype. Well,
if you don't have freetype you lose much of the ggiterm reason for being, but
it could still be useful for embedded use...
If you have the libggiwmh extension installed, ggiterm will use it to display
the app's name in the window's title bar instead the the default title. This is
useful only on windowed targets, like X-Window or Windows.


Post-install
------------

For ggiterm to function properly, you must add the ggiterm entry to your
system's terminal capabilities database.
Depending on your system, you will have to either (as root):
	- run the command "tic ggiterm.terminfo"
	- add the contents of ggiterm.termcap to your termcap file (or edit the
	  existing entry)

NOTE: if you are upgrading from version <= 0.6.2, don't overlook this step! The
      ggiterm entry has been significantly reworked for 0.7.0, and using an old
      entry with a newer version can give unexpected results...


Running ggiterm
---------------

CAVEAT: ggiterm has been tested only at color depths >= 8.

ggiterm --help will tell you about the available runtime arguments.
Without specifying any, you will be stuck with the default rendering options,
which won't be very impressive: plain ASCII, the default GGI font, etc...

Setting the --font option to your preferred * FIXED WIDTH * True Type font will
give much better results!
I suggest Microsoft Courier New (widely available), or monofur from Tobias
Kohler (much more fun and available for free at http://www.dafont.com).
Both have graphical drawing characters and allow underlining. Another great
font I found recently is Fixedsys Excelsior (http://www.fixedsys.org).

If you get a message like "Unknown terminal type" when running a terminal-based
application (vi, emacs, ...) from within ggiterm, this is because your host
doesn't have a ggiterm entry in its terminal capabilities database (see
Post-Install section). In this case, setting the TERM environment variable to
"vt100" prior to launching your application will allow it to run, however with
reduced features (eg. no colors).


Framebuffer
-----------

If you run ggiterm on a framebuffer-like target, make sure the current mode
leaves enough video memory to hold a virtual screen twice as big as the visible
area. Otherwise ggiterm will not be able to scroll with ggiSetOrigin() and
will fall back to ggiCopyBox(), which is unbearably slow on unaccelerated
targets.

The math is simple: a 1024x768 framebuffer with 16 bits color depth uses up
1024 x 768 x 2 = 1572864 bytes of memory (1.5 Mb). So in this case you need at
least 3 Mb of video memory to get a decent speed.


Known bugs
----------

You may notice a little flickering during scrolling operations under the X
target. This is because offscreen contents are not cached by the X server and
have to be retrieved from the GGI backbuffer each time ggiterm reaches the
bottom of its virtual screen.
Maybe one day GGI will provide an option to enable backing store, but for now
you have to manually tell the X server to do it by default.
For X.org or XFree86 this can be done with the +bs option:
 $ startx -- +bs
or specify
 /usr/X11R6/bin/X +bs
as the X server in your graphical login manager (xdm, gdm, kdm, etc...)


Troubleshooting
---------------

ggiterm is built by default without debugging support. If anything goes wrong,
recompile with ./configure --enable-debug, and run ggiterm with --debuglevel set
to the relevant value (see man page). Be warned, the log can be HUGE, so it is
recommended to redirect the output to a file in order to get a decent speed.
Then email me the debugging output with a description of the problem, I'll try
to fix it.

dedale1@users.sourceforge.net
