Read Me

libLASi Release 1.1.3
~~~~~~~~~~~~~~~~~~~~~
This is a maintenance release of libLASi that reflect the ongoing
efforts of the libLASi developers to respond to bug reports for this
stable and convenient library for creating PostScript documents that
can contain characters from any of the script and symbol blocks
supported in Unicode and by the Pango layout engine.

If you encounter a problem with libLASi, then please send a bug report to
the libLASi developers via the lasi-devel mailing list described at
http://lists.sourceforge.net/lists/listinfo/lasi-devel.

Please see the license under which this software is distributed (LGPL), and
the disclaimer of all warranties, given in the COPYING.LIB file.

INDEX

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility
1.2 Backwards-incompatible libLASi API changes
1.3 Need help getting rid of deprecation build warnings

2. Changes relative to our previous release (version 1.1.2) in decreasing order of importance

2.1  Improve libLASi's response when pango/fontconfig chooses pure bitmapped fonts
2.2  Make glyph names have a one-to-one relationship with glyphs
2.3  Set target property POSITION_INDEPENDENT_CODE ON for the libLASi library
2.4  Make "MissingGlyphExample" a more stringent test of font or glyph issues for libLASi
2.5  Replace deprecated lower-case variants of Freetype macro constants with preferred upper-case form
2.6  Add bounding boxes to the "MissingGlyphExample" and "ComplexTextLayoutExample" examples
2.7  Rename example applications and results using consistent and descriptive core names
2.8  Fix low-resolution boundary box issue
2.9  Update doxygen configuration files from doxygen version 1.8.1.2 to 1.8.13
2.10 Change the minimum version of CMake from 2.8.9 to 3.13.2

3. Testing of this release.

END of INDEX

1. OFFICIAL NOTICES FOR USERS

1.1 CMake version compatibility

    Our build system is implemented using CMake.  The minimum version
    of CMake we allow is 3.13.2 on all platforms.  That version is the
    one we have used to test this release of libLASi (see Section 3
    below).  However, if you try later CMake versions as they are
    released during the life of this libLASi release, our build system
    will likely continue to work well because CMake has an excellent
    reputation for preserving backwards compatibility.

1.2 Backwards-incompatible libLASi API changes

    The bug fixes in this release required backwards-incompatible
    changes to the libLASi API (a change in the argument list of the
    PostscriptDocument::GlyphId::GlyphId protected method that is
    designed for internal use only and the addition of the
    PostscriptDocument::PangoItem_do protected method that is also
    designed for internal use only).  Therefore, the SOVERSION for
    libLASi has been bumped from 1 to 2 to force source code that
    depends on this library (e.g., the PLplot psttf device driver) to
    be recompiled.  However, such source code will not require changes
    to adjust to this backwards-incompatible change in the libLASi
    API.

1.3 Need help getting rid of deprecation build warnings

This release has deprecation warning build issues which are

* "warning: dynamic exception specifications are deprecated in C++11 [-Wdeprecated]"

* "warning: ‘PangoContext* pango_ft2_get_context(double, double)’ is deprecated: Use 'pango_font_map_create_context' instead [-Wdeprecated-declarations]"

* "warning: ‘FT_FaceRec_* pango_ft2_font_get_face(PangoFont*)’ is deprecated: Use 'pango_fc_font_lock_face' instead [-Wdeprecated-declarations]"

All of these are beyond my current C++ and pango skill level to fix so
help with cleaning up any of these deprecation build warnings messages
would be much appreciated!

2. Changes relative to our previous release (version 1.1.2) in decreasing order of importance

2.1  Improve libLASi's response when pango/fontconfig chooses pure bitmapped fonts

     This change was the primary motivation for this release.

     Previous to this change when pango chose the popular Noto Color
     Emoji font to help render the Aries glyph, libLASi threw an error
     and aborted since such pure bitmap fonts are not suitable for
     libLASi's outline font needs.  Such a response completely stops
     PLplot tests when PLplot standard example 7 attempts to render an
     Aries glyph with either the psttf or psttfc devices.  So this
     previous response was completely unacceptable, and the fix for it
     is important.

     This change fixes that previous response by replacing all glyphs
     for a PangoItem where pango chooses a non-outline font with the
     default glyph used to represent missing glyphs.  Of course, a
     much better procedure would be to request pango to limit its
     choices to outline fonts, but as far as I know there is no method
     for doing that (outside of having one fontconfig configuration
     for libLASi use and another for all other situations), and, in
     any case, the present workaround is "good enough for now" because
     pure bitmap fonts are rare (for example, it is possible that Noto
     Color Emoji in the future may become available in the outline
     form generally preferred for modern fonts), and Pango/fontconfig
     chooses such pure bitmap fonts for relatively few glyphs.

