NAME
pal - calendar with events
SYNOPSIS
pal [options]
DESCRIPTION
pal is a command‐line calendar utility. It displays a cal(1)‐like
calender and events specified in text files.
OPTIONS
The following options are provided by pal:
-d date
Show events on the given date. Valid formats for date include:
dd, mmdd, yyyymmdd, ’yesterday’, ’today’, ’tomorrow’, ’n days
away’, ’n days ago’, first two letters of weekday, ’next ’
followed by first two letters of weekday, ’last ’ followed by
first two letters of weekday, ’1 Jan 2000’, ’Jan 1 2000’.
-r n Display events occurring in the next n days (counting today).
By default, n is 0 and no events are displayed. For example,
using -r 1 makes pal display events occurring today. If -d is
used too, the range is relative to date instead of the current
date.
-r p-n Display a list of events occurring in the past p days (not
counting today) and the next n days (counting today). For
example -r 1-1 will show yesterday’s and today’s events. If -d
is used too, the range is relative to date instead of the
current date.
-s regex
Search for any occurrences of an event matching the regular
expression (regex) occurring in the range of dates specified
with -r. This command searches both the event description and
the type of event (specified at the top of a calendar file).
This search is case insensitive.
-x n Expunge events that are n or more days old if they do not occur
again in the future. pal will not expunge events from the
calendars loaded from /usr/share/pal; even if you are root and
you have added events to the calendars that are not recurring.
When -x is used with -v, the events that are expunged will be
displayed.
-c n Display a calendar with n lines (default: 5).
-f file
Load file instead of ~/.pal/pal.conf.
-u username
Load /home/username/.pal/pal.conf instead of ~/.pal/pal.conf.
-p palfile
Override the .pal files loaded from pal.conf. This will only
load palfile. For convenience, if palfile is a relative path,
pal looks for the file relative from ~/.pal/, if not found, it
tries relative to /usr/share/pal/, if not found it tries
relative to your current directory. (This behavior might change
in the future.) Using an absolute path will work as you expect
it to.
-m Manage events interactively. Events can be added, modified and
deleted with this interface.
--color
Force use of colors, regardless of terminal type.
--nocolor
Do not use colors, regardless of terminal type.
--mail Generates output readable by sendmail by adding "From:" and
"Subject:" fields and forcing --nocolor. For example, you could
mail yourself a reminder of the upcoming events in the next week
with pal --mail -r 7 | sendmail username. Note: For the
calendar to appear correctly, make sure your email client is
using a fixed width font.
--html Generates a HTML calendar suitable for display on a web page.
It does not generate a complete HTML document so that you can
add your website’s header and footer around the calendar. The
number of months shown on the calendar can be adjusted with -c.
You will need to use Cascading Style Sheets (CSS) to change how
the calendar appears; if you do not use a style sheet, the
calendar will not have any borders. See
/usr/share/doc/pal/examples/example.css for an example style.
SECURITY NOTE: If you set up pal so it is being executed
server‐side, it is recommended that you do not allow web page
visitors to directly change the parameters sent to pal.
Allowing users to pass strange parameters (such as extremely
long ones) can be a security risk.
--latex
Generates a LaTeX source for a calendar that can be used to
generate a printer‐friendly DVI (run "pal --latex > file.tex;
latex file.tex"), PostScript or PDF (run "pal --latex >
file.tex; pdflatex file.tex"). The number of months shown on
the calendar can be adjusted with -c.
-v Verbose output.
--version
Display version information.
-h, --help
Display a help message.
EVENT DESCRIPTIONS
Years since year YYYY
pal will replace !YYYY! (where YYYY is a year) with the current year
minus YYYY. This feature is particularly useful for birthdays. For
example, the event text for a birthday could be: John Doe was born
on this day in 1990. He is !1990! years old.
Sort by time
If events have a time in the event description, pal will sort these
events by time. The time in the event description must be of the
format h:mm or hh:mm (where hh is 0-23). If an event has more than
one time in the event description, pal will sort the event by the
first time. Events that do not have times in them are shown before
all the events that do have times. Events without times are sorted
in the order that they are loaded in pal.conf.
FILE FORMATS
Unless -f or -u is used, pal looks for (or tries to create if it
doesn’t exist) a configuration file named ~/.pal/pal.conf. pal.conf
contains settings for pal and a list other files that contain events to
be displayed on the calendar. The file formats for pal.conf and the
event files are described below.
pal.conf
file filename [ (color) ]
Loads an event file named filename. If filename isn’t found
in ~/.pal, pal will look for it in /usr/share/pal. The color
parameter is optional, it will display the events in the file
with the given color. Valid colors: black, red, green,
yellow, blue, magenta, cyan, white
file_hide filename [ (color) ]
Loads an event file name filename. These events are not
indicated in the calendar that is printed, but they are
displayed when the -r argument is used. If filename isn’t
found in ~/.pal, pal will look for it in /usr/share/pal. The
color parameter is optional, it will display the events in
the file with the given color. Valid colors: black, red,
green, yellow, blue, magenta, cyan, white
event_color color
The default color used for events. Valid colors: black, red,
green, yellow, blue, magenta, cyan, white
week_start_monday
If this keyword is defined, the calendar weeks start on
Monday instead of Sunday.
date_fmt string
Changes how dates are displayed when the -r -d or -s
arguments are used. string can be a date format string that
follows the format used by strftime(3). Type man strftime
for more information. string is set to %a %e %b %Y by
default (example: Sun 8 Aug 2010).
reverse_order
Display all event listings in descending order.
hide_event_type
Hide the event type (shown in before a ’:’) when listing
events. The event type is defined at the top of the file
that the event is found in.
cal_on_bottom
Display calendar at the end of the output.
no_columns
Display calendar in one column instead of two.
compact_list
List events that are shown when using -r in a more compact
form.
compact_date_fmt
Format for the date displayed when compact_list is used. See
date_fmt for more information.
default_range range
If you get tired of always using -r, you can set the default
value for -r here. See the information on -r above to see
possible values for range. Note: Remember that this will
affect what is displayed when -d and -s are used too.
Event Files
Event files are ASCII or UTF-8 text files (usually with a .pal
ending) that define events for pal to show. Example event files can
be found in /usr/share/pal. The first line in these files indicate
settings that apply to all of the events in the file. The first
line starts with two characters that should be used in the calendar
that pal displays. A longer description of the kinds of events in
the file follows the two characters. This description will be
displayed when the -r argument is used. All other lines in the file
are in the format date event. date defines when the event occurs
and event is a string that describes the event. Below is a
description of the different strings that can be used with date:
Events that occur only once
Use the format yyyymmdd.
Daily events
The format DAILY can be used for an event that happens every
day.
Weekly events
The format MON, TUE, WED, THU, FRI, SAT and SUN can be used
for an event that happens every week.
Monthly events
Use the format 000000dd.
Annual events
Use the format 0000mmdd.
Annual: Events that occur on the Nth day of a month.
Use the format *mmnd. Where d is the day (1 = Sunday, 7 =
Saturday). Example: *1023 (10=Oct; 2="second"; 3=Tuesday ==>
Second Tuesday in October, every year).
Monthly: Events that occur on the Nth day of a month.
Use the format *00nd. Where d is the day (1 = Sunday, 7 =
Saturday). Example: *0023 (2="second"; 3=Tuesday ==> Second
Tuesday of every month).
Annual: Events that occur on a certain last day of a month
Use the format *mmLd. Example: *10L3 (10=Oct; L=Last;
3=Tuesday ==> Last Tuesday in October). This is useful for
some holidays.
Monthly: Events that occur on a certain last day of a month
Use the format *00Ld. Example: *00L3 (3=Tuesday ==> Last
Tuesday of every month).
Todo events
The format TODO can be used for an event that always happens
on the day that you run pal. This enables you to use pal to
keep track of items in your todo list(s).
Easter related events
Use the format Easter for Easter Sunday. Use the format
Easter+nnn for events that occur nnn days after Easter. Use
the format Easternnn for events that occur nnn days before
easter.
Recurring events with start and end dates
If a recurring event has a starting date and an ending date,
you can use the date format DATE:START:END where DATE is a
recurring date format above. START and END are dates in the
yyyymmdd format that specify the starting and ending date of
the recurring event. START and END dates are inclusive. For
example, if an event happens every Wednesday in October 2010,
you could use this format: WED:20101001:20101031
Bi-weekly, Bi-annual, etc. events
If a recurring event does only occurs every Nth occurence,
you can add a /N to the event of the date string for that
event. A start date must be specified. For example, a bi-
monthly event that occurs on the first of the month can be
specified as 00000001/2:20000101.
INTERNATIONALIZATION AND LOCALIZATION
The calendar files that pal uses must be ASCII encoded or UTF-8 encoded
text files (ASCII is a subset of UTF-8). UTF-8 enables the calendar
files to work on any system regardless of the default encoding scheme.
When pal prints text, it converts the UTF-8 characters into the local
encoding for your system. If pal does not display international
characters and you are using a UTF-8 calendar file, check to make sure
that your locale is set correctly. You can see your locale settings by
running "locale". You can see the character set that pal is using for
output by running pal with "-v". If pal does not have a translation
for your language and you are interested in creating a translation, see
the po/README file that is distributed with the source code for pal.
FILES
~/.pal/pal.conf: Contains configuration information for pal and a list
of .pal text files that contain events.
/etc/pal.conf: This pal.conf file is copied to ~/.pal/pal.conf when a
user runs pal for the first time.
/usr/share/pal: Contains several calendar files for pal.
BUGS
Bugs may be reported via http://palcal.sourceforge.net/.
SEE ALSO
strftime(3), cal(1), regex(7)
SIMILAR PROGRAMS
pal is similar to BSD’s calendar program and GNU’s more complex gcal
program.
AUTHORS
Scott Kuhl
pal(1)