Introduction

libLASi is a library written by Larry Siden that provides a C++ stream output interface (with operator <<) for creating Postscript documents that can contain characters from any of the scripts and symbol blocks supported in Unicode and by the Pango layout engine. The library accommodates right-to-left scripts such as Arabic and Hebrew as easily as left-to-right scripts. Indic and Indic-derived Complex Text Layout (CTL) scripts, such as Devanagari, Thai, Lao, and Tibetan are supported to the extent provided by Pango and by the OpenType fonts installed on your system. All of this is provided without need for any special configuration or layout calculation on the programmer's part.

Although the capability to produce Unicode-based multilingual Postscript documents exists in large Open Source application framework libraries such as GTK+, Qt, and KDE, libLASi was designed for projects which require the ability to produce Postscript independent of any one application framework. This document outlines the motivation and strategy employed in the development of LASi.

LASi is mature software with no further features planned, but because of sustained user interest over the years we still actively maintain it. For example, we highly recommend the latest release of LASi because of the bug fixes that release contains. For more details about that release (version 1.1.3 released on 2019-02-01) please see the news item and file release area (including release notes) for that release.

SourceForge Resources

The following SourceForge resources for LASi should be of interest to users of that software.

Font Resources

The example programs included with LASi contain Unicode text in various languages. To obtain Open Source and otherwise liberally-licensed fonts required for proper generation of the example Postscript output, you will likely need to install some additional font packages from your free software distribution. For a guide to what fonts are generally available for such distributions, please visit The Unicode Font Guide For Free/Libre Open Source Operating Systems.

Free Software Distributions Provide the LASi Dependencies

Free software distributions that are an integral part of any modern Linux or similar free *nix operating system or which are add ons to proprietary operating systems (e.g., the Fink, MacPorts, and Homebrew distributions for Mac OS X and the the Cygwin and MinGW-w64/MSYS2 distributions for Windows) are the recommended way for users to gain access to the LASi software dependencies. For such distributions, users need to install packages for CMake (version 3.13.2 or higher), pkg-config, native build tools that depend on the chosen CMake generator, a C++ compiler (likely g++, the C++ front end to the GNU compiler collection), font packages that allow rendering the particular Unicode glyphs in the examples, and optionally (if the user wants to build the LASi documentation) doxygen. Users also need to install development packages for the Pango and FreeType libraries which are direct dependencies of the LASi library. They also need to install all packages that are dependencies of the packages that are named here, but the the package installation software provided by the free software distributions should automatically take care of that issue.

General Build Instructions for LASi

The LASi source tree includes a CMake-based build system so you can use a general cross-platform procedure to configure, build, test the build, install, and test the install of this software. This general procedure consists of using the cmake executable to choose a generator, installation prefix, and whether the library build will be shared or static; configure build system targets; and for the chosen native build system that is configured by the generator build the "all" target, optionally test that result by running ctest (which is distributed as part of the CMake software), and install the software by building the "install" target. As an additional option that install can be tested by building the installed examples that are linked with the installed library and its dependencies using pkg-config. To facilitate this test we configure and install a special Makefile to implement building the examples this way. That Makefile also implements targets for run-time testing the examples that are built.

Depending on the platform and chosen generator, there are many ways that experienced CMake users should be able to implement the above general procedure. However, for those less experienced with CMake, we suggest they install cmake, pkg-config, the bash shell, the distribution make command, and g++ and use the following "Unix Makefiles" specific form of the above general procedure that should work well for all platforms provided that you use the free software distributions available for those platforms.

Create an empty build directory and change your current directory to that directory:
mkdir build_dir
cd build_dir
Configure LASi using cmake:
cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=<path to the install prefix> -DBUILD_SHARED=<ON or OFF> \
<path to the top-level directory of the source tree> >& cmake.out

The -G option lets the user choose a cmake generator, the -DCMAKE_INSTALL_PREFIX option lets the user choose an install prefix, and the -DBUILD_SHARED option lets the user choose to build LASi as a shared library (ON) or as a static library (OFF).
Build LASi:
make all >& all.out

