1PCAL(1) USER COMMANDS PCAL(1) 2 3 4 5NNAAMMEE 6 pcal - generate PostScript (or HTML) calendars 7 8SSYYNNOOPPSSIISS 9 ppccaall [--ee|--ff _c_a_l] [--oo _f_i_l_e] [--ll | --pp] [--PP [letter | legal | a4 | 10 tabloid]] [--jj | --JJ] [--mm | --MM] [--gg _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday] 11 [--OO _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday] [--GG _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holi- 12 day] [--bb _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday] [--ss [_d_a_y___n_u_m_e_r_- 13 _i_c_s___c_o_l_o_r][/_e_m_p_t_y___d_a_y___b_o_x___f_i_l_l___c_o_l_o_r]] [--FF _d_a_y] [--AA|--EE] 14 [--XX _x_t_r_a_n_s] [--YY _y_t_r_a_n_s] [--xx _x_s_c_a_l_e] [--yy _y_s_c_a_l_e] 15 [--tt [_t_i_t_l_e___f_o_n_t][/_s_i_z_e]] [--dd [_d_a_y___f_o_n_t][/_s_i_z_e]] 16 [--nn [_t_e_x_t___f_o_n_t][/_s_i_z_e]] [--LL _f_o_o_t_e_r___s_t_r] [--CC _f_o_o_t_e_r___s_t_r] 17 [--RR _f_o_o_t_e_r___s_t_r] [--NN _n_o_t_e_s___s_t_r] [--DD _s_y_m_b_o_l] [--UU _s_y_m_b_o_l] [--BB] [--## _n] 18 [--SS | --kk | --KK] [--ww] [--II] [--cc | --HH] [--qq] [--zz _t_i_m_e___z_o_n_e] 19 [--hh | --uu | --vv] [--aa _o_u_t_p_u_t___l_a_n_g_u_a_g_e] [--rr [_m_a_p_p_i_n_g] [--TT [B|I|R]] 20 [--WW [left|center|right]] [month] [year] [nmonths] 21 22 23 24DDEESSCCRRIIPPTTIIOONN 25 _P_c_a_l generates PostScript to produce landscape or portrait calendars 26 for any month and year. The arguments mmoonntthh, yyeeaarr, and nnmmoonntthhss, if 27 provided, should be numeric. The mmoonntthh value should be in the range 1 28 - 12, and the yyeeaarr value should be specified as 1 or 2 digits (in which 29 case it will be interpreted as that year in the current century) or as 30 the full 4-digit year. If no numeric arguments are provided, the cal- 31 endar for the current month and year will be generated. 32 33 If one numeric argument is provided, it is interpreted as the yyeeaarr 34 value, and calendars for the entire year will be generated. Otherwise, 35 nnmmoonntthhss months, starting with mmoonntthh and yyeeaarr, will be generated. 36 37 For whole-year calendars (i.e. when the --ww option is given), the com- 38 mand line arguments are interpreted somewhat differently. By default, 39 all months in the current year are printed, starting with January. If 40 the mmoonntthh argument alone is given, it is expected to be the desired 41 yyeeaarr to print, and prints all of the months in the given year. If both 42 mmoonntthh and yyeeaarr are given, then 12 consecutive months are printed start- 43 ing at the given month and year. If the mmoonntthh, yyeeaarr, and nnmmoonntthhss argu- 44 ments are all present, printing begins with the given month and year 45 and nnmmoonntthhss months are printed, rounded up to the nearest multiple of 46 12. 47 48 49 50 TThhee DDaattee FFiillee ((CCoonnffiigguurraattiioonn FFiillee)) 51 By default, _p_c_a_l simply prints an empty calendar. Its real power is in 52 its ability to place ``events'' (and, for monthly-format PostScript 53 calendars, Encapsulated PostScript images [e.g. photos and icons]) in 54 appropriate days on the (PostScript or HTML) calendar, thus allowing 55 the user to create personalized calendars. This is achieved through 56 the use of the ``date file'', also known as the ``configuration file''. 57 58 The default date/configuration file is expected to be named _._c_a_l_e_n_d_a_r 59 (_p_c_a_l_._d_a_t under MS-DOS), or _c_a_l_e_n_d_a_r for compatibility with older ver- 60 sions. _P_c_a_l will look in several places for such a file. First, if 61 the environment variable PPCCAALL__DDIIRR is defined, _p_c_a_l searches the direc- 62 tory indicated by that variable. Next, _p_c_a_l searches the user's home 63 directory (as specified by the HHOOMMEE environment variable). If neither 64 PPCCAALL__DDIIRR nor HHOOMMEE is defined, _p_c_a_l searches the current directory 65 instead. Finally, if enabled (via the `SEARCH_PCAL_DIR' flag) when 66 _p_c_a_l was built, the directory where the _p_c_a_l executable resides will be 67 checked. If no date file is found, an empty calendar is printed; no 68 error is generated. 69 70 Alternatively, the name of the date file (and, optionally, the path 71 where it can be found) can be specified using the --ff command-line 72 option. See the OOPPTTIIOONNSS section for more details. 73 74 Every _p_c_a_l distribution comes with an 'examples' directory. The `pcal- 75 cfg.txt' file that is located there contains a myriad of examples of 76 settings that can be used in your own configuration file. Please check 77 it out for lots of useful ideas. Furthermore, that directory contains 78 several language/country-specific examples (including holiday and other 79 event definitions) in various `calendar_xx.txt' files, where `xx' rep- 80 resents the 2-letter language code (e.g. 'calendar_de.txt' is the Ger- 81 man example file). 82 83 If a date file is found, it will be searched for lines with leading 84 dates matching the requested month and year. 85 86 Any text following the dates found will be printed on the calendar 87 under the appropriate day of the month. Encapsulated PostScript (EPS) 88 images are handled similarly as described in a later subsection. 89 90 ttrrooffff-style escape sequences \fB, \fI, \fP, and \fR may be used to set 91 the font style to Bold, Italic, the previous font style, or Roman 92 respectively. For those more familiar with HTML, <B>, <I>, </B>, and 93 </I> may be used instead to enable/disable Bold or Italic font styles. 94 The font style is reset to Roman after each line break. 95 96 Using the `include' pre-processor directive (described in the section 97 entitled `Pre-Processor Functionality', below), other configuration 98 files can be processed from within an existing configuration file. 99 That is, you can `nest' configuration files as needed. 100 101 Dates (essentially `events') in the configuration files may be 102 expressed in any of several formats: 103 104 105 � <ordinal> <day_spec> in <month_spec>{*} {<text>} 106 107 � {<ordinal>} <day_spec> <prep> <date_spec>{*} {<text>} 108 109 � <date_spec>{*} {<text>} 110 111 � <pre_defined_event>{*} {<text>} 112 113 Where: 114 115 116 <month_name> := first 3+ characters of name of month, or 117 ``all'' 118 119 NNoottee:: _p_c_a_l looks for names of the days of the 120 week prior to names of months when parsing event 121 date specifications. Furthermore, some languages 122 (e.g. French and Finnish) have a month name whose 123 first 3 letters are the same as the first 3 let- 124 ters of one of the names of the days of the week. 125 Because of this, the specification in such a lan- 126 guage of any month name which collides thusly 127 must use 4 or more letters to distinguish it from 128 the name of the day of the week with which it 129 `collides'. 130 131 <month_spec> := <month_name>, or ``year'' 132 133 <day_spec> := first 3+ characters of name of weekday, 134 ``day'', ``weekday'', ``workday'', ``holiday'', 135 ``nonweekday'', ``nonworkday'', ``nonholiday'', 136 ``new_moon'', ``first_quarter'', ``full_moon'', 137 or ``last_quarter'' 138 139 <ordinal> := any ordinal number (``1st'', ``2nd'', etc.), 140 ``first'' ... ``fifth'', ``last'', ``odd'', 141 ``even'', or ``all'' 142 143 <prep> := ``on'', ``before'', ``preceding'', ``after'', 144 ``following'', ``on_or_before'' (``oob''), 145 ``on_or_after'' (``ooa''), ``nearest'', ``near- 146 est_before``, or ``nearest_after`` 147 148 <pre_defined_event> 149 := ``Christmas'', ``Thanksgiving'', ``Easter'', 150 ``Good_Friday'', ``GEaster'' (Orthodox Easter), 151 ``Gstgeorge'' (Orthodox holiday), and ``Gmarcus'' 152 (Orthodox holiday). 153 154 <sep> := one or more non-numeric, non-space, non-`*' 155 characters 156 157 <month> := a numeric month (1-12) 158 159 <day> := day of month (1-31) 160 161 <year> := a numeric year 162 163 <text> := the text to be displayed for this event; if 164 the text begins with the constant string 165 ``image:'', then it is interpreted as a specifi- 166 cation of an Encapsulated PostScript (EPS) image 167 rather than as simple text; more information on 168 specifying EPS images is available in a later 169 section of this document 170 171 If the --AA option (American date formats, the default) is given: 172 173 174 <date_spec> := <month_name> <day> | 175 <month><sep><day>{<sep><year>} 176 177 If the --EE option (European date formats) is given: 178 179 180 <date_spec> := <day> <month_name> | <day> <month> | 181 <day><sep><month>{<sep><year>} 182 183 184 The ``Notes'' box (see below) uses the first of the current month as 185 the default date. All footer strings use the first of the current 186 month in single-month mode and the first of the starting month in 187 whole-year mode. 188 189 Examples: 190 191 last Monday in May* Memorial Day Holiday 192 193 all Fridays in Oct Status Meeting, 11 AM 194 first workday in all %-B progress report due 195 all Fri in all \fBTime card due,\fP 3 PM 196 all Monday in all Fiscal week %0W 197 -2nd workday in all Schedule for %+B due %+2D 198 2nd full_moon in all Blue Moon 199 Fri on_or_before all 15 Pay Day 200 even Fridays in year Pay Day 201 183rd day of year Mid-year (%l days left) 202 203 Tue after first Mon in Nov Election Day (USA) 204 205 4th Thu in Nov* Thanksgiving 206 Fri after 4th Thu in Nov* Day after Thanksgiving 207 workday nearest 12/25* Holiday 208 209 12/25/04* Christmas # American 210 25.12.04* Christmas # European 211 25. 12.* Christmas # European 212 213 Dec 25* Christmas # American 214 25 Dec* Christmas # European 215 25. Dec* Christmas # European 216 217 Fri on all 13 Avoid black cats! # 'Friday the 13th' 218 219 Any non-numeric character may separate numeric dates. Holidays may be 220 flagged by following the date immediately with `*' as in the examples 221 above; this will cause the date numerics to be printed in the color 222 specified by the --ss option (default = gray) and will cause the associ- 223 ated text (on monthly-format calendars) to be placed adjacent to the 224 numeric date in the day box rather than below the numeric date (as is 225 done for all non-holiday events). ``Each'' and ``every'' are accepted 226 as synonyms for ``all'', and any word may be used in place of ``in''. 227 The abbreviations ``oob'' and ``ooa'' may be used in place of the key- 228 words ``on_or_before'' and ``on_or_after'', respectively. ``Nearest'' 229 attempts to match the specified date; if that fails, it tries the day 230 after, then the day before, then two days after, two days before, and 231 so forth until a match occurs. 232 233 Wildcard day names are also provided. The keyword ``weekday'' applies 234 to any days which are normally printed in "logical black" - the predom- 235 inant day color - on the calendar. The keyword ``workday'' is the 236 same, but does not include any holidays. The keyword ``holiday'' 237 includes only those days flagged as holidays. The keywords ``nonweek- 238 day'', ``nonworkday'', and ``nonholiday'' are also recognized as nega- 239 tions of the above. See the CCAAVVEEAATTSS below for important notes on using 240 these keywords. Moon phases may also appear as wildcards; ``nm'' is 241 accepted as a synonym for ``new_moon'', ``1q'' and ``fq'' for 242 ``first_quarter'', ``fm'' for ``full_moon'', ``3q'' for ``third_quar- 243 ter'', and ``lq'' for ``last_quarter''. 244 245 Ordinal day numbers may be used to specify dates, either relative to 246 the month or to the year. Either words or numeric abbreviations may be 247 used for ``first'' through ``fifth''; higher numbers must be given 248 using the numeric equivalent (e.g. 100th). Negative ordinal numbers 249 may even be used. For example, ``-2nd'' means ``next to last''. 250 251 ``Odd'' and ``even'' do not refer to the actual date; instead, ``odd'' 252 means ``alternate, starting with the first'', and ``even'' means 253 ``alternate, starting with the second''. Thus, ``odd Fridays in 254 March'' refers to the first, third, and (if present) fifth Fridays in 255 March -- not to those Fridays falling on odd dates. 256 257 ``All'' refers to each individual month; ``year'' refers to the year as 258 an entity. Thus ``odd Fridays in all'' refers to the first, third, and 259 fifth Friday of each month, while ``odd Fridays in year'' refers to the 260 first Friday of January and every other Friday thereafter. 261 262 ``Nearest'', ``nearest_before'', and ``nearest_after'' refer to the 263 nearest weekday or wildcard day with respect to the specified date. 264 ``Nearest_before'' and ``nearest_after'' allow the user to specify how 265 _p_c_a_l is to disambiguate between two dates that are equally near: e.g., 266 ``nonweekday nearest_before [Wed.] 9/25/96'' refers to Sunday, 9/22 267 while ``nonweekday nearest_after 9/25/96'' refers to Saturday, 9/28. 268 (Note that ``nearest_before'' and ``nearest_after'' are equivalent to 269 ``nearest'' when no such ambiguity exists: e.g., ``nonweekday near- 270 est_before [Thu.] 9/26/96'' refers to Saturday, 9/28.) 271 272 Text in the date file may use C-like escape sequences (i.e. a `\' fol- 273 lowed by a character, 1 - 3 octal digits, or `x' followed by 1 - 2 274 hexadecimal digits). Escaped whitespace (including nneewwlliinnee ) and the 275 standard ANSI character escapes (`\a', `\b', `\f', `\n', `\r', `\t', 276 `\v') are all replaced by a single blank. 277 278 The HTML special characters `<' `>' `"' `&' ` ' and 279 `&#NNN;' (NNN = any three decimal digits) are also supported. These 280 will be propagated intact (be sure to escape the `#' in `&#NNN;') if 281 the output is specified as HTML (see the --HH flag); otherwise they will 282 be converted to their ASCII equivalents. This allows a common date 283 file to be used regardless of whether the desired output format is 284 HTML, PostScript, or Un*x _c_a_l_e_n_d_a_r_(_1_) (see the --cc flag) input. 285 286 Lines in the configuration file consisting of yyeeaarr ######## (where ######## is 287 a numeric year) can be used to set the year for following entries. 288 This assumes that the following entries do not contain a year; any date 289 entries containing year information will set the remembered year to 290 that year. 291 292 Lines in the configuration file consisting of yyeeaarr aallll (or, alterna- 293 tively, yyeeaarr **) direct _p_c_a_l to wildcard following entries against every 294 applicable year. This assumes that the following entries do not con- 295 tain a year; any date entries containing year information (or an 296 explicit yyeeaarr ######## entry) will set the remembered year to that year. 297 298 Lines in the configuration file consisting of oopptt <<ooppttiioonnss>> can be used 299 to override the defaults for any command-line options except --cc, --ee, 300 --ff, --hh, --HH, --uu, --vv, --DD, and --UU. Any options specified in this manner 301 are, in turn, overridden by those specified explicitly on the command 302 line. 303 304 Lines in the configuration file consisting of nnoottee{{//<<nnuummbbeerr>>}} <<mmoonntthh>> 305 can be used to place notes regarding the entire month in one of the 306 unused blocks of the calendar. The <<mmoonntthh>> indicator may be either a 307 number 1 through 12 or an alphabetic month name as described above; 308 ``note all'' will place the associated text in the notes block for each 309 month in the current year. <<nnuummbbeerr>> is an optional positive or nega- 310 tive number specifying the empty box where the associated text is to be 311 placed. If positive, _p_c_a_l counts forward from the first empty box; if 312 negative, _p_c_a_l counts backward from the last empty box. Thus, 313 ````nnoottee//11'''' places the associated text in the first empty box; nnoottee//--33 314 in the third-to-last. The default is -1 if no <number> is given (last 315 empty box, immediately preceding the small calendars on the bottom row; 316 cf. --SS, --kk, and --KK, below). You can place several notes in the same 317 box. You can also use more than 1 box for the various monthly notes. 318 319 Lines in the configuration file consisting of iinnppuutt--llaanngguuaaggee XXXX (where 320 XXXX is the 2-letter specification for any of the supported languages) 321 can be used to set the language used for interpretation of the month 322 names and day-of-week names for the remaining event entries. This 323 option may be specified more than once, as needed, if the language used 324 to describe events changes within the file. For backwards compatibil- 325 ity, the default value for `input language' if this directive is never 326 used is 'en' (English). Note that this directive is distinct from the 327 specification of 'output language' as accomplished with the --aa option. 328 329 Comments are supported in the configuration file. Any characters fol- 330 lowing a `#' character are ignored, through the end of that line, 331 unless the `#' character is escaped by `\'. 332 333 334 335 DDeelleettiinngg EEvveennttss 336 By prepending the _`_d_e_l_e_t_e_' keyword to an event specification, one or 337 more events may be deleted from a set of previously-specified events. 338 339 340 For example, the following lines might appear in the date file: 341 342 343 all Friday in all Poker game 344 delete first Friday in all Poker game 345 346 This results in an event labeled `Poker game' on every Friday except 347 the first Friday of the month. If you delete an entry which is marked 348 as a holiday, the `holiday' flag for that day will be recalculated. 349 Any `delete' entries which don't match any pre-existing entries are 350 silently ignored. 351 352 353 354 FFoorrmmaatt SSppeecciiffiieerrss 355 _P_c_a_l allows format specifiers in both the event text and footer strings 356 (see the --LL, --CC, --RR, and --NN options below). Each format specifier will 357 be replaced by a corresponding string as outlined in the following ta- 358 ble: 359 360 %a abbreviated weekday 361 %A full weekday 362 %b abbreviated month name 363 %B full month name 364 %d day of month (1-31) 365 %j day of year (1-366) 366 %l days left in year (0-365) 367 %m month (1-12) 368 %U week number (0-53) 369 %W week number (0-53) 370 %u week number (1-54) 371 %w week number (1-54) 372 %y year w/o century (00-99) 373 %Y year w/century 374 %% `%' character 375 376 %o print number as ordinal 377 %0 print number with leading zeroes 378 %+ use following month or year 379 %- use previous month or year 380 %{+N}[DWMY] adjust date by +N days/weeks/months/years 381 %{-N}[DWMY] adjust date by -N days/weeks/months/years 382 383 Most of these are derived from the ANSI C strftime() function, but the 384 %%[[lloouuwwMMDD]] and %%[[oo00++--]] format specifiers are specific to _p_c_a_l. 385 386 The %%uu specifier considers the week containing 1/1 (Jan 1st) as week 1 387 and the following logical Sunday (the first day of the week as printed; 388 cf. the --FF option below) as the start of week 2; %%UU considers the first 389 logical Sunday as the first day of week 1. %%ww and %%WW behave like %%uu 390 and %%UU respectively, but use the first logical Monday instead. Note 391 that %%ww has a different meaning from strftime(). 392 393 The %%oo format specifier prints a number as an ordinal, with the appro- 394 priate suffix (``st'', ``nd'', ``rd'', or ``th'' in English) appended. 395 For example, %%oodd prints the day of the month as ``1st'', ``2nd'', 396 ``3rd'', etc. 397 398 Unlike strftime(), _p_c_a_l defaults to printing numbers (except %%yy) with- 399 out leading zeroes. If leading zeroes are desired, the `0' prefix may 400 be used. For example, %%00jj prints the first day of year as ``001''. 401 402 The %%++ and %%-- format specifiers direct _p_c_a_l to substitute the follow- 403 ing/previous month/year in the following [[bbBBmmyyYY]] specifier. For exam- 404 ple, %%++BB prints the name of the next month. 405 406 The %%{{[[++--]]NN}}[[DDWWMMYY]] format specifiers do not print anything, but instead 407 adjust the working date by � NNdays (DD), weeks (WW), months (MM), or years 408 (YY). Subsequent format specifiers use the adjusted date instead of the 409 current date. For example, %%++11MM %%BB %%YY adjusts the date forward by one 410 month and then prints the resulting month and year (``January 1992'' in 411 December, 1991); %%--22WW %%bb %%dd adjusts the date backward by two weeks and 412 prints the resulting month and day (``Jul 26'' on August 9). 413 414 Such date adjustments are normally cumulative; for example, %%++11YY%%--11DD 415 adjusts the date forward by one year and then backward by one day. If 416 %%DD or %%MM is specified alone (or if NN is zero), _p_c_a_l restores the origi- 417 nal date. Note that %%MM has a different meaning to the strftime() func- 418 tion. 419 420 Here's a common, useful example of an event entry for the _p_c_a_l date 421 file which combines the ability to adjust working dates and the ability 422 to display ordinals. This particular example is used to display text 423 on the birthday of a person born in 1991: 424 425 May 10 Eric's %-1991Y%oY Birthday 426 427 That entry would result in the following text being displayed on May 428 10, 2005: 429 430 431 Eric's 14th Birthday 432 433 434 435 436 EEnnccaappssuullaatteedd PPoossttSSccrriipptt ((EEPPSS)) IImmaaggeess 437 For monthly PostScript calendars only, _p_c_a_l supports the embedding of 438 one or more EPS images (photos, icons, etc) into any given day of the 439 month. (EPS image specifications in the _p_c_a_l date file are ignored for 440 yearly PostScript calendars and for all HTML calendars.) 441 442 In order to associate an image with a given event, you must add one or 443 more entries to the date file. The event date is specified exactly as 444 described previously for simple event text specification lines. How- 445 ever, instead of specifying the text associated with the event, you 446 instead specify the EPS image filename and some additional parameters 447 in the following format: 448 449 image:<EPS-image-filename> <x-scale> <y-scale> <x-delta> <y-delta> 450 451 Where: 452 453 454 <EPS-image-filename> is the filename (which can include a path) 455 of the Encapsulated PostScript image. 456 NNoottee:: The EPS image filename must be pre- 457 ceded by the constant text `image:' in 458 order to distinguish an EPS image specifi- 459 cation from an ordinary event text specifi- 460 cation. 461 462 <x-scale> is a scaling factor in the horizontal 463 dimension for the EPS image. A value of 464 1.0 is nominal (i.e. no change to image 465 scale). Values between 0.0 and 1.0 shrink 466 the image in the horizontal dimension while 467 values over 1.0 expand the image in the 468 horizontal dimension. Generally speaking, 469 only positive values should be used. How- 470 ever, in the rare case that you find that 471 your EPS image needs to be flipped about 472 the vertical axis (i.e. left to right), you 473 can use a negative value to achieve this 474 without having to tweak the actual Post- 475 Script content within the EPS image file. 476 Use of a negative value will undoubtedly 477 necessitate a corresponding change to the 478 <x-delta> parameter to account for the 479 image's relocated position that occurs when 480 it gets flipped "left-to-right". 481 482 <y-scale> is a scaling factor in the vertical dimen- 483 sion for the EPS image. Values between 0.0 484 and 1.0 shrink the image in the vertical 485 dimension while values over 1.0 expand the 486 image in the vertical dimension. Note that 487 a negative value for this parameter can be 488 useful in the less-than-rare case that you 489 find that your EPS image needs to be 490 flipped about the horizontal axis (i.e. top 491 to bottom). In such cases, you can use a 492 negative <y-scale> value to achieve this 493 without having to tweak the actual Post- 494 Script content within the EPS image file. 495 Use of a negative value will undoubtedly 496 necessitate a corresponding change to the 497 <y-delta> parameter to account for the 498 image's relocated position that occurs when 499 it gets flipped "upside down". 500 501 <x-delta> := a horizontal adjustment in typographic 502 `points' (i.e. 72nds of an inch) for the 503 positioning of the EPS image. With offsets 504 of 0 for X and Y, the image will be printed 505 at the extreme left edge of the box for 506 that day, just under the numerics for that 507 day. Positive values move the image to the 508 right and negative values move the image to 509 the left. 510 511 <y-delta> := a vertical adjustment in typographic 512 `points' (i.e. 72nds of an inch) for the 513 positioning of the EPS image. With offsets 514 of 0 for X and Y, the image will be printed 515 at the extreme left edge of the box for 516 that day, just under the numerics for that 517 day. Positive values move the image up and 518 negative values move the image down. 519 520 Here's an example of a line from the date file that associates an EPS 521 image with an event: 522 523 4th Thu in Nov* Thanksgiving 524 4th Thu in Nov* image:/eps-path/turkey.eps 1.0 1.0 0 0 525 526 You can place as many images as you want on a single day of the month 527 by specifying repeated lines in the date file. For example, these 528 lines put icons of George Washington and Abraham Lincoln on the day of 529 the U.S. ``Presidents' Day'' holiday, along with the event text: 530 531 3rd Monday in Feb* Presidents' Day 532 3rd Monday in Feb* image:/eps-path/washington.eps 0.08 0.08 8 0 533 3rd Monday in Feb* image:/eps-path/lincoln.eps 0.22 0.22 48 0 534 535 Note that the icon for Lincoln is shifted to the right by 48 typo- 536 graphic points so as not to overlay the first icon. 537 538 The _p_c_a_l releases come with a single EPS sample file ('eps/recy- 539 cle.eps') of the ubiquitous 'recycle' icon (3 green arrows in a trian- 540 gular shape). Such an image might be used with configuration file set- 541 tings like this: 542 543 second Sat in all RECYCLE! 544 second Sat in all image:/eps-path/recycle.eps 0.039 0.039 34 -9 545 546 In cases where you're displaying non-holiday event text (e.g. someone's 547 birthday) and an EPS image, you'll often need to use a negative `Y- 548 delta' value on the EPS image specification line, in order to shift the 549 image down so that it doesn't cover the event text, which appears just 550 below the day's numerics for non-holiday events. (Text for holiday 551 events appears higher up, to the right of the day's numerics, so 552 there's usually no collision with the EPS image.) 553 554 NNoottee:: Unfortunately, most EPS images cannot be used directly by _p_c_a_l. 555 556 557 Depending on the EPS image used and how it was created, you may 558 have to remove or comment out some or all of the PostScript 559 `translate' commands, in order to avoid the use of illogical X- 560 delta and Y-delta values when specifying the EPS image in your 561 _p_c_a_l date file. Most programs that generate EPS output (either 562 directly or via conversion from some other graphic format) seem 563 to have these `translate' commands relatively early in the EPS 564 file. 565 566 It may take some experimentation to get it just right. Preview 567 the _p_c_a_l output using a PostScript viewer as you tweak the Post- 568 Script commands in the EPS image file and/or the event entry in 569 the _p_c_a_l date file. 570 571 NNoottee:: Depending upon what application you use to preview 572 PostScript content, the monthly calendars may not show 573 any embedded EPS images. Here's a rundown of some popu- 574 lar PostScript-viewing applications and whether they cor- 575 rectly display the embedded EPS images: 576 577 578 � gv (version 3.5.8) -- EPS images appear fine 579 580 � ggv (versions 2.4.0.1 and 2.6.1) -- EPS images 581 appear fine 582 583 � older kghostview (versions 0.13.2 [KDE 3.1.4] 584 and 0.2.0 [KDE 3.2.3 and 3.3.2]) -- EPS images 585 DO NOT APPEAR! 586 587 � newer kghostview (version 0.2.0 [KDE 3.4.2 and 588 3.5.4]) -- EPS images appear fine 589 590 591 592 For converting non-EPS images (e.g. photos) to EPS format, one can use 593 the graphical GNU Image Manipulation Program, a.k.a. `The GIMP': 594 595 _h_t_t_p_:_/_/_w_w_w_._g_i_m_p_._o_r_g 596 597 598 For icons/images in WMF format (which are popular in various 3rd-party, 599 legacy-OS, commercial calendar programs), the `libwmf'/`wmf2eps' 600 library/utility is useful for generating _p_c_a_l-capable EPS images. It 601 can be found at this site: 602 603 _h_t_t_p_:_/_/_w_v_w_a_r_e_._s_o_u_r_c_e_f_o_r_g_e_._n_e_t_/_l_i_b_w_m_f_._h_t_m_l 604 605 606 For icons/images in SVG format, the ImageMagick `convert' utility is 607 sometimes useful for generating _p_c_a_l-capable EPS images. This suite of 608 utilities (which includes other useful ImageMagick utilities like `dis- 609 play' and `identify') may already be available on your Linux distribu- 610 tion. If not, it can be found at this site: 611 612 _h_t_t_p_:_/_/_w_w_w_._i_m_a_g_e_m_a_g_i_c_k_._o_r_g 613 614 615 For cases where ImageMagick's `convert' utility fails to properly con- 616 vert SVG-format images to EPS format, you can try the method of con- 617 verting the SVG image into an intermediate format (e.g. PNG) using the 618 `rsvg' utility. This utility may already be available on your Linux 619 distribution. If not, it can be found at this site: 620 621 _h_t_t_p_:_/_/_l_i_b_r_s_v_g_._s_o_u_r_c_e_f_o_r_g_e_._n_e_t_/ 622 623 From the PNG format, the image can often then be successfully converted 624 to EPS format, using the above-mentioned ImageMagick `convert' utility. 625 626 627 The _O_p_e_n _C_l_i_p _A_r_t _L_i_b_r_a_r_y is a good source of freely-usable images 628 (many of which are in SVG format) for decorating your events: 629 630 _h_t_t_p_:_/_/_w_w_w_._o_p_e_n_c_l_i_p_a_r_t_._o_r_g 631 632 633 NNoottee:: The EPS image content is not generated in the PostScript output 634 -- only a reference to the EPS image filename is generated. From a 635 practical standpoint, this means that normally you'll need to 636 print/preview the PostScript output of _p_c_a_l from the same computer/set- 637 up as that which was used to run _p_c_a_l in the first place. If you want 638 to generate a calendar with embedded EPS images that will later be 639 printed/viewed on another machine which does not have access to those 640 EPS images, you'll need to run the output through a pre-processor which 641 will put the EPS image content into the PostScript output file. For 642 example, assuming your initial calendar output was generated to a file 643 named `pcal.ps', on most GNU/Linux systems you could run this command, 644 which uses the popular `Ghostscript' interpreter: 645 646 gs -r300x300 -dBATCH -dNOPAUSE -sDEVICE=pswrite -sOutput- 647 File=out.ps pcal.ps 648 649 This would generate a PostScript file named `out.ps', at 300x300 dpi 650 resolution, which has the actual EPS image content embedded within, 651 allowing you to transport the `out.ps' file to another computer for 652 viewing/printing. Of course, the new file is substantially larger, but 653 it's portable. Furthermore, the EPS images will be viewable even in 654 PostScript-viewing applications (see above) which don't properly sup- 655 port the display of embedded (by filename only) EPS images. 656 657 658 659 PPrree--PPrroocceessssoorr FFuunnccttiioonnaalliittyy 660 _P_c_a_l supports rudimentary _c_p_p-like functionality in the date file, 661 allowing the following constructs: 662 663 664 � ddeeffiinnee || uunnddeeff 665 666 � iiff{{{{nn}}ddeeff}} ...... {{eelliiff ......}}** {{eellssee ......}} eennddiiff 667 668 � iinncclluuddee 669 670 Note that these are not preceded by `#' as they are in C. 671 672 Symbol names defined using these keywords (or via the --DD option) are 673 case-insensitive. It is not an error to uunnddeeff an undefined symbol, nor 674 to ddeeffiinnee a previously-defined one. 675 676 A symbol can be defined with just a name (e.g. ``define MY_SYM'') or it 677 can take on a value (e.g. ``define MY_SYM SOME_VALUE''). Use of symbol 678 values is convenient for defining a starting date then using that sym- 679 bol to reference that starting date in one or more events. For exam- 680 ple, these definitions in the date file might be useful: 681 682 define semester_start 8/23 # Beginning of semester 683 semester_start Class Start 684 7th day after semester_start 1st Quiz 685 14th day after semester_start 2nd Quiz 686 undef semester_start 687 688 Be aware that the substitution of symbol values for symbol names is not 689 robust, so it's wise to use a symbol name that's unlikely to occur in 690 any of your other event text. In other words, if you defined the `se- 691 mester_start' symbol in the example above as merely `start', then you'd 692 get the undesired effect of having the text `Class 8/23' in your calen- 693 dar on that day instead of `Class Start'! The use of `undef semes- 694 ter_start' in the above example is optional and is really only useful 695 to prevent any unwanted symbol substitutions later on, which probably 696 won't happen unless you poorly choose your symbol name to begin with. 697 698 An iiffddeeff alone is always ffaallssee; an iiffnnddeeff alone is always ttrruuee. iiff is 699 accepted as a synonym for iiffddeeff. 700 701 The name of the file in the iinncclluuddee directive may optionally be sur- 702 rounded by either "" or <>, both of which are ignored. If the name is 703 not an absolute path, it is taken to be relative to the directory where 704 the file containing the directive is located. If the string "%y" 705 appears in the file name, it is replaced by the last two digits of the 706 current year or, if "year all" is in effect, is expanded to all appli- 707 cable years. _P_c_a_l is smart enough to translate ~~// to the user's home 708 directory. 709 710 _P_c_a_l normally terminates immediately if the file specified in an 711 iinncclluuddee directive does not exist. An alternate form of the directive, 712 iinncclluuddee??, directs _p_c_a_l to continue silently if the file does not exist 713 or cannot be opened. 714 715 In addition to pre-processing keywords, _p_c_a_l also accepts boolean 716 expressions in iiff{{{{nn}}ddeeff}} and eelliiff directives. These expressions con- 717 sist of symbol names joined by the boolean operators !!, &&, ^^, and ||, in 718 order of precedence, high to low. Parentheses may be used to alter the 719 precedence. The synonyms &&&& and |||| are accepted for && and ||. A symbol 720 name evaluates to ttrruuee if currently defined, ffaallssee if not; thus: 721 722 ifdef A | B | C 723 724 ...is ttrruuee if any of the symbols A, B, and C is defined, and: 725 726 ifdef A & B & C 727 728 ...is ttrruuee if they all are. Note that iiffnnddeeff <<eexxpprr>> is equivalent to 729 iiffddeeff !!(( <<eexxpprr>> )).. 730 731 732 733 TThhee MMoooonn FFiillee 734 If a file of the name _._m_o_o_n_#_# (_m_o_o_n_#_#_._d_a_t under MS-DOS), where #### is 735 the last two digits of the calendar year, exists in the same directory 736 as the date file (or in the directory where _p_c_a_l resides), _p_c_a_l uses 737 the information contained within to calculate the phase of the moon. 738 If a) no such file exists, b) the --ee flag (do not use a date file) is 739 specified, or c) the --zz flag (specify time zone) is specified, then 740 _p_c_a_l uses an algorithm to calculate the phase of the moon. 741 742 Entries in the moon file must conform to the following syntax: 743 744 If the --AA option (American date formats, the default) is given: 745 746 <quarter> <month><sep><day> {<hour><sep><min>} 747 748 If the --EE option (European date formats) is given: 749 750 <quarter> <day><sep><month> {<hour><sep><min>} 751 752 Where: 753 754 <quarter> := ``nm'', ``fq'' or ``1q'', ``fm'', ``3q'' or ``lq'' (new moon, 755 first quarter, full moon, last quarter) 756 <hour> := number 0-23 (24-hour clock) 757 <min> := number 0-59 758 759 This file must contain entries for all quarter moons in the year, in 760 chronological order; if any errors are encountered, _p_c_a_l will revert to 761 using its default algorithm. 762 763 As in the date file, comments start with `#' and run through the end of 764 the given line. 765 766 The moon file may optionally contain an oopptt --AA or oopptt --EE line to spec- 767 ify the format of its own date entries independently of the format used 768 in the date file. No other flags are legal in the moon file. 769 770 771 772 773 GGeenneerraattiinngg PPoossttSSccrriipptt CCaalleennddaarrss VViiaa AA WWeebb BBrroowwsseerr IInntteerrffaaccee 774 PostScript-format _p_c_a_l calendars can be generated and viewed from a web 775 browser interface. 776 777 NNoottee:: This is not to be confused with the ability to generate 778 non-PostScript, HTML-format (using the --HH command-line option) 779 calendars, which is a different capability entirely. 780 781 _P_c_a_l comes with 4 files that provide this ability: `pcal.cgi' (a Bourne 782 shell script), `pcal.pl' (a Perl equivalent of `pcal.cgi'), 783 `pcal.html', and `pcalw.html'. 784 785 The CGI file (either `pcal.cgi' or `pcal.pl') must be edited before 786 using it. Change the definition for _`_p_c_a_l_=_' (Bourne shell script) or 787 _`_m_y _$_P_C_A_L _=_' (Perl script) to point to the location of the _p_c_a_l exe- 788 cutable file. Change the definition for _`_f_i_l_e_=_' (Bourne shell script) 789 or _`_m_y _$_F_I_L_E _=_' (Perl script) to point to the location of the _p_c_a_l 790 `date file' (e.g. `.calendar'), which contains the options for running 791 _p_c_a_l. Finally, copy the `pcal.cgi' (or `pcal.pl') file to the location 792 where your web server expects to find such files (e.g. `/var/www/cgi- 793 bin/'). 794 795 The `pcal.html' and `pcalw.html' files must also be edited. Each one 796 has a line like this: 797 798 <FORM ACTION="http://yourpath/cgi-bin/pcal.cgi" METHOD=GET> 799 800 That line must be edited to point to the host and location of your CGI 801 script file (`pcal.cgi' or `pcal.pl'). 802 803 Once that's done, point your web browser to the `pcal.html' or 804 `pcalw.html' file to generate monthly/yearly PostScript calendars for 805 viewing within your web browser. 806 807 NNoottee:: Depending upon what application your web browser spawns to 808 preview PostScript content, the monthly calendars generated via 809 this web browser interface may not show any embedded EPS images. 810 For a rundown of some popular PostScript-viewing applications 811 and whether they correctly display the embedded EPS images, see 812 the section (above) entitled `Encapsulated PostScript (EPS) 813 Images'. 814 815 816 817 818OOPPTTIIOONNSS 819 --ee Prints an empty calendar. Do not print entries from a _._c_a_l_e_n_d_a_r 820 file even if one exists. 821 822 --ff _c_a_l Directs _p_c_a_l to use the file name _c_a_l as the input file in place 823 of the default _._c_a_l_e_n_d_a_r file. Note that the search rules are 824 different when --ff is used. If _c_a_l is an absolute file name 825 (i.e. starting with a `/'), then _p_c_a_l attempts to open only that 826 file. Otherwise, _p_c_a_l looks for _c_a_l in the current directory, 827 then in the directory indicated by the environment variable 828 PPCCAALL__DDIIRR (if defined), and finally, if enabled (via the 829 `SEARCH_PCAL_DIR' flag) when _p_c_a_l was built, in the directory 830 where the _p_c_a_l executable resides. If the given _c_a_l file is not 831 found, an error results. 832 833 --oo _f_i_l_e 834 Directs _p_c_a_l to write the output to _f_i_l_e instead of to stdout. 835 836 --ll Causes the output to be in landscape mode (default). 837 838 839 840 _P_c_a_l predefines the symbol `ORIENTATION_LANDSCAPE' whenever 841 `landscape' page orientation is enabled. This can be useful for 842 providing alternate values in the configuration file for EPS 843 image placement and scaling, based on the page orientation. 844 845 846 --pp Causes the output to be in portrait mode. 847 848 849 850 _P_c_a_l predefines the symbol `ORIENTATION_PORTRAIT' whenever `por- 851 trait' page orientation is enabled. This can be useful for pro- 852 viding alternate values in the configuration file for EPS image 853 placement and scaling, based on the page orientation. 854 855 856 --PP Selects the paper size. The following sizes are supported: 857 858 859 � letter -- 8.5 x 11.0 inches 860 861 � legal -- 8.5 x 14.0 inches 862 863 � a4 -- 210 x 297 mm 864 865 � tabloid -- 11.0 x 17.0 inches 866 867 868 _P_c_a_l predefines one of the following symbols based on the cur- 869 rent paper size: 870 871 872 � PAPERSIZE_LETTER 873 874 � PAPERSIZE_LEGAL 875 876 � PAPERSIZE_A4 877 878 � PAPERSIZE_TABLOID 879 880 These symbol definitions can be useful for providing alternate 881 values in the configuration file for EPS image placement and 882 scaling, based on paper size. 883 884 885 886 --jj Causes the Julian date (day of year) to be printed in each cal- 887 endar box. 888 889 --JJ Causes the Julian date and the number of days remaining in the 890 year to be printed in each calendar box. 891 892 --mm Causes moon icons to be printed on dates corresponding to new, 893 half, and full moons (the default is that no moons are printed). 894 895 --MM Causes moon icons to be printed on all dates (the default is 896 that no moons are printed). 897 898 --gg _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy 899 Causes all dates falling on weekday _d_a_y_1 (through _d_a_y_2 if speci- 900 fied) to be printed in the `day numerics color' (i.e. the color 901 specified by the --ss option [default = gray]); --gg aallll causes all 902 weekdays (other than holidays) to be printed in the `day numer- 903 ics color'; --gg hhoolliiddaayy causes all holidays to be printed in `day 904 numerics color'. _d_a_y_1 and _d_a_y_2 may wrap around weekends; for 905 example, --gg ffrrii--ssuunn causes Fridays, Saturdays, and Sundays to be 906 printed in the `day numerics color'. 907 908 --OO _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy 909 Similar to --gg, but the selected days will be printed as outlined 910 characters, using the `day numerics color'. 911 912 --GG _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy 913 Similar to --gg, but the selected days will be printed in the `day 914 numerics color', outlined in black. 915 916 --bb _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy 917 Similar to -- you guessed it -- --gg, but the selected days will 918 be printed in black. Since black is the default for weekdays, 919 -b is primarily used to overriding other flags (e.g., --gg aallll --bb 920 ssaatt--ssuunn ). 921 922 NNoottee:: 923 The default for the above options is to print Saturdays, Sun- 924 days, and holidays in the `day numerics color' and all other 925 days in black. For backward compatibility with earlier versions 926 of _p_c_a_l, --OO and --GG alone change all non-black days to the speci- 927 fied color. 928 929 --ss _[_d_a_y___n_u_m_e_r_i_c_s___c_o_l_o_r_]_[_/_e_m_p_t_y___d_a_y___b_o_x___f_i_l_l___c_o_l_o_r_] 930 Overrides the default value(s) for the color of the numerics for 931 each day and/or the color of the fill used on boxes for 'empty' 932 days. NNoottee:: This option only applies to PostScript-format cal- 933 endars, not to HTML-format calendars. These values may be set 934 independently of each other. For use with non-color printers, 935 these values should be in the range 0.0 (black) through 1.0 936 (white). The default values are 0.8 for day numerics and 0.9 937 for empty day boxes. For use with color printers, these values 938 may optionally be specified as a set of _r_e_d:_g_r_e_e_n:_b_l_u_e (RGB) 939 values, each of which must in the range 0.0 through 1.0. At 940 least one `:' must be present for these values to be recognized 941 as RGB colors; omitted values are set to 0.0. 942 943 This option may also be set semi-permanently by altering the 944 makefile (`Makefile' for most environments, 'Makefile.DOS' for 945 MS-DOS). 946 947 --FF _d_a_y Selects weekday _d_a_y as the first day of the week. The given day 948 will appear in the left-most column of the calendar. _d_a_y may be 949 specified either as a weekday name or, optionally, as a number 950 in the range 0 (Sunday) through 6 (Saturday). 951 952 This option may also be set semi-permanently by altering the 953 makefile (`Makefile' for most environments, 'Makefile.DOS' for 954 MS-DOS). 955 956 --AA Directs _p_c_a_l to use American date conventions ( mmmm//dddd{{//yyyy}} and 957 mmoonntthh dddd ) when parsing the date file. This is the default. 958 959 This option may also be set semi-permanently by altering the 960 makefile (`Makefile' for most environments, 'Makefile.DOS' for 961 MS-DOS). 962 963 --EE Directs _p_c_a_l to use European date conventions ( dddd//mmmm{{//yyyy}} and 964 dddd mmoonntthh ) when parsing the date file. 965 966 This option may also be set semi-permanently by altering the 967 makefile (`Makefile' for most environments, 'Makefile.DOS' for 968 MS-DOS). 969 970 --XX _x_t_r_a_n_s 971 Specifies the x-axis translation value for positioning the out- 972 put on the page. Positive values shift the output to the right. 973 Negative values shift the output to the left. 974 975 --YY _y_t_r_a_n_s 976 Specifies the y-axis translation value for positioning the out- 977 put on the page. Positive values shift the output up. Negative 978 values shift the output down. 979 980 --xx _x_s_c_a_l_e 981 Specifies the x-axis scaling factor for the calendar size. 982 983 --yy _y_s_c_a_l_e 984 Specifies the y-axis scaling factor for the calendar size. 985 986 --tt [_t_i_t_l_e___f_o_n_t][//_s_i_z_e] 987 Specifies the name of a font to use for all the calendar heading 988 text: 989 990 991 � the month name and year at the top of the calendar (for 992 monthly-format calendars) or at the top of each month 993 (for yearly-format calendars and for the small previ- 994 ous/next-month calendars [if enabled] on monthly-format 995 calendars) 996 997 � the day-of-week names 998 999 � the footer strings (if any) 1000 1001 � the ``Notes'' box heading (if any; for monthly calen- 1002 dars only) 1003 1004 1005 For monthly calendars only, the user may optionally specify the 1006 font size, which applies only to the main month/year heading. 1007 For example, ppccaall --tt TTiimmeess--RRoommaann//5544 sets the font to Times-Roman 1008 and the month/year point size to 54. The font size may also be 1009 changed independently: ppccaall --tt //5544 changes the point size to 54 1010 without affecting the font name. 1011 1012 Note: For yearly calendars, any specification of font _s_i_z_e is 1013 ignored. 1014 1015 This option may also be set semi-permanently by altering the 1016 makefile (`Makefile' for most environments, 'Makefile.DOS' for 1017 MS-DOS). 1018 1019 --dd [_d_a_t_e___f_o_n_t][//_s_i_z_e] 1020 Similar to the --tt option, but selects the font and/or size used 1021 for the day numerics (the numbers inside the box for each day). 1022 1023 Note: For yearly calendars, any specification of font _s_i_z_e is 1024 ignored. 1025 1026 This option may also be set semi-permanently by altering the 1027 makefile (`Makefile' for most environments, 'Makefile.DOS' for 1028 MS-DOS). 1029 1030 --nn [_t_e_x_t___f_o_n_t][//_s_i_z_e] 1031 Similar to the --tt and --dd options, but selects the font and/or 1032 size used for any `event' text associated with each day and for 1033 any text in the monthly ``Notes'' box. 1034 1035 Note: This option applies to monthly calendars only. For yearly 1036 calendars, this option does not apply. 1037 1038 This option may also be set semi-permanently by altering the 1039 makefile (`Makefile' for most environments, 'Makefile.DOS' for 1040 MS-DOS). 1041 1042 --LL _s_t_r_i_n_g 1043 Causes the accompanying string to be printed as a left-justified 1044 footer. Format specifiers denoting the month and/or year may 1045 appear in the string; the appropriate values will be substituted 1046 upon printing. 1047 1048 --CC _s_t_r_i_n_g 1049 Similar to --LL, but causes the accompanying string to be printed 1050 as a centered footer. If the --HH flag (generate calendar as HTML 1051 table) was specified, this string will be used as the title and 1052 heading. 1053 1054 --RR _s_t_r_i_n_g 1055 Similar to --LL, but causes the accompanying string to be printed 1056 as a right-justified footer. 1057 1058 --NN _s_t_r_i_n_g 1059 Causes the accompanying string to be printed as the heading for 1060 the "Notes" box. Note, however, that _p_c_a_l makes no attempt to 1061 ensure that it fits. 1062 1063 --DD _s_y_m_b_o_l _[_v_a_l_u_e_] 1064 Defines the named symbol and an optional value to be associated 1065 with that symbol, prior to reading the date file. 1066 1067 --UU _s_y_m_b_o_l 1068 Un-defines the named symbol prior to reading the date file. 1069 1070 --BB Causes _p_c_a_l to leave unused calendar day boxes blank as opposed 1071 to the default behavior of filling them using the `empty day-box 1072 fill color' (i.e. the color specified by the --ss option [default 1073 = gray]). 1074 1075 --## _n Causes _p_c_a_l to print _n copies (maximum: 100) of each output 1076 page. 1077 1078 --SS Causes _p_c_a_l to suppress printing the small calendars. See the 1079 CCAAVVEEAATTSS section for further details. 1080 1081 --kk Causes _p_c_a_l to print the small calendars in the upper left cor- 1082 ner (the default is to print them at the lower right). 1083 1084 --KK Causes _p_c_a_l to print the small calendar for the previous month 1085 in the upper left corner and the next month in the lower right 1086 (the default is to print both at the lower right). 1087 1088 --ww Causes _p_c_a_l to print a calendar for 12 consecutive months: 3 1089 rows / 4 columns in landscape mode, 4 rows / 3 columns in por- 1090 trait mode. See the CCAAVVEEAATTSS section for details on the use of 1091 this option with other options. 1092 1093 Pcal predefines the symbol wwhhoollee__yyeeaarr when the --ww flag is in 1094 effect, allowing directives like `iiffddeeff wwhhoollee__yyeeaarr' in the con- 1095 figuration file. 1096 1097 --II Resets all parameters to the program defaults. 1098 1099 --cc Causes _p_c_a_l to generate a date file suitable for use as input to 1100 the Un*x _c_a_l_e_n_d_a_r_(_1_) utility. The normal PostScript output is 1101 suppressed. 1102 1103 --HH Causes _p_c_a_l to generate a calendar in HTML table format. The 1104 normal PostScript output is suppressed. 1105 1106 The HTML table format does not support moon graphics, Julian 1107 date information, `day numerics' color, `empty day' `box fill' 1108 color, left or right footer strings (but see the --CC flag), 1109 alternate fonts/sizes, transformation and scaling factors, or 1110 embedded EPS images. 1111 1112 --qq This option is only valid when used in conjunction with the --HH 1113 (generate HTML-format calendar) option. It generates a yearly- 1114 planner style of HTML calendar whereby a single column for each 1115 month is used, resulting in table that gives a quicker overview 1116 of several months. Since there is less space for text, only the 1117 first character of the weekday and the first 5 characters of 1118 text from each event for that day are printed. The day numerics 1119 for holidays are colored red but the text of the holiday event 1120 is not printed. The day numerics are grey for Saturdays and 1121 bold black for Sundays. 1122 1123 --zz _t_i_m_e___z_o_n_e 1124 Forces _p_c_a_l to ignore the moon file and to use its internal 1125 algorithm for moon phase calculations, adjusting the phase by 1126 _t_i_m_e___z_o_n_e hours (where _t_i_m_e___z_o_n_e is expressed in hours west of 1127 UTC). 1128 1129 For example, New York residents (USA Eastern time zone) would 1130 use '-z 5' while on Eastern Standard Time (winter) and '-z 4' 1131 while on Eastern Daylight Time (summer). People in India would 1132 use '-z-5.5'. Notice that fractional values are allowed. 1133 1134 This option may also be set semi-permanently by altering the 1135 makefile (`Makefile' for most environments, 'Makefile.DOS' for 1136 MS-DOS). 1137 1138 --hh Causes _p_c_a_l to write version information, parameter usage mes- 1139 sage, and full explanation of options and file formats (to _s_t_d_- 1140 _o_u_t) and terminate. 1141 1142 --uu Causes _p_c_a_l to write version information and parameter usage 1143 message (to _s_t_d_o_u_t) and terminate. 1144 1145 --vv Causes _p_c_a_l to write version information only (to _s_t_d_o_u_t) and 1146 terminate. 1147 1148 Pcal predefines the symbol vvXX__YY__ZZ, where XX__YY__ZZ denotes the cur- 1149 rent version of Pcal (e.g. version 4.9.0 predefines the symbol 1150 vv44__99__00). 1151 1152 --aa _o_u_t_p_u_t___l_a_n_g_u_a_g_e 1153 Select the output language (for the names of months and days on 1154 the calendar). 1155 1156 Currently, the following languages are supported: ccaa (Catalan), 1157 ccss (Czech), ddaa (Danish), ddee (German), eell (Greek), eenn (English), 1158 eeoo (Esperanto), eess (Spanish), eett (Estonian), ffii (Finnish), ffrr 1159 (French), hhaa (Hawaiian), hhuu (Hungarian), iitt (Italian), lltt 1160 (Lithuanian), llvv (Latvian), nnll (Dutch), ppll (Polish), pptt (Por- 1161 tuguese), rroo (Romanian), rruu (Russian), sskk (Slovak), ssvv 1162 (Swedish), and uukk (Ukrainian). The default is eenn. 1163 1164 Note that this option does nnoott specify the `input language', 1165 which is the language used to process events in the configura- 1166 tion file ('English', by default, unless changed with the _i_n_p_u_t_- 1167 _l_a_n_g_u_a_g_e _X_X directive). See the section _T_h_e _D_a_t_e _F_i_l_e for more 1168 details on specifying the `input language'. 1169 1170 NNoottee:: In order to display diacritical marks, languages other 1171 than English require that the characters be remapped. Normally, 1172 no action is required since _p_c_a_l automatically selects a remap- 1173 ping which is appropriate to the selected language. However, if 1174 you want to override the default remapping for a given language, 1175 you would use the --rr option (e.g. "-r Latin1"). 1176 1177 Furthermore, an appropriate font should be selected as needed 1178 using the --tt option (e.g. "-t some-latin1-font-name"). Any lan- 1179 guage using the "Latin1" remapping (e.g. French, German, Ital- 1180 ian, Spanish, etc) requires an ISO 8859-1 ('Latin1') font. The 1181 Greek language requires an ISO 8859-7 (similar to ELOT-928) font 1182 (available from Angelo Haritsis <ah@doc.ic.ac.uk>; also see 1183 http://www.hellenic.net/fonts/). Similarly, Russian requires a 1184 KOI8-R font while Ukrainian requires a KOI8-U font. 1185 1186 _P_c_a_l predefines the symbol llaanngg__XXXX, where XXXX is the two-charac- 1187 ter abbreviation for the selected output language. 1188 1189 --rr [_m_a_p_p_i_n_g] 1190 Specifies an 8-bit character set remapping (encoding) for print- 1191 ing the diacritical marks common to European languages. 1192 1193 Note: This option is not usually needed since _p_c_a_l will automat- 1194 ically select an appropriate default character encoding (map- 1195 ping) for the language for which the calendar is being gener- 1196 ated. 1197 1198 The value specified for _m_a_p_p_i_n_g is case-insensitive and may be 1199 abbreviated to the point where it is still unique. The value 1200 used may be any of the following: 1201 1202 1203 � "none" (use built-in character set) 1204 1205 � "Latin1" (ISO 8859-1) 1206 1207 � "Latin2" (ISO 8859-2) 1208 1209 � "Latin3" (ISO 8859-3) 1210 1211 � "Latin4" (ISO 8859-4) 1212 1213 � "Cyrillic" (ISO 8859-5) 1214 1215 � "Greek" (ISO 8859-7) 1216 1217 � "Latin5" (ISO 8859-9) 1218 1219 � "Latin6" (ISO 8859-10) 1220 1221 � "Thai" (ISO 8859-11) 1222 1223 � "Latin7" (ISO 8859-13) 1224 1225 � "Latin8" (ISO 8859-14) 1226 1227 � "Latin9" (ISO 8859-15) 1228 1229 � "KOI8-R" (Russian) 1230 1231 � "KOI8-U" (Ukrainian) 1232 1233 � "Roman8" 1234 1235 1236 1237 This option may also be set semi-permanently by altering the 1238 makefile (`Makefile' for most environments, 'Makefile.DOS' for 1239 MS-DOS). 1240 1241 1242 --TT [B|I|R] 1243 Select the default typeface (Bold, Italic, or Roman) for print- 1244 ing date/note text. This flag may be specified multiple times 1245 within the date file (via "opt") to reset the font style on the 1246 fly -- for example, to print all holidays in Bold. 1247 1248 1249 --WW [left|center|right] 1250 Specify the horizontal alignment of the month/year heading 1251 (left, center, right) (for monthly-format calendars only). 1252 1253 1254 Any option taking a negative value (e.g. --YY --######) should be specified 1255 with no space between the option and the (negative) value to avoid _p_c_a_l 1256 interpreting the value as an illegal flag and aborting. For example, 1257 use ` _-_Y_-_5_0' instead of ` _-_Y _-_5_0' on your option specification. 1258 1259 Any option (except --GG and --OO, for backward-compatibility) which nor- 1260 mally takes an argument may be specified without the argument in order 1261 to reset the value to the program default. Note that while the --DD 1262 option alone clears all the defined symbols, the --UU option alone has no 1263 effect. The -- (or ---- as per System V) argument may be used to disam- 1264 biguate command lines such as: 1265 1266 ppccaall --tt 99 9900 1267 1268 This could be written instead as one of the following: 1269 1270 ppccaall --tt -- 99 9900 1271 ppccaall --tt ---- 99 9900 1272 1273 If the environment variable PPCCAALL__OOPPTTSS is defined, its contents are 1274 parsed as a command line. Flags set via PPCCAALL__OOPPTTSS override the program 1275 defaults, but are overridden by options set via oopptt lines in the con- 1276 figuration file or explicitly on the command line. 1277 1278 1279 1280 AAddddiittiioonnaall OOppttiioonnss FFoorr DDeebbuuggggiinngg OOnnllyy 1281 The --ZZ flag is used to print debugging information which is of interest 1282 primarily to _p_c_a_l hackers. This flag is a "hidden" flag; it does not 1283 appear as part of the usage message. At present, the following options 1284 are supported: 1285 1286 1287 � -ZD print dates and text as read from date file 1288 1289 � -ZF print date file search paths 1290 1291 � -ZM print moon phases and identify quarters 1292 1293 � -ZO print option flags and where set 1294 1295 � -ZP print "preprocessor" debug info 1296 1297 � -ZT print dates and text as written to output file 1298 1299 � -Z turn off all debugging info 1300 1301 The subflags may be combined: e.g. "-ZDF" is equivalent to "-ZD -ZF". 1302 All of the aforementioned debugging information is written to stderr. 1303 1304 1305 1306CCAAVVEEAATTSS 1307 � The ``workday'' and ``holiday'' keywords are aware of only those hol- 1308 idays which have already been flagged at the point where they appear. 1309 For example, consider January 1990: 1310 1311 January 1990 1312 S M Tu W Th F S 1313 1 2 3 4 5 6 1314 7 8 9 10 11 12 13 1315 14 15 16 17 18 19 20 1316 21 22 23 24 25 26 27 1317 28 29 30 31 1318 1319 If the configuration file looked like this: 1320 1321 workday on_or_before all 15 payday 1322 3rd Mon in Jan* MLK day 1323 1324 ... then _p_c_a_l would mark the 15th as ``payday'' since at that point 1325 in the configuration file it has no way of knowing that January 15th 1326 will later be flagged as a holiday. If the two lines were reversed, 1327 such that the holiday preceded the ``workday'' wildcard, then _p_c_a_l 1328 would work as intended, marking instead the 12th as ``payday''. 1329 1330 Also, beware of year boundaries which affect the handling of all of 1331 the day wildcard keywords. In general, it is best to place monthly 1332 wildcards such as the example above at the end of each year to 1333 achieve the desired effect. 1334 1335 1336 � Only the positive ordinals may be used in conjunction with preposi- 1337 tions (e.g. "fourth Sunday before 12/25"). (It could be argued that 1338 "last Sunday before 12/25" should be accepted as a synonym for "first 1339 Sunday before 12/25", but then what does "last Sunday after 12/25" 1340 mean?) 1341 1342 1343 � When the --ww and --pp options are used together, _p_c_a_l revises the y- 1344 scale factor in order to use the entire portrait page; therefore, the 1345 user should avoid using use the --yy option when using both the --ww and 1346 --pp options. Use of the --ww option in any case effectively disables 1347 the --mm, --MM, --jj, and --JJ options. 1348 1349 1350 � The output of the --cc option may be used as input to subsequent runs 1351 of _p_c_a_l. Note, however, that oopptt lines (except for an automatic oopptt 1352 --[[AA||EE]]), comments, ``note'' text, and iiffddeeff'd-out source will be 1353 lost. 1354 1355 1356 � The --SS option interacts with nnoottee{{//<<nnuummbbeerr>>}}; if used, it should be 1357 specified either on the command line or prior to the first nnoottee line 1358 in the date file. 1359 1360 1361 1362 1363SSEEEE AALLSSOO 1364 Website for _p_c_a_l and _l_c_a_l (a lunar calendar generation application): 1365 1366 1367 http://pcal.sourceforge.net 1368 1369 cal(1), calendar(1). 1370 1371 The old, simple Unix/BSD 'calendar' program, which can be used with 1372 _p_c_a_l and the '-c' option is part of the BSD Main Utilities ('bsdmainu- 1373 tils') package and is available at the Debian site: 1374 1375 _h_t_t_p_:_/_/_p_a_c_k_a_g_e_s_._d_e_b_i_a_n_._o_r_g_/_s_t_a_b_l_e_/_s_o_u_r_c_e_/_b_s_d_m_a_i_n_u_t_i_l_s 1376 1377 This old program does not seem to be included with most GNU/Linux dis- 1378 tributions these days. 1379 1380 For more information on PostScript, consult the free, online Adobe book 1381 entitled _P_o_s_t_S_c_r_i_p_t _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, which can be found here 1382 (as of Dec 2007): 1383 1384 _h_t_t_p_:_/_/_p_a_r_t_n_e_r_s_._a_d_o_b_e_._c_o_m_/_p_u_b_l_i_c_/_d_e_v_e_l_o_p_e_r_/_p_s_/_i_n_d_e_x___s_p_e_c_s_._h_t_m_l 1385 1386 1387 1388AAUUTTHHOORRSS 1389 The original PostScript code to generate the calendars was written by 1390 Patrick Wood (Copyright � 1987 by Patrick Wood of Pipeline Associates, 1391 Inc.), and authorized for modification and redistribution. The calen- 1392 dar file inclusion code was originally written in "bs(1)" by Bill Vogel 1393 of AT&T. Patrick's original PostScript was modified and enhanced sev- 1394 eral times by King Ables, Tim Tessin, Joe Wood, Jeff Mogul, Mark Han- 1395 son, and others whose names have regrettably been lost. This C version 1396 was originally created by Ken Keirnan of Pacific Bell; additional 1397 enhancements by Joseph P. Larson, Ed Hand, Andrew Rogers, Mark 1398 Kantrowitz, Joe Brownlee, Andy Fyfe, Steve Grandi, Geoff Kuenning, Ste- 1399 fan Fronzek (1-column HTML output), Bill Bogstad (event deletion capa- 1400 bility), and Bill Marr (embedded EPS images, command-line paper size 1401 specification, new paper sizes [legal & tabloid], additional character 1402 mappings for new languages, and various cleanups). The moon routines 1403 were originally written by Jef Poskanzer and Craig Leres, and were 1404 incorporated into _p_c_a_l by Richard Dyson. International language sup- 1405 port was initially added by Angelo Haritsis. Additional languages were 1406 added by Andrew Rogers (Esperanto), Lars Wirzenius (Finnish), Pedro 1407 Zorzenon Neto (Portuguese), Joel Fredrikson (Swedish), Volodymyr M. 1408 Lisivka (Ukrainian), Neeme Praks (Estonian, Russian, Latvian, Lithua- 1409 nian), Peter Cernoch (Czech), Ferenc Kruzslicz (Hungarian), Carles 1410 Sadurn� Anguita (Catalan), Dominik 'Chiron' Derlatka (Polish), Ewald 1411 Beekman (Dutch), Claudiu Costin (Romanian), Kenneth Geisshirt (Danish), 1412 Zdenko Podobny (Slovak), and Eric Nichols (Hawaiian). 1413 1414 1415 1416Version 4.11.0 18 Dec 2007 PCAL(1) 1417