-*- org -*-

#+STARTUP: hidestars oddeven

This is the 'NEWS' file for the 'screen-wrappers' project. This file contains
information on changes since the last release of the package, as well as a
running list of changes from previous versions.  If critical bugs are found in
any of the software, notice of such bugs and the versions in which they were
fixed will be noted here, as well.

------------------------------------------------------------------------------

* screen-wrappers 0.3.3 (2019-01-21)

** fixes

*** issue #9: screen-ls: unable to parse zero-session output from GNU screen "4.02.01 (GNU) 28-Apr-14"

    https://github.com/salewski/screen-wrappers/issues/9

    Added logic to check exit status of 'screen -q -ls' prior to attempting to
    parse the output of 'screen -ls'. This provides a more direct way of
    detecting the "no screen sessions found" scenario because the '-q' option
    causes screen to exit with status 9. The 'screen' exit statuses between 10
    and 125 are treated as "one or more screen session found". The behavior of
    exit status 10 and above is consistent with screen(1), which states:

    #+BEGIN_QUOTE
       -q   Suppress printing of error messages. In combination with "-ls" the
            exit  value  is  as  follows: 9 indicates a directory without ses-
            sions. 10 indicates a directory with running  but  not  attachable
            sessions.  11 (or more) indicates 1 (or more) usable sessions.  In
            combination with "-r" the exit value is as follows:  10  indicates
            that  there  is  no session to resume. 12 (or more) indicates that
            there are 2 (or more) sessions to resume and  you  should  specify
            which one to choose.  In all other cases "-q" has no effect.
    #+END_QUOTE

    [The above taken from screen(1) as provided with screen version 4.00.03
     (FAU) 23-Oct-06. Note that the man page text for the option remains
     identical to the above as of screen version 4.05.00 (GNU) 10-Dec-16]

     The limit of treating 125 as the highest exit status interpreted as
     described above is due to the fact that bash uses values of 126 and
     higher to indicate various abnormal exit conditions (killed by various
     signals, etc.). For more on that, see the "EXIT STATUS" section of
     bash(1).

     Consistent with prior releases of the 'screen-wrappers' package, the
     'screen-ls' program still exits with a zero (success) status if it was
     able to complete its work successfully, regardless of whether any
     existing screen sessions were found.

     If verbose output has been enabled, then a message is printed to stderr
     explaining the "no screen sessions found" scenario:
 
     :     $ screen-ls
     :     $ echo $?
     :     0
     :
     :     $ screen-ls -v
     :     screen-ls (info): no screen sessions exist (okay); exiting early with success status (no work left to do)
     :     $ echo $?
     :     0


** improvements

*** issue #14: screen-ls.in: refactor f_is_screen_4_dot_3_or_newer(...) to accept screen version string as a function argument

    https://github.com/salewski/screen-wrappers/issues/14

    The jury is still out on the degree to which this may be an improvement,
    but the parsing of the output of 'screen --version' has been made more
    robust (both in being more lenient in what we might get, as well as in the
    checking of the exit status of the invocation).


*** issue #12: update 'HACKING' file to reflect current versions of GNU autotools, and similar

    https://github.com/salewski/screen-wrappers/issues/12

    The HACKING file now reflects the author's use of automake 1.15.


*** issue #11: screen-ls: unset GREP_OPTIONS to prevent warning from GNU grep 2.11+

    https://github.com/salewski/screen-wrappers/issues/11

    The 'screen-ls' program now unconditionally unsets the GREP_OPTIONS
    environment variable.

    This only has an effect if the grep program in use is GNU grep; other grep
    implementations did not recognize or alter their behavior based on the
    'GREP_OPTIONS' variable. GNU grep prior to version 2.11 (~2014-11) would
    append values from this variable to the command line, which would make
    behavior of our invocations in the current program unpredictable. Versions
    of GNU grep 2.11 or newer no longer behave that way, but do emit a warning
    on stderr about the change in behavior.

    Unsetting GREP_OPTIONS here has the effect of making our grep invocations
    predictable (when older versions of GNU grep are in use) and also of
    suppressing the spurious warning:

        grep: warning: GREP_OPTIONS is deprecated; please use an alias or script

    when newer versions of GNU grep are in use.


