Copyright (C) 2011 Jason Graham <[email protected]> 
See the end of the file for license conditions.

=====================================================================
                               SUMMARY
=====================================================================

GSD (gsd) is the "getting stuff done" to-do list manager. It is a
command driven utility used to create, manage, and print to-do
lists. It provides basic functionality such as:

   * Adding, deleting, and modifying to-do items

   * Creating and managing an arbitrary number of to-do lists

   * Updating an item's status (new, incomplete, complete) as you
     work on it

   * Flagging items that are most important

   * Viewing and printing items for a given status to see all
     completed tasks, all new tasks, etc.

   * Searching for entry items in a specified list or all lists

Because gsd has a simple interface for managing all of your to-do
lists, you can create lists for home, work, etc. and create lists for
each of your projects.

Requirements: gsd should work fine on any Unix based OS (Linux, *BSD,
Mac) and on Windows running Cygwin. It requires software found on any
standard installation of the aforementioned OS's. Specifically these
requirements are:
   
   * bash
   * coreutils
   * grep
   * sed
   * lpr (for printing support)


=====================================================================
                           GETTING STARTED
=====================================================================

To get started place the file "gsd" somewhere in your PATH. The
easiest what to see what does what is to run:

    gsd help

from the command line. 

gsd provides colored output when displaying to the terminal. The
colors are configured by default to be suitable for white or light
colored terminal backgrounds. If you use a dark background for your
terminal you may want to change the default color configuration by
opening with your favorite text editor the file "gsd" and changing the
line

    DARK_BACKGROUND="no"

to

    DARK_BACKGROUND="yes"


=====================================================================
                               TUTORIAL
=====================================================================

----------------------------------------------------------------------
                             BASIC USAGE
----------------------------------------------------------------------

To add your first items run:

    gsd add "Learn how to use gsd" 
    gsd add "Wash the dishes" 
    gsd add "Walk the dog"

To show the new entries, run:

    gsd show

and you should see the items that where entered as:

    1 (N): Learn how to use gsd

    2 (N): Wash the dishes

    3 (N): Walk the dog

Each entry is composed of four parts:

    <tag> <status>: <flag> <statement>

The tag is used to reference items when editing or deleting them,
status lets you know an entry's progress, and statement is the text
you would jot down on your to-do list. The flag will only be present
if toggled on.

Since you are on the way to learning gsd, go ahead and change the
status of the first item with:

    gsd edit -s I 1

Showing the entries again shows that the status was updated to "(I)"
for "in progress/incomplete". To look at only the new items run:

    gsd show -n

and similarly the incomplete items:

    gsd show -i

In some instances it is useful to flag some items to be important so
they recieve the immediate attention. An important flag "(*)" may be
toggled by using

    gsd edit -f <tag>

Doing this for item 2 in list we get:

    1 (I): Learn how to use gsd

    2 (N): (*) Wash the dishes

    3 (N): Walk the dog

from "gsd show". To unmark the item, just toggle it off with the same
command. If you have a lot of items, you can tag the most important
ones then choose to view only these by:

    gsd show -f

You can also choose to print a list using the system default printer
(this requires the program "lpr" and the PRINTER environment variable
to be set). To print the entire list run:

    gsd print

and this will print the contents you'd see from from "gsd show". To
print say only the flagged items run:

    gsd print -f

Once you are done with an item either mark it as complete with:

    gsd edit -s C <tag>

or delete the item using:

    gsd delete <tag>

If you have numerous completed items and would like to delete them all
at once run:

    gsd purge

After you delete items you'll notice that the tag numbers remained the
same and may not be continuous. This was done to ensure that if gsd
is ran several times successively the tag number will remain the same
and the wrong tags won't be referenced. To see this, let's delete item
2 from our list with:

    gsd delete 2

to get:

    1 (I): Learn how to use gsd

    3 (N): Walk the dog

from "gsd show". Notice the tag numbers are 1 and 3, not 1 and
2. Although not necessary, it may be of convenience to put the tags in
successive order with:

    gsd edit -r

to get:

    1 (I): Learn how to use gsd

    2 (N): Walk the dog

from "gsd show".


----------------------------------------------------------------------
                          WORKING WITH LISTS
----------------------------------------------------------------------

By default (if no list is specified) gsd works with the list
"default". To start working with a specific list we pass "-l <list>"
as the first argument to gsd. Suppose we would like to create a list
called "myproject", we would do this by simply adding an item with:

    gsd -l myproject add "Step 1 to the project"

This step will automatically create the project and insert the first
entry. Let's now create two more entries:

    gsd -l myproject add "Step 2 to the project"
    gsd -l myproject add "Step 3 to the project"

To see the entries of the list "myproject" run:

    gsd -l myproject show

The first line displayed in the output tells you which list this is
from. In this case we see:

    LIST: myproject

This will come in handy when viewing all items in your lists using
"gsd showlists" and need to distinguish between the lists. All of the
other commands (add, delete, edit, etc.) are applied to the specified
list in the same way using:

    gsd -l myproject <command>

To see which lists you have available run:

   gsd lists

In this example you should see:

   default
   myproject

The default list will always be present since it is created
automatically by gsd. To delete a list once your done with it execute:

    gsd deletelist <list>

In addition to working with a single list, you can also work with all
lists at the same time using aggregate operations. As mentioned
previously, you can see all items of your lists simultaneously with

   gsd showlists

and for example to see only the new items use:

    gsd showlists -n

Other list functions are "searchlists" - search entries for specified
text, "purgelists" - purge the complete items from all lists, and
"printlist" - print all lists are available.

Well, that should hopefully be enough to get you started. Remember to
always refer to "gsd help" if you get stuck.

Enjoy.


=====================================================================
                           GENERAL COMMENTS
=====================================================================

 * Also after starting and finishing the first major part of this
   project, it was realized that numerous utilities similar to this
   one exist online. Up until now, no parts of this program have been
   borrowed from any others; if at any point parts are borrowed it
   will be noted here in this file.


This file is part of gsd

gsd is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.

gsd is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with gsd.  If not, see <https://www.gnu.org/licenses/>.