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.

MissingGlyphExample
===================

The example C++ program, "MissingGlyphExample.cpp" is built into the
executable, MissingGlyphExample.  This example renders the following
self-explanatory lines of text:

      "Display range of glyphs (chosen such that one or more of them normally are missing or",
      "correspond to pure bitmapped fonts) to verify that libLASi does something with low",
      "impact in these cases, i.e., uses the default replacement glyph (normally an empty box)",
      "for all freetype errors generated by missing glyphs or pure bitmap fonts that are",
      "unsuitable for libLASi needs.",
      "",
      "Unicode U+0802 SAMARITAN LETTER GAMAN: ࠂ",
      "Unicode U+08AA ARABIC LETTER REH WITH LOOP: ࢪ",
      "Unicode U+2AF4 TRIPLE VERTICAL BAR BINARY RELATION: ⫴", 
      "Unicode U+2AF5 TRIPLE VERTICAL BAR WITH HORIZONTAL STROKE: ⫵", 
      "Unicode U+2AF6 TRIPLE COLON OPERATOR: ⫶", 
      "Unicode U+2AF7 TRIPLE NESTED LESS-THAN: ⫷", 
      "Unicode U+2AF8 TRIPLE NESTED GREATER-THAN: ⫸", 
      "Unicode U+1010A AEGEAN NUMBER FOUR: 𐄊",
      "Unicode U+1F70A ALCHEMICAL SYMBOL FOR VINEGAR: 🜊",
      "Unicode U+2648 ARIES (twice): ♈♈",
      "Embedded newlines a\\nb\\nc: a\nb\nc"

Currently, only the last two lines generate empty boxes on my (AWI's)
Debian Buster platform.

For the line with the two Aries glyphs, pango selects the popular Noto
Color Emoji glyph to render those glyphs, but that pure bitmap font is
completely unsuitable for libLASi which only works for outline fonts.
This example demonstrates that instead of erroring out, libLASi does
something with low impact for such a pure bitmapped font case and
replaces each Aries glyph with the default replacement glyph (empty
box).

For the line with the two embedded line feeds, pango selects an outline
font that would normally be suitable for use by libLASi.  However,
this non-printing glyph does not exist for that font (which is likely
to always be the case for all non-printing glyphs for all fonts).
This example demonstrates that instead of erroring out, libLASi does
something with low impact for this missing glyph case and replaces
each requested linefeed glyph with the default replacement glyph
(empty box).

SimpleLASiExample
=================

This example C++ program, "SimpleLASiExample.cpp" is built into the
executable, SimpleLASiExample.  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.

ComplexTextLayoutExample
========================

This example C++ program, "ComplexTextLayoutExample.cpp" is built into
the executable, ComplexTextLayoutExample. 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.

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 libLASi's get_dimensions()
method to help determine the overall bounding box of these examples.
That method also returns a "lineSpacing".  For certain cases we define
a Postscript "newLine" routine that uses that value to determine the
spacing between lines.

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

Building the three examples in the core build tree
==================================================

In the core build tree, the user should configure libLASi with cmake
and build targets using one of the CMake backends such as the "make"
command.  Building the "all" target builds the library and examples,
and runs those examples in the examples subdirectory of the build tree
to generate <example name>.eps EPS (Encapsulated PostScript) files and
possibly (if inkscape is available to do the conversion) <example
name>.png PNG files (where <example name> is one of
MissingGlyphExample, SimpleLASiExample, or ComplexTextLayoutExample).
The (possible) inkscape conversion from EPS to PNG form is done
using

inkscape --export-background=\#ffffff --file=<example name>.eps --export-png=<example name>.png

The --export-background option is to impose a white background since
the EPS result has no background.  The result of this conversion is a
high-quality bitmap representation of the EPS results.  Note that
inkscape is capable of other format transformations as well (e.g., to
SVG format).

Note such build-time EPS and PNG results are always generated in the
build tree, and the PNG files examples/<example name>.png *in the
source tree* are recent (Debian Buster) snapshots of those build-tree
results which should be a good visual comparison for build-tree EPS
and PNG results that users obtain on their own platforms by building
the "all" target.

Building the three examples in the installed examples tree
==========================================================

In the installed examples tree we use a traditional Makefile +
pkg-config approach to build and run the examples.  The Makefile uses
"pkg-config" to determine the proper location of headers and libraries
for libLASi and the libraries that it requires. The pkg-config command
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.

For the installed examples case

make all

should build all the installed examples and run them to produce
<example name>.eps results, (where <example name> is
MissingGlyphExample, SimpleLASiExample, or ComplexTextLayoutExample).

The files <example name>.png in the installed example directory are
automatically installed from the source tree.  These PNG files have
been generated by inkscape from a recent (Debian Buster) snapshot of
the EPS files <example name>.eps.  This PNG form of recent EPS results
should make a good visual comparison for installed examples EPS
results that users obtain on their own platform with the above make
command.

We hope you enjoy using libLASi!