------------------------------------------------------------------------------


* screen-wrappers 0.3.2 (2016-07-30)

** fixes

*** issue #8: autotools/missing and friends updated

    https://github.com/salewski/screen-wrappers/issues/8

    This prevents these configure-time warnings:

    :    /path/to/screen-wrappers/autotools/missing: Unknown `--is-lightweight' option
    :    Try `/path/to/screen-wrappers/autotools/missing --help' for more information
    :    configure: WARNING: 'missing' script is too old or missing


*** issue #6: configure now checks for bash 4.x or newer

    https://github.com/salewski/screen-wrappers/issues/6

    The 'screen-ls' program uses associative arrays, which were introduced in
    bash-4.0. The 'configure' was previously checking for the presence of
    bash, but did not check for any particular version. The consequence was
    that it was possible to build a version of the program that did not work
    at runtime if installing on a host that only has bash 3.x (yes, the author
    came across such a thing in the wild).

    The 'configure' script now checks that the found version of bash is at
    major version 4 or newer, and bombs out with an error message if that is
    not the case.

    If you have multiple versions of bash installed on your machine, you can
    tell 'configure' where to find the one you want to use by specifying the
    'BASH_SH' variable on the 'configure' command line like this:

    :    $ ./configure --prefix=/path/to/wherever BASH_SH=/path/to/your/bash-4


*** issue #7: screen-ls no longer swallows output of old versions of screen

    https://github.com/salewski/screen-wrappers/issues/7

    Prior to this fix the 'screen-ls' program was only able to parse the
    'screen -ls' output from more recent versions of GNU 'screen', and was
    swallowing all of the output from ancient versions of 'screen' that
    produced a slightly different output.

    The program was expecting to parse output in the form:

    :        28189.screen-wrappers-hacking   (06/22/2016 06:49:18 PM)        (Attached)

    but was inadvertently swallowing all of the output from older versions,
    which have the form:

    :        28189.screen-wrappers-hacking   (Attached)

    The 'screen-wrappers' author is still encountering those ancient versions
    "in the wild", so the 'screen-ls' program has been enhanced to be flexible
    enough to correctly parse both forms.

    Old format behavior tested with 'screen' 4.00.03 (FAU) 23-Oct-06.

    New format behavior tested with 'screen' 4.04.00 (GNU) 19-Jun-16.


** improvements

   (none)

------------------------------------------------------------------------------


* screen-wrappers 0.3.1 (2016-07-29)

** fixes

*** issue #5: screen-wrappers build now omits `--nobacklink` when invoking pod2html

    https://github.com/salewski/screen-wrappers/issues/5

    The `'--no-backlink'` option to `pod2html` requests what is the default
    behavior for that tool, but that command line option is not available on
    some older `pod2html` versions (such as that from perl 5.8.8) on hosts on
    which we wish to build screen-wrappers. We therefore have removed the
    option from the Makefile recipe; the resulting build is identical in
    behavior and outcome to that prior to this change, but the build is now
    able to complete successfully on a slightly wider range of machines (at
    the expense of the build recipe being slightly less explicit about the
    wanted behavior).

** improvements

   (none)

------------------------------------------------------------------------------


* screen-wrappers 0.3.0 (2016-07-04)

** fixes

   (none)


** improvements

*** README(.md) switched to GitHub-flavored markdown (from org-mode) for improved rendering on GitHub

    The content of the file was also updated to integrate better from the
    GitHub repository view (which shows the README file by default) with the
    project's GitHub Pages site.

    Also renamed the file from 'README' to 'README.md' so GitHub would
    recognize it as a markdown file.


