1pal(1)                      General Commands Manual                     pal(1)
2
3
4

NAME

6       pal - calendar with events
7

SYNOPSIS

9       pal [options]
10
11

DESCRIPTION

13       pal is a command‐line calendar utility.  It displays a cal(1)‐like cal‐
14       ender and events specified in text files.
15
16

OPTIONS

18       The following options are provided by pal:
19
20       -d date
21              Show events on the given date.  Valid formats for date  include:
22              dd,  mmdd,  yyyymmdd,  'yesterday', 'today', 'tomorrow', 'n days
23              away', 'n days ago', first two letters of weekday, 'next '  fol‐
24              lowed by first two letters of weekday, 'last ' followed by first
25              two letters of weekday, '1 Jan 2000', 'Jan 1 2000'.
26
27       -r n   Display events occurring in the next n  days  (counting  today).
28              By  default,  n  is 0 and no events are displayed.  For example,
29              using -r 1 makes pal display events occurring today.  If  -d  is
30              used  too,  the range is relative to date instead of the current
31              date.
32
33       -r p-n Display a list of events occurring  in  the  past  p  days  (not
34              counting today) and the next n days (counting today).  For exam‐
35              ple -r 1-1 will show yesterday's and today's events.  If  -d  is
36              used  too,  the range is relative to date instead of the current
37              date.
38
39       -s regex
40              Search for any occurrences of  an  event  matching  the  regular
41              expression  (regex)  occurring  in  the range of dates specified
42              with -r.  This command searches both the event  description  and
43              the  type  of  event  (specified at the top of a calendar file).
44              This search is case insensitive.
45
46       -x n   Expunge events that are n or more days old if they do not  occur
47              again  in the future.  pal will not expunge events from the cal‐
48              endars loaded from /usr/share/pal; even if you are root and  you
49              have added events to the calendars that are not recurring.  When
50              -x is used with -v, the events that are expunged  will  be  dis‐
51              played.
52
53       -c n   Display a calendar with n lines (default: 5).
54
55       -f file
56              Load file instead of ~/.pal/pal.conf.
57
58       -u username
59              Load /home/username/.pal/pal.conf instead of ~/.pal/pal.conf.
60
61       -p palfile
62              Override  the  .pal  files loaded from pal.conf.  This will only
63              load palfile.  For convenience, if palfile is a  relative  path,
64              pal  looks  for the file relative from ~/.pal/, if not found, it
65              tries relative to /usr/share/pal/, if not found it  tries  rela‐
66              tive  to your current directory.  (This behavior might change in
67              the future.)  Using an absolute path will work as you expect  it
68              to.
69
70       -m     Manage  events interactively.  Events can be added, modified and
71              deleted with this interface.
72
73       --color
74              Force use of colors, regardless of terminal type.
75
76       --nocolor
77              Do not use colors, regardless of terminal type.
78
79       --mail Generates output readable by  sendmail  by  adding  "From:"  and
80              "Subject:" fields and forcing --nocolor.  For example, you could
81              mail yourself a reminder of the upcoming events in the next week
82              with  pal --mail -r 7 | sendmail username.  Note: For the calen‐
83              dar to appear correctly, make sure your email client is using  a
84              fixed width font.
85
86       --html Generates  a  HTML  calendar suitable for display on a web page.
87              It does not generate a complete HTML document so  that  you  can
88              add  your  website's header and footer around the calendar.  The
89              number of months shown on the calendar can be adjusted with  -c.
90              You  will need to use Cascading Style Sheets (CSS) to change how
91              the calendar appears; if you do not use a style sheet, the  cal‐
92              endar  will  not have any borders.  See /usr/share/doc/pal/exam‐
93              ple.css for an example style.  SECURITY NOTE: If you set up  pal
94              so  it is being executed server‐side, it is recommended that you
95              do not allow web page visitors to directly change the parameters
96              sent to pal.  Allowing users to pass strange parameters (such as
97              extremely long ones) can be a security risk.
98
99       --latex
100              Generates a LaTeX source for a calendar that can be used to gen‐
101              erate a printer‐friendly DVI (run "pal --latex > file.tex; latex
102              file.tex"), PostScript or PDF  (run  "pal  --latex  >  file.tex;
103              pdflatex file.tex").  The number of months shown on the calendar
104              can be adjusted with -c.
105
106       -v     Verbose output.
107
108       --version
109              Display version information.
110
111       -h, --help
112              Display a help message.
113
114

EVENT DESCRIPTIONS

116       Years since year YYYY
117          pal will replace !YYYY! (where YYYY is a year) with the current year
118          minus YYYY.  This feature is particularly useful for birthdays.  For
119          example, the event text for a birthday could be: John Doe  was  born
120          on this day in 1990.  He is !1990! years old.
121
122       Sort by time
123          If  events have a time in the event description, pal will sort these
124          events by time.  The time in the event description must  be  of  the
125          format  h:mm or hh:mm (where hh is 0-23).  If an event has more than
126          one time in the event description, pal will sort the  event  by  the
127          first  time.  Events that do not have times in them are shown before
128          all the events that do have times.  Events without times are  sorted
129          in the order that they are loaded in pal.conf.
130
131
132

FILE FORMATS

134       Unless  -f  or  -u  is  used,  pal  looks for (or tries to create if it
135       doesn't exist) a configuration file  named  ~/.pal/pal.conf.   pal.conf
136       contains settings for pal and a list other files that contain events to
137       be displayed on the calendar.  The file formats for  pal.conf  and  the
138       event files are described below.
139
140       pal.conf
141
142          file filename [ (color) ]
143                 Loads  an event file named filename.  If filename isn't found
144                 in ~/.pal, pal will look for it in /usr/share/pal.  The color
145                 parameter is optional, it will display the events in the file
146                 with the given color.  Valid colors: black, red, green,  yel‐
147                 low, blue, magenta, cyan, white
148
149          file_hide filename [ (color) ]
150                 Loads  an  event  file  name  filename.  These events are not
151                 indicated in the calendar that is printed, but they are  dis‐
152                 played when the -r argument is used.  If filename isn't found
153                 in ~/.pal, pal will look for it in /usr/share/pal.  The color
154                 parameter is optional, it will display the events in the file
155                 with the given color.  Valid colors: black, red, green,  yel‐
156                 low, blue, magenta, cyan, white
157
158          event_color color
159                 The default color used for events.  Valid colors: black, red,
160                 green, yellow, blue, magenta, cyan, white
161
162          week_start_monday
163                 If this keyword is defined, the calendar weeks start on  Mon‐
164                 day instead of Sunday.
165
166          date_fmt string
167                 Changes  how  dates  are displayed when the -r -d or -s argu‐
168                 ments are used.  string can be a date format string that fol‐
169                 lows  the  format used by strftime(3).  Type man strftime for
170                 more information.  string is set to %a %e %b  %Y  by  default
171                 (example: Sun  8 Aug 2010).
172
173          reverse_order
174                 Display all event listings in descending order.
175
176          hide_event_type
177                 Hide  the  event  type  (shown  in before a ':') when listing
178                 events.  The event type is defined at the  top  of  the  file
179                 that the event is found in.
180
181          cal_on_bottom
182                 Display calendar at the end of the output.
183
184          no_columns
185                 Display calendar in one column instead of two.
186
187          compact_list
188                 List  events  that  are shown when using -r in a more compact
189                 form.
190
191          compact_date_fmt
192                 Format for the date displayed when compact_list is used.  See
193                 date_fmt for more information.
194
195          default_range range
196                 If  you get tired of always using -r, you can set the default
197                 value for -r here.  See the information on -r  above  to  see
198                 possible  values  for  range.   Note: Remember that this will
199                 affect what is displayed when -d and -s are used too.
200
201
202       Event Files
203          Event files are ASCII or UTF-8 text files (usually with a .pal  end‐
204          ing) that define events for pal to show.  Example event files can be
205          found in /usr/share/pal.  The first line  in  these  files  indicate
206          settings  that  apply  to  all of the events in the file.  The first
207          line starts with two characters that should be used in the  calendar
208          that  pal  displays.  A longer description of the kinds of events in
209          the file follows the two characters.  This description will be  dis‐
210          played  when  the  -r argument is used.  All other lines in the file
211          are in the format date event.  date defines when  the  event  occurs
212          and event is a string that describes the event.  Below is a descrip‐
213          tion of the different strings that can be used with date:
214
215          Events that occur only once
216                 Use the format yyyymmdd.
217
218          Daily events
219                 The format DAILY can be used for an event that happens  every
220                 day.
221
222          Weekly events
223                 The  format  MON, TUE, WED, THU, FRI, SAT and SUN can be used
224                 for an event that happens every week.
225
226          Monthly events
227                 Use the format 000000dd.
228
229          Annual events
230                 Use the format 0000mmdd.
231
232          Annual: Events that occur on the Nth day of a month.
233                 Use the format *mmnd.  Where d is the day (1 =  Sunday,  7  =
234                 Saturday).  Example: *1023 (10=Oct; 2="second"; 3=Tuesday ==>
235                 Second Tuesday in October, every year).
236
237          Monthly: Events that occur on the Nth day of a month.
238                 Use the format *00nd.  Where d is the day (1 =  Sunday,  7  =
239                 Saturday).   Example: *0023 (2="second"; 3=Tuesday ==> Second
240                 Tuesday of every month).
241
242          Annual: Events that occur on a certain last day of a month
243                 Use  the  format  *mmLd.   Example:  *10L3  (10=Oct;  L=Last;
244                 3=Tuesday  ==>  Last Tuesday in October).  This is useful for
245                 some holidays.
246
247          Monthly: Events that occur on a certain last day of a month
248                 Use the format *00Ld.  Example:  *00L3  (3=Tuesday  ==>  Last
249                 Tuesday of every month).
250
251          Todo events
252                 The  format TODO can be used for an event that always happens
253                 on the day that you run pal.  This enables you to use pal  to
254                 keep track of items in your todo list(s).
255
256          Easter related events
257                 Use  the  format  Easter  for  Easter Sunday.  Use the format
258                 Easter+nnn for events that occur nnn days after Easter.   Use
259                 the  format  Easter‐nnn for events that occur nnn days before
260                 easter.
261
262          Recurring events with start and end dates
263                 If a recurring event has a starting date and an ending  date,
264                 you  can  use  the date format DATE:START:END where DATE is a
265                 recurring date format above.  START and END are dates in  the
266                 yyyymmdd  format that specify the starting and ending date of
267                 the recurring event.  START and END dates are inclusive.  For
268                 example, if an event happens every Wednesday in October 2010,
269                 you could use this format: WED:20101001:20101031
270
271          Bi-weekly, Bi-annual, etc. events
272                 If a recurring event does only occurs  every  Nth  occurence,
273                 you  can  add  a  /N to the event of the date string for that
274                 event.  A start date must be specified.  For example,  a  bi-
275                 monthly  event  that  occurs on the first of the month can be
276                 specified as 00000001/2:20000101.
277
278
279

INTERNATIONALIZATION AND LOCALIZATION

281       The calendar files that pal uses must be ASCII encoded or UTF-8 encoded
282       text  files  (ASCII  is a subset of UTF-8).  UTF-8 enables the calendar
283       files to work on any system regardless of the default encoding  scheme.
284       When  pal  prints text, it converts the UTF-8 characters into the local
285       encoding for your system.  If pal does not display international  char‐
286       acters and you are using a UTF-8 calendar file, check to make sure that
287       your locale is set correctly.  You can see your locale settings by run‐
288       ning  "locale".   You  can  see the character set that pal is using for
289       output by running pal with "-v".  If pal does not  have  a  translation
290       for your language and you are interested in creating a translation, see
291       the po/README file that is distributed with the source code for pal.
292
293
294
295
296

FILES

298       ~/.pal/pal.conf: Contains configuration information for pal and a  list
299       of .pal text files that contain events.
300
301       /etc/pal.conf:  This  pal.conf file is copied to ~/.pal/pal.conf when a
302       user runs pal for the first time.
303
304       /usr/share/pal: Contains several calendar files for pal.
305
306

BUGS

308       Bugs may be reported via http://palcal.sourceforge.net/.
309
310

SEE ALSO

312       strftime(3), cal(1), regex(7)
313
314

SIMILAR PROGRAMS

316       pal is similar to BSD's calendar program and GNU's  more  complex  gcal
317       program.
318
319

AUTHORS

321       Scott Kuhl
322
323
324
325                                                                        pal(1)
Impressum