Three examples that use libLASi
===============================

This directory contains three examples that use libLASi.  Below we comment
on each of these examples, comment on the structure of the resulting
postscript files, and then give the build instructions for all examples.

Missing Glyph libLASi Example (Example0)
========================================

The example C++ program, "MissingGlyphExample.cpp" is built into the
executable, example0.  This example renders UTF-8: 0xE2 0xAB 0xB4 = Unicode:
U+2AF4 = "Triple vertical bar binary relation" through 0xE2 0xAB 0xB8 =
Unicode: U+2AF8 = "TRIPLE NESTED GREATER-THAN". We have determined
experimentally that this range of 5 math glyphs is rarely defined on most
systems so the point of this example is to test how your system responds to
missing glyphs.  The correct response should be a rendering of an empty box
for each undefined glyph. Some older versions of libLASi generate an
incorrect showstopping error for undefined glyphs so this is a test for this
potential regression.

Simple libLASi Example (Example1)
=================================

This example C++ program, "SimpleLASiExample.cpp" is built into the
executable, example1.  This example renders "Hello" in Arabic, English,
Hebrew, and Hindi. Be sure to obtain the fonts listed in the source code, or
substitute others present on your machine.  See
http://www.unifont.org/fontguide/ to obtain the Open Source fonts specified
in the program if you need them. "Example_1_Result.png" will show you what
the resulting Postscript should look like.

Complex Text Layout libLASi Example (Example2)
==============================================

This example C++ program, "ComplexTextLayoutExample.cpp" is built into the
executable, example2. This example demonstrates a few additional features of
libLASi and also demonstrates the layout of complex text layout (CTL)
scripts such as Arabic and Indic scripts via Pango. This example prints
strings in English, Hebrew, Arabic, Thai, Japanese, Bengali, and Cyrillic:
Be sure to obtain the fonts listed in the source code, or substitute others
present on your machine. See http://www.unifont.org/fontguide/ to obtain the
Open Source fonts specified in the program if you need them.
"Example_2_Result.png" will show you what the resulting Postscript should
look like.

Structure of the PostScript Files Resulting from libLASi
========================================================

The key thing to notice in these example results is that libLASi divides a
Postscript document into three parts: a header, a body, and a footer.  These
three parts correspond directly to the document structure that you will
usually find in a well-structured Postscript document.

As shown in the example results, the header can contain Postscript
convenience procedures that have been defined by the user to ease layout.
The header will also contain all of the glyph outline procedures needed to
draw the text of the document. Be sure to examine the Postscript output to
see what these glyph procedures look like.

The body contains the text that we want to print.  Here the "gsave" and
"grestore" operators are used so that we can change the graphics state --
color, rotation, translation, and so on -- and get back to the original
state after we are done.

Also notice the use of libLASi's setFont(), setFontSize(), and show()
methods. These methods should remind you of the Postscript "setfont", "show"
and related commands. But of course here we use libLASi's methods so we can
manage Unicode text printed using TrueType and OpenType fonts.  Notice that
all of the strings are simply null-terminated UTF-8 strings. 

Another thing to notice is that we also use libLASi's get_dimensions() method
to obtain a "lineSpacing".  We then define a Postscript "newLine" routine
that uses the "lineSpacing" value we got from libLASi.

Finally the footer can contain any additional Postscript Document
Structuring Conventions, such as the "%%Pages:" directive.

Building the Three Examples
===========================

The Makefile uses "pkg-config" to determine the proper location of headers
and libraries for libLASi and the libraries that it requires. Pkg-config is
available for Linux, Mac OS X, and Windows. If you have problems, make sure
the environment variable PKG_CONFIG_PATH mentioned in the Makefile is
modified to include (colon-separated) paths to the "freetype2", "pango.pc",
and "panggoft2.pc" files.  Usually this will be in /usr/lib/pkgconfig,
/usr/local/lib/pkgconfig, or $PREFIX/lib/pkgconfig where $PREFIX is an
installation prefix that you set up when configuring Pango.

To compile the example0, example1, and example2 executables and generate 
the corresponding example0.ps, example1.ps, and example2.ps postscript
results, type:

   make

We hope you enjoy using libLASi!

2008-02-07: ET, AWI
