doc/RELEASE_NOTES-1.0.0.txt

------------------------------
shFlags.sh 1.0.0 Release Notes
------------------------------

Preface
-------
Copyright 2008 Kate Ward. All Rights Reserved.
Released under the LGPL (GNU Lesser General Public License)

Author: Kate Ward (kate.ward@forestent.com)

This document covers any known issues and workarounds for the stated release of
shFlags.

General info
------------

This is the first official release of shFlags. The project is modeled after the
gflags code released by Google on http://code.google.com/p/google-gflags/. Many
thanks for the code they have provided.

As this is the first release, there are bound to be issues. Feel free

Disclamer
---------

The unit tests
--------------

shFlags is designed to work on as many environments as possible, but not all
environments are created equal. As such, not all of the unit tests will succeed
on every platform. The unit tests are therefore designed to fail, indicating to
the tester that the supported functionality is not present, but an additional
test is present to verify that shFlags properly caught the limitation and
presented the user with an appropriate error message.

shFlags tries to support both the standard and enhanced versions of ``getopt``.
As each responds differently, and not everything is supported on the standard
version, some unit tests will be skipped (i.e. ASSERTS will not be thrown) when
the standard version of ``getopt`` is detected. The reason being that there is
no point testing for functionality that is positively known not to exist. A
tally of skipped tests will be kept for later reference.

Standard vs Enhanced getopt
---------------------------

Here is a matrix of the supported features of the various getopt variants.

+-------------------------+---+---+
|Feature                  |std|enh|
+=========================+===+===+
|short option names       | Y | Y |
|long option names        | N | Y |
|spaces in string options | N | Y |
+-------------------------+---+---+

Known Issues
------------

The getopt version provided by default with all versions of Solaris (up to and
including Solaris 10) is the standard version. As such, only short flags are
supported.

The getopt version provided by default with all versions of Mac OS X (up to and
including 10.5) is the standard version. As such, only short flags are
supported.

Workarounds
-----------

The zsh shell requires the 'shwordsplit' option to be set, and the special
FLAGS_PARENT variable must be defined.