home | help 
pal(1)			     General Commands Manual			  pal(1)

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 expres-
	    sion (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  "Sub-
	    ject:"  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  ap-
	    pears;  if	you do not use a style sheet, the calendar will not have
	    any borders.   See	/usr/share/doc/pal/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  visi-
	    tors  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  ad-
	    justed 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 mi-
	nus YYYY.  This feature is particularly useful for birthdays.  For exam-
	ple,  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 set-
     tings 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  de-
     scribed 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  para-
	       meter  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 indi-
	       cated 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	informa-
	       tion.   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 possi-
	       ble 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 = Satur-
	       day).  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 = Satur-
	       day).   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 Easter-nnn 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 for-
	       mat 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 in-
     terested in creating a translation, see the po/README file that is distrib-
     uted 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  pro-
     gram.

AUTHORS
     Scott Kuhl

									  pal(1)
home | help