2.2  Make glyph names have a one-to-one relationship with glyphs

     This change is an important motivation for this release.

     This change is confined to the case when fonts don't follow
     standards so that they cannot be interrogated for the glyph name,
     i.e., FT_HAS_GLYPH_NAMES(face) is false.  Before this change,
     libLASi computed its own unique glyph name using the template

LASi_glyph_<unique number>

     where <unique number> was incremented whenever the code decided a
     new glyph had been encountered.  This scheme had the following
     disadvantages:

*    The logic for deciding when new glyphs were encountered was
     faulty with the result that the same glyph would have multiple
     glyph names and therefore redundant glyph information stored in
     the PostScript header whenever, for example, both

doc.osBody() << show(string)
  
     and

doc.get_dimensions(string,&lineSpacing,&xAdvance,&yMinimum,&yMaximum);

     (a common combination when bounding boxes are being determined)
     were called for the same string.

*    The glyph name depended on the order with which strings were
     processed with the result that PLplot octave results (where all
     standard octave examples were run from one instance of octave)
     had different glyph names than PLplot C results (where all
     standard C examples were run using separate executables for each
     example).

*    The glyph names were completely meaningless to humans reading
     through the PostScript code in the results.

     All these issues were addressed by borrowing a static function
     from PLplot (whose LGPL'd code allows us to do that) to calculate
     the UCS4 (32-bit unsigned) encoding of unicode for each glyph
     encountered in the UTF-8 encoded input string.  With the result
     that the glyph names now have the template

LASi_glyph_U+<UCS4 hexadecimal code for the glyph>

     where by definition the UCS4 hexadecimal code completely
     identifies the glyph in a unique way which is easy to look up,
     e.g., with the gucharmap application.

     The net result of this change is the PLplot test_diff_device
     target for the case when -DPLPLOT_TEST_DEVICE=psttfc now gives a
     clean report for the first time ever.  So this change is an
     important one.

2.3  Set target property POSITION_INDEPENDENT_CODE ON for the libLASi library

     This change is an important motivation for this release.

     This bug fix allows the static version of libLASi to be used with
     shared builds of external software that depend on libLASi such as
     the PLplot psttf device driver.

2.4  Make "MissingGlyphExample" a more stringent test of font or glyph issues for libLASi

     The most important change here was to add

"Unicode U+2648 ARIES (twice): ♈♈"
"Embedded newlines a\\nb\\nc: a\nb\nc"

     to the strings that are rendered to PostScript by this example.

     For the first of these, the Debian Buster version of pango
     (likely due to the default fontconfig configuration) decides to
     use the popular Noto Color Emoji font to render the Aries glyphs,
     but the problem for that font is it is a pure bitmap font with no
     outline information that is required by libLASi.  So this line
     tests the response of libLASi to this situation.

     For the second of these the linefeed "\n" glyph is a non-printing
     glyph.  It appears for all such glyphs there is a "missing glyph"
     issue so regardless of future font improvements this line seems
     to be a reliable way to trigger missing-glyph issues to test the
     response of libLASi to this situation.

2.5  Replace deprecated lower-case variants of Freetype macro constants with preferred upper-case form

2.6  Add bounding boxes to the "MissingGlyphExample" and "ComplexTextLayoutExample" examples

     The resulting MissingGlyphExample.eps and
     ComplexTextLayoutExample.eps files join SimpleLASiExample.eps as
     being properly formatted EPS (Encapsulated PostScript) files.

     Note also that for the "Complex Text Layout" case, I implemented
     some generally useful C++ code macros (called
     LASI_SHOW_AND_UPDATE_BB, LASI_SCALED_SHOW_AND_UPDATE_BB, and
     LASI_ROTATED_SHOW_AND_UPDATE_BB), which made it straightforward
     to handle even complex cases such as determining the bounding box
     of text that has undergone anamorphic scaling or rotation.  For
     example, the LASI_ROTATED_SHOW_AND_UPDATE_BB macro includes C++
     code to apply the rotation matrix to determine the x,y
     coordinates of the corners of the rotated text box and use those
     corner coordinates to help determine the overall bounding box.

2.7  Rename example applications and results using consistent and descriptive core names

     Those core names are " MissingGlyphExample", "SimpleLASiExample",
     and "ComplexTextLayoutExample".  As a result the example source
     code name is <core name>.cpp, the example application name is
     <core name> (or <core name>.exe on Windows platforms), the EPS
     (Encapsulated PostScript) results are named <core name>.eps, and
     the PNG results (generated from the EPS results using inkscape)
     are named <core name>.png.

2.8  Fix low-resolution boundary box issue

     As a result of this change the low-res (int) BB (bounding box)
     limits are calculated from the high-res (double) BB limits with
     the appropriate combinations of floor and ceil so the low-res
     limits always lie on or outside (by up to but not including 1
     point) the high-res limits.  Previously this calculation was done
     incorrectly with floor for all limits.

2.9  Update doxygen configuration files from doxygen version 1.8.1.2 to 1.8.13

     These changes were done in the usual way by running the following
     commands:

doxygen -u Doxyfile.developer
doxygen -u Doxyfile.user

2.10 Change the minimum version of CMake from 2.8.9 to 3.13.2

     This change was motivated by the bug fixes in later CMake
     versions and also the much better checking of the build system
     that occurs for the policies automatically used for 3.13.2.

3. Testing of this release.

This release has been successfully built and run-tested (following the
prescription in README.Release_Manager_Cookbook) for both the shared
and static library case on Linux (Debian Buster) using CMake-3.13.2
(the minimum allowed version of CMake for libLASi), libpango-1.42.4,
libcairo-1.16.0, libfreetype-2.9.1, and libfontconfig-2.13.1.

This release has not been tested (yet) on Mac OS X or Windows
platforms, but we anticipate no difficulties on those platforms since
previous versions of libLASi have worked well on those platforms.  In
other words, the cross-platform nature of libLASi appears to have been
well supported by CMake in the past, and we feel that happy state will
continue with this release as well.

libLASi Release 1.1.2
~~~~~~~~~~~~~~~~~~~~~
This is a maintenance release of libLASi that reflect the ongoing
efforts of the libLASi developers to respond to bug reports for this
stable and convenient library for creating PostScript documents that
can contain characters from any of the script and symbol blocks
supported in Unicode and by the Pango layout engine.

If you encounter a problem with libLASi, then please send a bug report to
the libLASi developers via the lasi-devel mailing list described at
http://lists.sourceforge.net/lists/listinfo/lasi-devel.

Please see the license under which this software is distributed (LGPL), and
the disclaimer of all warranties, given in the COPYING.LIB file.

INDEX

1. Changes relative to our previous release (version 1.1.1).

2. Testing of this release.

1.1 Update of examples/MissingGlyphExample.cpp
1.2 #include FreeType headers in recommended (by FreeType) way.
1.3 Make all install locations configurable.
1.4 Fix FreetypeGlyphMgr::FreetypeGlyphMgr(FT_Glyph glyph) initialization bug.
1.5 Fix long-standing file repeatability issue.

1.1 Update of examples/MissingGlyphExample.cpp

The whole point of this example was to make sure that libLASi
responded well to missing glyphs, but the example had gotten seriously
outdated because for modern Linux systems with the normal system
fonts, the chosen unicode characters were no longer missing!  That
issue has now been addressed by using a larger variety of obscure
unicode glyphs in the examples based on some glyphs that gucharmap
says are missing for the particular Debian stable platform where this
release is being created.  At the same time, I took the opportunity to
improve the look of the PostScript results of this example by
indicating its purpose and keeping results for the various test
glyphs separate from each other.  The results are good (no build or
run-time errors, the PostScript results are now self-explanatory, and
the missing glyphs are indicated by empty boxes).

1.2 #include FreeType headers in recommended (by FreeType) way.

This fixes <https://sourceforge.net/p/lasi/bugs/2/>, does not disrupt
the previous success with building libLASi against FreeType version
2.4.9, and for the first time allows libLASi to build against FreeType
version 2.5.1 and later.  So this is a high-impact fix for use of
libLASi with the latest FreeType versions and is also the fundamental
motivation for this maintenance release.

1.3 Make all install locations configurable.

This fixes <https://sourceforge.net/p/lasi/bugs/3/> and makes it more
convenient to package libLASi.

1.4 Fix FreetypeGlyphMgr::FreetypeGlyphMgr(FT_Glyph glyph) initialization bug.

This fixes <https://sourceforge.net/p/lasi/bugs/4/>.  The particular
method being fixed here is not used in any of our examples, and was
only caught by compiler warning messages rather than a bug report
about actual use of this method so this is likely a low-impact
fix.

1.5 Fix long-standing file repeatability issue.

This bug <https://sourceforge.net/p/lasi/bugs/5/> was discovered while
testing a pre-release version of 1.1.2, but apparently also appeared
in all prior releases of libLASi.  The issue was glyphs without a name
available in the font data were assigned a unique name by libLASi
using rand, but those unique names were not repeatable from one run of
an application linked to libLASi to the next (presumably because
libraries that libLASi depends on were fiddling with the rand seed in
some threaded way that was not repeatable).  An initial fix that used
rand_r and a unique seed for libLASi solved the issue, but ultimately
it was decided to solve the issue by using the libLASi assigned names
LASi_glyph_1, LASi_glyph_2, etc., which should be unique until the
integer overflow limit is encountered, and which should not name clash
with glyph names that are included with font data.

2. Testing of this release.

This release has been successfully build and run tested on Linux using
(1) libpango-1.30.0, libcairo-1.12.2, and libfreetype-2.4.9 and (2)
libpango-1.35.0, libcairo-1.12.14, and libfreetype-2.5.3.

Thanks to the kind testing help of Arjen Markus, this release has also
been successfully build and run tested on Windows using the build
procedure for that platform given at <http://www.unifont.org/lasi/>
using the gtk+ all-in-one Windows bundle downloaded from
<http://www.gtk.org/download/win32.php> which includes
libpango-1.30.1, libcairo-1.10.2, and libfreetype-2.4.11.

Although there has been no specific testing of this release on Mac OS
X, we do not anticipate any difficulties for that platform since
previous releases of libLASi (patched for the above freetype header
issue) have worked fine on that platform according to reports at
https://sourceforge.net/p/lasi/bugs/2/.

libLASi Release 1.1.1
~~~~~~~~~~~~~~~~~~~~~
This is a stable release of libLASi. It represents the ongoing efforts
of the libLASi developers to improve the libLASi library for creating
PostScript documents that can contain characters from any of the
script and symbol blocks supported in Unicode and by the Pango layout engine.

If you encounter a problem with libLASi, then please send a bug report to
the libLASI developers via the lasi-devel mailing list described at
http://lists.sourceforge.net/lists/listinfo/lasi-devel.

Please see the license under which this software is distributed (LGPL), and
the disclaimer of all warrantees, given in the COPYING.LIB file.

INDEX

1. Changes relative to our previous release (version 1.1.0).

1.1 Make declaration and definition of setFont arguments consistent.
1.2 Fix alignment of diacritical marks.
1.3 Build system improvements.
1.4 Reduction of symbol visibility for gcc.

1.1 Make declaration and definition of setFont arguments consistent.

Thanks to John Ellson's bug report (link failure with Sun's CC - ID:
2797964) we found out that the arguments of setFont had inconsistent
const attributes between the declaration in LASi.h and the definition
in psDoc.cpp.  We have now fixed that inconsistency by using John's
patch to drop the const attribute from the appropriate definition
arguments.

