1pal(1) General Commands Manual pal(1)
2
6 pal - calendar with events
7
9 pal [options]
10
13 pal is a command‐line calendar utility. It displays a cal(1)‐like cal‐
14 ender and events specified in text files.
15
18 The following options are provided by pal:
19 -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 -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 -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 -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 -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 -c n Display a calendar with n lines (default: 5).
54 -f file
56 Load file instead of ~/.pal/pal.conf.
57 -u username
59 Load /home/username/.pal/pal.conf instead of ~/.pal/pal.conf.
60 -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 -m Manage events interactively. Events can be added, modified and
71 deleted with this interface.
72 --color
74 Force use of colors, regardless of terminal type.
75 --nocolor
77 Do not use colors, regardless of terminal type.
78 --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 --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 --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 -v Verbose output.
107 --version
109 Display version information.
110 -h, --help
112 Display a help message.
113
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 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
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 pal.conf
141 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 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 event_color color
159 The default color used for events. Valid colors: black, red,
160 green, yellow, blue, magenta, cyan, white
161 week_start_monday
163 If this keyword is defined, the calendar weeks start on Mon‐
164 day instead of Sunday.
165 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 reverse_order
174 Display all event listings in descending order.
175 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 cal_on_bottom
182 Display calendar at the end of the output.
183 no_columns
185 Display calendar in one column instead of two.
186 compact_list
188 List events that are shown when using -r in a more compact
189 form.
190 compact_date_fmt
192 Format for the date displayed when compact_list is used. See
193 date_fmt for more information.
194 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 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 Events that occur only once
216 Use the format yyyymmdd.
217 Daily events
219 The format DAILY can be used for an event that happens every
220 day.
221 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 Monthly events
227 Use the format 000000dd.
228 Annual events
230 Use the format 0000mmdd.
231 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 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 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 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 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 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 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 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
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
298 ~/.pal/pal.conf: Contains configuration information for pal and a list
299 of .pal text files that contain events.
300 /etc/pal.conf: This pal.conf file is copied to ~/.pal/pal.conf when a
302 user runs pal for the first time.
303 /usr/share/pal: Contains several calendar files for pal.
305
308 Bugs may be reported via http://palcal.sourceforge.net/.
309
312 strftime(3), cal(1), regex(7)
313
316 pal is similar to BSD's calendar program and GNU's more complex gcal
317 program.
318
321 Scott Kuhl
322 pal(1)