Afterwards, use a good PostScript viewer to look at the generated Encapsulated PostScript results in examples/*.eps to check for missing glyphs (designated by empty boxes) in all but examples/MissingGlyphExample.eps which is the result from an example that is designed to have missing glyphs to test that empty boxes are rendered in that case. If any but that example result have missing glyphs, then you should install additional font packages from your free software distribution to address that issue.
Optionally test that build of LASi:
ctest >& ctest.out

Afterwards, use the cmp or diff commands to verify that the generated ctest results (in examples/ctest_examples_output_dir/*.eps) are identical to the "make all" results (in examples/*.eps).
Install LASi:
make install >& install.out
Optionally test that install of LASi using the specially configured installed Makefile:
cd <path to the install prefix>/share/lasi<latest LASi version>/examples
make all >& all.out

Afterwards, use the cmp or diff commands to verify that these "make all" results (in *.eps) are identical to the "make all" results in the build tree (located in examples/*.eps in that tree).

Note, that for most of the above steps, the combined stderr and stdout output is captured in various *.out files. For each such step the user should inspect those files for any warning or error messages before proceeding to the next step.

Platform Specific Notes

At this stage we have no platform-specific notes. The reason for this is we are reasonably confident that if users follow the "Unix Makefiles" procedure for most any free software distribution, that procedure will "just work". This confidence is based on years of experience building and testing PLplot (whose build is much more complex than that of LASi and whose psttf device driver depends directly on the LASi library and indirectly on its dependencies) on many free software distributions (including the Mac OS X and Windows ones) using a procedure that is quite similar to the "Unix Makefiles" procedure; good test results on Linux, Mac OS X, and Windows for older releases of LASi using variants of the general CMake-based procedure above; and good results on Linux (specifically Debian Testing) for the recommended "Unix Makefiles" procedure for the latest release of LASi.

That said, if you have trouble building LASi, the usual culprits are:

CMake version problems. You need version 3.13.2 or later to build LASi. (Otherwise, the cmake step in the "Unix Makefiles" procedure will error out). The latest versions of most free software distributions should provide CMake version 3.13.2 or later, but if not or if you are using an older distribution, then we recommend you build 3.13.2 or later from CMake source code using the older version of cmake that your distribution provides using the same "Unix Makefiles" procedure that we recommend for LASi. Then follow up by building LASi with your newly built version of CMake using the same "Unix Makefiles" procedure.
Dependencies not installed. If you do not install the LASi dependencies from your free software distribution, the cmake step in the "Unix Makefiles" procedure will error out in most cases or else produce a warning when the missing dependency is not critical). So it is important to review the cmake.out output from the cmake step to confirm you have the correct packages installed.

Note that if you have solved all cmake version problems and installed all dependencies, and you still do not get good results for the latest release of LASi for using the above "Unix Makefiles" procedure for any free software distribution, we would like to hear from you (preferably on our mailing list).

API Documentation

Note: The doxygen documentation generated when you build LASi will be more up-to-date than the documentation here. However the API changes very little so the differences will be few:

LASi Public Interfaces

Examples

Examples are provided in the examples subdirectory of the LASi source tree. The file Makefile.examples.in that appears in that subdirectory is a configurable template for a Makefile (installed with our installed examples) that illustrates how to link a program against LASi. Here is a simple example of what source code using LASi looks like.

Original Author

Larry Siden lsiden@gmail.com is the original author of LASi.

Project Maintainers and Development Staff

Please visit http://sourceforge.net/projects/lasi/ for the most current information regarding project maintainers and development staff.

Credits

Ed would like to sincerely thank Larry Siden for producing such an elegant and simple-to-use software interface.
Ed would also like to thank Ritu Khanna for her interest and help in resolving bugs in the software and installation scripts.
All of us would also like to thank Dr. Julia Richards of the Kellogg Eye Center at the University of Michigan Medical Center for providing us the opportunity and support to work on this project.

Colophon

My friend, Ed Trager, who first envisioned and motivated me to write LASi, suggested that I assign the name "Lasi" to this project, as "Lasi" is composed of the first two letters of my first name, Larry, followed by the first two letters of my last name, Siden. Since this immediately delighted by own sense of vanity, I had no trouble indulging Ed. Out of concern that the name "Lasi" might invite ridicule by jealous programming rivals who would no doubt take every opportunity to mock it's connection to the beloved TV canine hero, I changed it's spelling to the post-modern, hi-tech moniker "LASi".

top