==============
 Using minder
==============

   Minder is a command line reminder program with a simple cron-like file
format. You can use it to remind you of appointments, birthdays, anniversaries,
holidays, and just about whatever else. The reminder syntax if fairly
expressive. You can represent simple one shot items (for instance, an event on
June 27th, 2004) or more complex occurrences like the USA's Election Day (the
first Tuesday after the first Monday of every November).

   Minder keeps its reminder files in ~/.minder/, like so:

[loco@erebor]% ls -l ~/.minder/
total 8
-rw-------    1 loco     users         622 May 18 13:56 2004
-rw-------    1 loco     users         570 May 18 13:58 perm

   There is a file for each year that has particular one-shot items in it. The
'perm' file, though, is always used, and stores reminders that occur year to
year. The line format for these files is inspired by cron, but is different. Try
not to get confused. Here's a line broken down:

<YEAR> <MONTH> <DAY OF MONTH> <LOGIC><DAY OF WEEK> :<ORIGIN DATE>: <COMMENT>
   YEAR: four digit year
   MONTH: either numeric month, or three letter case insensitive abbreviation
   DAY OF MONTH: numeric
   LOGIC: one of '&', '|' or nothing, which is the same as '|', indicating
whether we're ORing the days with the days of the week (like cron) or ANDing
them
   DAY OF WEEK: either numeric (with Sunday as 0 or 7, just like vcron) or three
letter case insensitive abbreviation
   ORIGIN DATE: date of first occurrence; we will note how long ago this was when
representing this event; optional field
   COMMENT: free-form text to the end of the line to describe the reminder

   Any of these fields (besides ORIGIN DATE and LOGIC) can be an asterisk (*)
instead of a standard value to indicate 'all possible values.' So * in the YEAR
field means 'every year.' These can all be combined to indicate particular dates
or series of dates. Minder allows you to put however many spaces before and in
between these fields as you want, including tabs, but you must have some space.
   A reminder file can have any number of reminders. Each reminder gets its own
line, but you can have blank lines, and also comment lines by starting them with
a hash mark (#).
   Here is what a couple of actual reminders look like:

* 5 5 * :: Cinco di Mayo
* 7 4 * :17760704: Independence Day
* 11 2-8 &tue :: Election Day
* 11 22-28 &thu :: Thanksgiving
* 12 25 * :: Christmas

   These reminder were chosen because they show a few of the nifty features of
minder. Cinco di Mayo and Christmas are both static days that should be easy to
understand. They occur on all years, particular months and particular days.
Also, it doesn't matter which day of the week either lands on. Independence Day
(yes, we're USA-centric here..) is also a simple day, but it has an origin, so
we list that. When this reminder comes up, minder will also tell you how many
years ago from the requested date that was. Nice huh?
   Election Day and Thanksgiving are more complex. Thanksgiving falls on the
third Thursday in November. A not-so-quick glance at a calender will show you
that the third Thursday of any month will always be from the 22nd to the 28th.
But it must be a Thursday, too. So, minder has the option of logically ANDing
the day of the month with the day of the week, not ORing them, like cron always
does. OR is the default behavior for minder, but you can AND instead with an
ampersand (&) before the day of the week. So Thanksgiving is the Thursday of
November that lies between the 22nd and the 28th, inclusive. Election Day is the
first Tuesday after the first Monday of November. So we make sure it's a Tuesday
by ANDing the day of the week, and we make sure that there's been at least one
day before that Tuesday by specifying a week starting with the 2nd.
   Minder also lets you specify periodic reminders, but this is sort of beta
right now. It only works for the the day of the week, and even then it's sort of
half-working. Basically, it's a semi-ugly hack.

* * * fri/2 :20040507: Payday

   The above line will give you a reminder every 2nd Friday starting with May
7th, 2004. What it actually does is give a reminder every 2 weeks from the
origin, not really caring that Friday was specified. It works just fine for
periodic day of the week reminders though. I intend to make it work correctly
for any field, so you could specify:

*/4 6-8 * * :20040601: The Olympics

   But that doesn't currently work. Any help with implementing this right, lemme
know.
   The 'perm' file has the format described above. The annual file (named for
the year, e.g '2004') does not include a year field, as everything in the file
is assumed to take place in the year indicated by the filename. For instance:

5 5 * :: Appt with Dr. Smith
Jun 12-16 * :: Trip to Free Country, USA

   This is done to reduce typing the same year on every line. The year files are
only looked at when the requested date is that year anyway, so anything not
landing on that year would never be seen if it was in a year file.

   Good luck!


=======
 Usage
=======

   Now that you actually have some usable reminder files, here's how to actually
invoke and use the program:

USAGE:
        minder <date> +<days> -<qhv>

        <date>    8 digit date YYYYMMDD
        +<days>   span of days from requested date to display reminders from
        -q        quiet output, don't remind on reminderless days
        -h        print this help output and exit
        -v        print version and exit

   If you give no arguments, minder will print just the reminders for today.

[loco@erebor]% minder
20040518
  Tuesday

   You can also just specify a date in 8 digit format (YYYYMMDD), and minder
will print just the reminder for that day.

[loco@erebor]% minder 20040704
20040704
  228 year(s): Independence Day
  Sunday

   If you use the +<days> argument, minder will print all the reminders over the
span of <days> days. You can also use this argument after specifying a
particular date, and that will be the start of the span of days.

[loco@erebor]% minder +5
20040518
  Tuesday
20040519
  work
  Wednesday
20040520
  work
  Thursday
20040521
  work
  Friday
20040522
  work
  going to Delaware!
  Saturday
20040523
  going to Delaware!
  Sunday

[loco@erebor]% minder 20040704 +5
20040704
  228 year(s): Independence Day
  Sunday
20040705
  Monday
20040706
  Tuesday
20040707
  Wednesday
20040708
  work
  Thursday
20040709
  work
  Friday

   You might notice that even when there's not a reminder on a day, minder will
still tell you what day of the week that is. If you'd rather only get output
when there's really a reminder, use the -q option (q is for quiet). Minder will
still print the day of the week on days with reminders.

[loco@erebor]% minder -q 20040704 +5
20040704
  228 year(s): Independence Day
  Sunday
20040708
  work
  Thursday
20040709
  work
  Friday

   Enjoy! Please let me know you if you see any place to improve minder. I hope
you find it useful.

Brian Kelly
locoburger@netscape.net
http://www.locoburger.org/
