restructured source for GitHub

1 files changed, 94 insertions, 0 deletions

diff --git a/doc/RELEASE_NOTES-1.0.3.txt b/doc/RELEASE_NOTES-1.0.3.txt
new file mode 100644
index 0000000..edfb1e2
--- /dev/null
+++ b/doc/RELEASE_NOTES-1.0.3.txt
@@ -0,0 +1,94 @@
+------------------------------
+shFlags.sh 1.0.3 Release Notes
+------------------------------
+
+Preface
+=======
+Copyright 2008-2009 Kate Ward. All Rights Reserved.
+Released under the LGPL (GNU Lesser General Public License)
+Author: kate.ward@forestent.com (Kate Ward)
+
+This document covers any known issues and workarounds for the stated release of
+shFlags.
+
+Release info
+============
+
+This is a major bug fix release. The biggest fix is in how non-flag arguments are
+made available to the script.
+
+Major changes
+-------------
+
+The use of the ``FLAGS_ARGC`` variable is now obsolete. It will be maintained
+for backwards compatibility with old scripts, but its value is known to be
+wrong when flag and non-flag arguments are mixed together on the command-line.
+
+To gain access to the non-flag arguments, replace the following snippet of code
+in your scripts with the updated version.
+
+old ::
+  shift ${FLAGS_ARGC}
+
+new ::
+  eval set -- "${FLAGS_ARGV}"
+
+Please see the CHANGES-1.0.txt file for a complete list of changes.
+
+Obsolete items
+--------------
+
+Bug fixes
+---------
+
+Issue# 7 Flags set with '=' result in off-by-one shifting error
+
+General info
+============
+
+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  |
+| intermixing of flag and non-flag values |  N  |  Y  |
++=========================================+=====+=====+
+
+Known Issues
+------------
+
+The **getopt** version provided by default with all versions of Mac OS X (up to
+and including 10.5.6) and Solaris (up to and including Solaris 10 and
+OpenSolaris) is the standard version.
+
+Workarounds
+-----------
+
+The Zsh shell requires the ``shwordsplit`` option to be set and the special
+``FLAGS_PARENT`` variable must be defined. See ``src/shflags_test_helpers`` to
+see how the unit tests do this.
+
+.. vim:fileencoding=latin1:ft=rst:spell:tw=80