*** issue #3: screen-ls: allow short-form command line options to be bundled

    https://github.com/salewski/screen-wrappers/issues/3

    All of the following representative invocations are now equivalent:

    :     $ screen-ls -l -p
    :     $ screen-ls -lp

    :     $ screen-ls -p -l
    :     $ screen-ls -pl

    Prior to this change, the bundled variations ('-lp' and '-pl') caused the
    program to exit with an error code.


*** issue #4: build now generates man pages in HTML format, too

    https://github.com/salewski/screen-wrappers/issues/4

    The project is now able to generate man pages in HTML format (in addition
    to the troff format man pages). This is mainly intended for use by the
    author to incorporate them into the 'screen-wrappers' project's GitHub
    Pages web site.  However, the mechanism is generic and will install the
    pages beneath a 'html' directory beneath the =htmldir= location (which can
    be specified at configure-time).

    Since this is a new capability, we have bumped up the 'm' in our M.m.p
    (semver) version number from '0.2.3' to '0.3.0'.

------------------------------------------------------------------------------


* screen-wrappers 0.2.2 (2016-06-22)

** fixes

*** screen-ls: minor documentation fix


*** screen-ls: fix github issue #2: name of last session name was being omitted from output when using newer versions of GNU 'screen'.

    See: https://github.com/salewski/screen-wrappers/issues/2


** improvements

   (none)

------------------------------------------------------------------------------


* screen-wrappers 0.2.1 (2016-04-10)

** fixes

*** screen-ls: address github bug #1: work correctly with GNU screen 4.3.0 or newer

    https://github.com/salewski/screen-wrappers/issues/1

    Upstream GNU screen versions prior to 4.3.0 exited with a non-zero exit
    status of 1 (rather than the expected zero status) when invoked with the
    'screen -ls' option, as is done by the 'screen-ls' program:

    http://savannah.gnu.org/bugs/?26750

    Earlier versions of 'screen-ls' had a comment in the source code noting
    the wonkiness, and broke with GNU screen 4.3.0 when the upstream bug
    #26750 was addressed (2015-06-12).

    The 'screen-ls' program now attempts to parse the output of 'screen
    --version' at runtime and adapt its behavior accordingly. If it detects a
    version of GNU screen older than 4.3.0, then the traditional 'screen-ls'
    behavior is used. If a version of screen newer than 4.3.0 is detected,
    then the behavior is modified to expect a zero exit status to indicate a
    successful outcome from the 'screen -ls' invocation.


** improvements

   (none)

------------------------------------------------------------------------------


* screen-wrappers 0.2.0 (2016-03-25)

This release of 'screen-wrappers' finds the project publicly hosted on GitHub
for the first time. The project's GitHub URL is:

    http://github.com/salewski/screen-wrappers

** fixes

   (none)


** improvements

*** screen-ls: minor doc fixes

*** screen-ls: new '-U' (--unsorted) option

    The new '-U' (--unsorted) option prevents the program from sorting the
    output, and instead list screen sessions in order output by
    screen(1). Thanks to John Marquart for suggesting this feature.

------------------------------------------------------------------------------


* screen-wrappers 0.1.1 (2013-07-09)

** fixes

**** screen-ls: corrected 'screen -q -ls' exit status checking

The screen-wrappers-0.1.0 release included a version of 'screen-ls' that had
code left in that was being used by the author to verify error handling by
forcing the exception condition, with the result that the program was
unusable. Sorry! This has been corrected.


** improvements

------------------------------------------------------------------------------


* screen-wrappers 0.1.0 (2013-07-09)

This is the initial release of 'screen-wrappers'.

The 'screen-wrappers' project provides convenience wrappers for various
invocations of the GNU screen(1) program.

    http://www.gnu.org/software/screen/

This initial release provides only the 'screen-ls' program. Once installed,
you can read screen-ls(1) to learn all about it.

See the README file for more information.

------------------------------------------------------------------------------
