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.
