================================================================================
    shalarm.sh  |   James Hendrie (hendrie.james@gmail.com)
    2018-09-14  |   README file
================================================================================

Usage:
    shalarm [OPTION / TIME]


Requirements:
    You'll need a media player of some sort to actually get anything out of this
    script.  I recommend 'mplayer' or something similar.  If you want to use the
    'FORTUNE' option in the config file, you'll also need the fortune program
    installed.


Installation:
    You don't really need to install this (it's a shell script), but it makes
    things a little easier if you do.  To do so, as superuser and within the
    root directory to which you've extracted the archive, type 'make install'.


Uninstallation:
    Similar to the above, except you type 'make uninstall' instead.


Description:
    It's just an alarm clock written as a bash script.  Use it however you'd use
    an alarm.  Alarms are typically used to cancel sleep.

    I'd recommend trying it with the --test option before attempting to use this
    in any serious capacity, however.

    NOTE:  Times can be in 24-hour or 12-hour format.  For 12-hour
           format, append AM/PM (case-insensitive, with optional
           periods).  Single-letter abbreviations ("5a", "10p")
           are also accepted.


Arguments:
    -h or --help:
        Print a help screen

    -v or --version:
        Print version and author info

    -d or --debug:
        Print out some information about what the script is trying to do.

    -t or --test:
        Test out the alarm (HIGHLY RECOMMENDED)

    --snooze N:
        Enable snooze, set snooze length to N seconds

    --timeout N:
        Enable alarm timeout, set timeout limit to N seconds


Examples:
    shalarm 14
        Set the alarm for 14:00 (2:00 PM).
    shalarm 2:00PM
        Same as above, using 12-hour format.
    shalarm 2p
        Same as above, using 12-hour shorthand.
    shalarm 1430
        Set the alarm for 14:30 (2:30 PM).
    shalarm 143030
        Set the alarm for 9:00 PM.  Just kidding.  14:30:30 (2:30:30 PM).
    shalarm 10:00 am
        Set the alarm for 10:00 AM (12-hour).
    shalarm --snooze 300 --timeout 900 07:30
        Set the alarm for 7:30 AM.  Additionally, both snooze and alarm timeout
        are enabled.  When you snooze (the first CTRL-C), the alarm will silence
        itself for 300 seconds (5 minutes).  If left ringing for 900 seconds (15
        minutes), the alarm will terminate itself.



Configuration:
    Configuration files are stored at /etc/shalarm.cfg and
    $HOME/.config/shalarm/shalarm.cfg.  The second file takes precedence over
    the first.  While a configuration file isn't strictly required, it's highly
    recommended that you use it since it contains a couple of things not
    presently supported by command-line arguments.

    Initially the config file is installed to /etc/shalarm.cfg, but the
    user-modifiable version is copied to $HOME/.config/shalarm/shalarm.cfg the
    first time the script is run, including with the --test option.  It's
    probably a good idea to run the test before anything else.

    If you want to use the 'fortune' program when printing a wakeup message,
    set the wakeup message to FORTUNE.  Obviously, the fortune program needs to
    be installed.


This script is licensed under the FreeBSD License (aka, Simplified BSD License).
Check out LICENSE.txt for more info.


AUTHOR
    James Hendrie <hendrie.james@gmail.com>
    with contributions from Ilya Pikulin, stormdragon2976 and rellieberman.