1.2 Fix alignment of diacritical marks.

Thanks to Yotam Medini for supplying a patch which we have applied to
correct the positioning of diacritical marks.  This change means there
must be an extra bool applyOffset = false argument to the
PostscriptDocument::for_each_glyph_do method (see Lasi.h).  This
method is called internally by other libLASi routines with applyOffset
both true and false depending on circumstances/needs to obtain
correct offsets for diacritical marks.  

This method is also available for external use so this added argument
is a backwards-incompatible API change requiring rebuilding of
apps/libraries that use this method, and the soversion of the library
has been bumped from 0 to 1 consistent with this API change.  However,
this external API change issue is not relevant for the libLASi
examples that are part of this release and also to the psttf device driver
for PLplot that depends on libLASi because those applications and device
driver plug-ins do not call the for_each_glyph_do method.

1.3 Build system improvements.

Our CMake-based build system has been updated to determine pkg-config
results in a way that is much more useful for CMake.  (We simply
adopted PLplot's method of handling this).  The result is that modern
CMake (tested on CMake-2.6.4 and CMake-2.8.1) warnings about
inconsistent library handling by Policy CMP0003 are no longer present.
The minimum version of CMake has been updated from 2.4.5 (!) to 2.6.4.

1.4 Reduction of symbol visibility for gcc.

The infrastructure in LASi.h for exporting symbols for the Windows
version of this library has been generalized for the gcc-4.x case for
Unix platforms following the well-tested implementation used for
the PLplot libraries.

The net effect of this change is that Windows visibility of symbols
should be unchanged and similarly for Unix _except_ for the case of
gcc on Unix where the user specifies the gcc -fvisibility=hidden
option.  For that case, the exported symbols are reduced to those
exported in the Windows case.  The difference in results between using
default visibility and -fvisibility=hidden for gcc-4.x on Unix is the
number of visible symbols in libLASi.so is reduced from 164 to the 128
actually needed by users of the library which should give a modest but
still significant reduction in load times.

libLASi Release 1.1.0
~~~~~~~~~~~~~~~~~~~~~
This is a stable release of libLASi. It represents the ongoing efforts
of the libLASi developers to improve the libLASi library for creating
PostScript documents that can contain characters from any of the
script and symbol blocks supported in Unicode and by the Pango layout engine.

If you encounter a problem with libLASi, then please send a bug report to
the libLASI developers via the lasi-devel mailing list described at
http://lists.sourceforge.net/lists/listinfo/lasi-devel.

Please see the license under which this software is distributed (LGPL), and
the disclaimer of all warrantees, given in the COPYING.LIB file.

INDEX

1. Changes relative to our previous release (version 1.0.5p1 for FreeType
versions less than 2.2 and version 1.0.6 for FreeType 2.2+).

1.1 Replace autotools-based build system with a CMake-based build system.
1.2 libLASi can now be built both on Unix and Windows.
1.3 The examples have been reorganized and extended.
1.4 libLASi is now more robust against font/glyph issues.


1.1 Replace autotools-based build system with a CMake-based build system.

The build system is now based on CMake. It has been tested on Linux,
Mac OS-X and Windows platforms.  For directions on how to use CMake to
build libLASi, please consult http://www.unifont.org/lasi/.  In particular,
the new build system has the capability of detecting the FreeType version
so the previous split release (1.0.5p1 and 1.0.6) is no longer necessary.

1.2 libLASi can now be built both on Unix and Windows

Our new CMake-based build system allows building libLASi on both Unix
(Linux, Mac OS X, and proprietary Unices) and Windows (Cygwin, MinGW/MSYS,
and Microsoft proprietary build environments) platforms.  Instructions
for various platforms have been collected at http://www.unifont.org/lasi/.
  
1.3 The examples have been reorganized and extended and can now be built
in both the build tree and install tree.

After running "cmake" (which configures libLASi) and "make" (which builds
the libLASi library and examples which use that library in the build tree,
see instructions at http://www.unifont.org/lasi/), you can run ctest in the
build tree to run the examples. If ctest shows no errors, the PostScript
results of that test of the libLASi library are collected in the
examples/example[0-2].ps files in the build tree. See examples/README
in the source tree for descriptions of these test examples.

The examples can also independently be built and run in the install tree
created by "make install" as well using

cd $version/share/lasi$lasi_version/examples 
make

where $version is the installation prefix specified as a command-line option
for the cmake command, and $lasi_version is currently 1.1.0.  The make
command uses pkg-config to specify the correct C++ flags and link flags, and
users with independent applications that link to libLASi are advised to use
the same method as well.

1.4 libLASi is now more robust against font/glyph issues.

Missing glyphs are now rendered as a blank rather than being the cause of
showstopping errors seen in previous libLASi releases.

Some font installations were occasionally returning non-outline glyphs that
were causing segfault errors for older libLASi versions.  The libLASi code
has now been changed to render a blank for such cases and only attempt to
render results for the outline glyphs it was designed for.