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 calendar 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  con-
       tains  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 param-
		 eter  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
		 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 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 calen-
       dar 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)