PCAL(1) USER COMMANDS PCAL(1)
NNAAMMEE
pcal - generate PostScript (or HTML) calendars
SSYYNNOOPPSSIISS
ppccaall [--ee|--ff _c_a_l] [--oo _f_i_l_e] [--ll | --pp] [--PP [letter | legal | a4 |
tabloid]] [--jj | --JJ] [--mm | --MM] [--gg _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday]
[--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-
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_-
_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]
[--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]
[--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]]
[--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]
[--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]
[--SS | --kk | --KK] [--ww] [--II] [--cc | --HH] [--qq] [--zz _t_i_m_e___z_o_n_e]
[--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]]
[--WW [left|center|right]] [month] [year] [nmonths]
DDEESSCCRRIIPPTTIIOONN
_P_c_a_l generates PostScript to produce landscape or portrait calendars
for any month and year. The arguments mmoonntthh, yyeeaarr, and nnmmoonntthhss, if
provided, should be numeric. The mmoonntthh value should be in the range 1
- 12, and the yyeeaarr value should be specified as 1 or 2 digits (in which
case it will be interpreted as that year in the current century) or as
the full 4-digit year. If no numeric arguments are provided, the cal-
endar for the current month and year will be generated.
If one numeric argument is provided, it is interpreted as the yyeeaarr
value, and calendars for the entire year will be generated. Otherwise,
nnmmoonntthhss months, starting with mmoonntthh and yyeeaarr, will be generated.
For whole-year calendars (i.e. when the --ww option is given), the com-
mand line arguments are interpreted somewhat differently. By default,
all months in the current year are printed, starting with January. If
the mmoonntthh argument alone is given, it is expected to be the desired
yyeeaarr to print, and prints all of the months in the given year. If both
mmoonntthh and yyeeaarr are given, then 12 consecutive months are printed start-
ing at the given month and year. If the mmoonntthh, yyeeaarr, and nnmmoonntthhss argu-
ments are all present, printing begins with the given month and year
and nnmmoonntthhss months are printed, rounded up to the nearest multiple of
12.
TThhee DDaattee FFiillee ((CCoonnffiigguurraattiioonn FFiillee))
By default, _p_c_a_l simply prints an empty calendar. Its real power is in
its ability to place ``events'' (and, for monthly-format PostScript
calendars, Encapsulated PostScript images [e.g. photos and icons]) in
appropriate days on the (PostScript or HTML) calendar, thus allowing
the user to create personalized calendars. This is achieved through
the use of the ``date file'', also known as the ``configuration file''.
The default date/configuration file is expected to be named _._c_a_l_e_n_d_a_r
(_p_c_a_l_._d_a_t under MS-DOS), or _c_a_l_e_n_d_a_r for compatibility with older ver-
sions. _P_c_a_l will look in several places for such a file. First, if
the environment variable PPCCAALL__DDIIRR is defined, _p_c_a_l searches the direc-
tory indicated by that variable. Next, _p_c_a_l searches the user's home
directory (as specified by the HHOOMMEE environment variable). If neither
PPCCAALL__DDIIRR nor HHOOMMEE is defined, _p_c_a_l searches the current directory
instead. Finally, if enabled (via the `SEARCH_PCAL_DIR' flag) when
_p_c_a_l was built, the directory where the _p_c_a_l executable resides will be
checked. If no date file is found, an empty calendar is printed; no
error is generated.
Alternatively, the name of the date file (and, optionally, the path
where it can be found) can be specified using the --ff command-line
option. See the OOPPTTIIOONNSS section for more details.
Every _p_c_a_l distribution comes with an 'examples' directory. The `pcal-
cfg.txt' file that is located there contains a myriad of examples of
settings that can be used in your own configuration file. Please check
it out for lots of useful ideas. Furthermore, that directory contains
several language/country-specific examples (including holiday and other
event definitions) in various `calendar_xx.txt' files, where `xx' rep-
resents the 2-letter language code (e.g. 'calendar_de.txt' is the Ger-
man example file).
If a date file is found, it will be searched for lines with leading
dates matching the requested month and year.
Any text following the dates found will be printed on the calendar
under the appropriate day of the month. Encapsulated PostScript (EPS)
images are handled similarly as described in a later subsection.
ttrrooffff-style escape sequences \fB, \fI, \fP, and \fR may be used to set
the font style to Bold, Italic, the previous font style, or Roman
respectively. For those more familiar with HTML, , , , and
may be used instead to enable/disable Bold or Italic font styles.
The font style is reset to Roman after each line break.
Using the `include' pre-processor directive (described in the section
entitled `Pre-Processor Functionality', below), other configuration
files can be processed from within an existing configuration file.
That is, you can `nest' configuration files as needed.
Dates (essentially `events') in the configuration files may be
expressed in any of several formats:
+o in {*} {}
+o {} {*} {}
+o {*} {}
+o {*} {}
Where:
:= first 3+ characters of name of month, or
``all''
NNoottee:: _p_c_a_l looks for names of the days of the
week prior to names of months when parsing event
date specifications. Furthermore, some languages
(e.g. French and Finnish) have a month name whose
first 3 letters are the same as the first 3 let-
ters of one of the names of the days of the week.
Because of this, the specification in such a lan-
guage of any month name which collides thusly
must use 4 or more letters to distinguish it from
the name of the day of the week with which it
`collides'.
:= , or ``year''
:= first 3+ characters of name of weekday,
``day'', ``weekday'', ``workday'', ``holiday'',
``nonweekday'', ``nonworkday'', ``nonholiday'',
``new_moon'', ``first_quarter'', ``full_moon'',
or ``last_quarter''
:= any ordinal number (``1st'', ``2nd'', etc.),
``first'' ... ``fifth'', ``last'', ``odd'',
``even'', or ``all''
:= ``on'', ``before'', ``preceding'', ``after'',
``following'', ``on_or_before'' (``oob''),
``on_or_after'' (``ooa''), ``nearest'', ``near-
est_before``, or ``nearest_after``
:= ``Christmas'', ``Thanksgiving'', ``Easter'',
``Good_Friday'', ``GEaster'' (Orthodox Easter),
``Gstgeorge'' (Orthodox holiday), and ``Gmarcus''
(Orthodox holiday).
:= one or more non-numeric, non-space, non-`*'
characters
:= a numeric month (1-12)
:= day of month (1-31)
:= a numeric year
:= the text to be displayed for this event; if
the text begins with the constant string
``image:'', then it is interpreted as a specifi-
cation of an Encapsulated PostScript (EPS) image
rather than as simple text; more information on
specifying EPS images is available in a later
section of this document
If the --AA option (American date formats, the default) is given:
:= |
{}
If the --EE option (European date formats) is given:
:= | |
{}
The ``Notes'' box (see below) uses the first of the current month as
the default date. All footer strings use the first of the current
month in single-month mode and the first of the starting month in
whole-year mode.
Examples:
last Monday in May* Memorial Day Holiday
all Fridays in Oct Status Meeting, 11 AM
first workday in all %-B progress report due
all Fri in all \fBTime card due,\fP 3 PM
all Monday in all Fiscal week %0W
-2nd workday in all Schedule for %+B due %+2D
2nd full_moon in all Blue Moon
Fri on_or_before all 15 Pay Day
even Fridays in year Pay Day
183rd day of year Mid-year (%l days left)
Tue after first Mon in Nov Election Day (USA)
4th Thu in Nov* Thanksgiving
Fri after 4th Thu in Nov* Day after Thanksgiving
workday nearest 12/25* Holiday
12/25/04* Christmas # American
25.12.04* Christmas # European
25. 12.* Christmas # European
Dec 25* Christmas # American
25 Dec* Christmas # European
25. Dec* Christmas # European
Fri on all 13 Avoid black cats! # 'Friday the 13th'
Any non-numeric character may separate numeric dates. Holidays may be
flagged by following the date immediately with `*' as in the examples
above; this will cause the date numerics to be printed in the color
specified by the --ss option (default = gray) and will cause the associ-
ated text (on monthly-format calendars) to be placed adjacent to the
numeric date in the day box rather than below the numeric date (as is
done for all non-holiday events). ``Each'' and ``every'' are accepted
as synonyms for ``all'', and any word may be used in place of ``in''.
The abbreviations ``oob'' and ``ooa'' may be used in place of the key-
words ``on_or_before'' and ``on_or_after'', respectively. ``Nearest''
attempts to match the specified date; if that fails, it tries the day
after, then the day before, then two days after, two days before, and
so forth until a match occurs.
Wildcard day names are also provided. The keyword ``weekday'' applies
to any days which are normally printed in "logical black" - the predom-
inant day color - on the calendar. The keyword ``workday'' is the
same, but does not include any holidays. The keyword ``holiday''
includes only those days flagged as holidays. The keywords ``nonweek-
day'', ``nonworkday'', and ``nonholiday'' are also recognized as nega-
tions of the above. See the CCAAVVEEAATTSS below for important notes on using
these keywords. Moon phases may also appear as wildcards; ``nm'' is
accepted as a synonym for ``new_moon'', ``1q'' and ``fq'' for
``first_quarter'', ``fm'' for ``full_moon'', ``3q'' for ``third_quar-
ter'', and ``lq'' for ``last_quarter''.
Ordinal day numbers may be used to specify dates, either relative to
the month or to the year. Either words or numeric abbreviations may be
used for ``first'' through ``fifth''; higher numbers must be given
using the numeric equivalent (e.g. 100th). Negative ordinal numbers
may even be used. For example, ``-2nd'' means ``next to last''.
``Odd'' and ``even'' do not refer to the actual date; instead, ``odd''
means ``alternate, starting with the first'', and ``even'' means
``alternate, starting with the second''. Thus, ``odd Fridays in
March'' refers to the first, third, and (if present) fifth Fridays in
March -- not to those Fridays falling on odd dates.
``All'' refers to each individual month; ``year'' refers to the year as
an entity. Thus ``odd Fridays in all'' refers to the first, third, and
fifth Friday of each month, while ``odd Fridays in year'' refers to the
first Friday of January and every other Friday thereafter.
``Nearest'', ``nearest_before'', and ``nearest_after'' refer to the
nearest weekday or wildcard day with respect to the specified date.
``Nearest_before'' and ``nearest_after'' allow the user to specify how
_p_c_a_l is to disambiguate between two dates that are equally near: e.g.,
``nonweekday nearest_before [Wed.] 9/25/96'' refers to Sunday, 9/22
while ``nonweekday nearest_after 9/25/96'' refers to Saturday, 9/28.
(Note that ``nearest_before'' and ``nearest_after'' are equivalent to
``nearest'' when no such ambiguity exists: e.g., ``nonweekday near-
est_before [Thu.] 9/26/96'' refers to Saturday, 9/28.)
Text in the date file may use C-like escape sequences (i.e. a `\' fol-
lowed by a character, 1 - 3 octal digits, or `x' followed by 1 - 2
hexadecimal digits). Escaped whitespace (including nneewwlliinnee ) and the
standard ANSI character escapes (`\a', `\b', `\f', `\n', `\r', `\t',
`\v') are all replaced by a single blank.
The HTML special characters `<' `>' `"' `&' ` ' and
`NNN;' (NNN = any three decimal digits) are also supported. These
will be propagated intact (be sure to escape the `#' in `NNN;') if
the output is specified as HTML (see the --HH flag); otherwise they will
be converted to their ASCII equivalents. This allows a common date
file to be used regardless of whether the desired output format is
HTML, PostScript, or Un*x _c_a_l_e_n_d_a_r_(_1_) (see the --cc flag) input.
Lines in the configuration file consisting of yyeeaarr ######## (where ######## is
a numeric year) can be used to set the year for following entries.
This assumes that the following entries do not contain a year; any date
entries containing year information will set the remembered year to
that year.
Lines in the configuration file consisting of yyeeaarr aallll (or, alterna-
tively, yyeeaarr **) direct _p_c_a_l to wildcard following entries against every
applicable year. This assumes that the following entries do not con-
tain a year; any date entries containing year information (or an
explicit yyeeaarr ######## entry) will set the remembered year to that year.
Lines in the configuration file consisting of oopptt <> can be used
to override the defaults for any command-line options except --cc, --ee,
--ff, --hh, --HH, --uu, --vv, --DD, and --UU. Any options specified in this manner
are, in turn, overridden by those specified explicitly on the command
line.
Lines in the configuration file consisting of nnoottee{{//<>}} <>
can be used to place notes regarding the entire month in one of the
unused blocks of the calendar. The <> indicator may be either a
number 1 through 12 or an alphabetic month name as described above;
``note all'' will place the associated text in the notes block for each
month in the current year. <> is an optional positive or nega-
tive number specifying the empty box where the associated text is to be
placed. If positive, _p_c_a_l counts forward from the first empty box; if
negative, _p_c_a_l counts backward from the last empty box. Thus,
````nnoottee//11'''' places the associated text in the first empty box; nnoottee//--33
in the third-to-last. The default is -1 if no is given (last
empty box, immediately preceding the small calendars on the bottom row;
cf. --SS, --kk, and --KK, below). You can place several notes in the same
box. You can also use more than 1 box for the various monthly notes.
Lines in the configuration file consisting of iinnppuutt--llaanngguuaaggee XXXX (where
XXXX is the 2-letter specification for any of the supported languages)
can be used to set the language used for interpretation of the month
names and day-of-week names for the remaining event entries. This
option may be specified more than once, as needed, if the language used
to describe events changes within the file. For backwards compatibil-
ity, the default value for `input language' if this directive is never
used is 'en' (English). Note that this directive is distinct from the
specification of 'output language' as accomplished with the --aa option.
Comments are supported in the configuration file. Any characters fol-
lowing a `#' character are ignored, through the end of that line,
unless the `#' character is escaped by `\'.
DDeelleettiinngg EEvveennttss
By prepending the _`_d_e_l_e_t_e_' keyword to an event specification, one or
more events may be deleted from a set of previously-specified events.
For example, the following lines might appear in the date file:
all Friday in all Poker game
delete first Friday in all Poker game
This results in an event labeled `Poker game' on every Friday except
the first Friday of the month. If you delete an entry which is marked
as a holiday, the `holiday' flag for that day will be recalculated.
Any `delete' entries which don't match any pre-existing entries are
silently ignored.
FFoorrmmaatt SSppeecciiffiieerrss
_P_c_a_l allows format specifiers in both the event text and footer strings
(see the --LL, --CC, --RR, and --NN options below). Each format specifier will
be replaced by a corresponding string as outlined in the following ta-
ble:
%a abbreviated weekday
%A full weekday
%b abbreviated month name
%B full month name
%d day of month (1-31)
%j day of year (1-366)
%l days left in year (0-365)
%m month (1-12)
%U week number (0-53)
%W week number (0-53)
%u week number (1-54)
%w week number (1-54)
%y year w/o century (00-99)
%Y year w/century
%% `%' character
%o print number as ordinal
%0 print number with leading zeroes
%+ use following month or year
%- use previous month or year
%{+N}[DWMY] adjust date by +N days/weeks/months/years
%{-N}[DWMY] adjust date by -N days/weeks/months/years
Most of these are derived from the ANSI C strftime() function, but the
%%[[lloouuwwMMDD]] and %%[[oo00++--]] format specifiers are specific to _p_c_a_l.
The %%uu specifier considers the week containing 1/1 (Jan 1st) as week 1
and the following logical Sunday (the first day of the week as printed;
cf. the --FF option below) as the start of week 2; %%UU considers the first
logical Sunday as the first day of week 1. %%ww and %%WW behave like %%uu
and %%UU respectively, but use the first logical Monday instead. Note
that %%ww has a different meaning from strftime().
The %%oo format specifier prints a number as an ordinal, with the appro-
priate suffix (``st'', ``nd'', ``rd'', or ``th'' in English) appended.
For example, %%oodd prints the day of the month as ``1st'', ``2nd'',
``3rd'', etc.
Unlike strftime(), _p_c_a_l defaults to printing numbers (except %%yy) with-
out leading zeroes. If leading zeroes are desired, the `0' prefix may
be used. For example, %%00jj prints the first day of year as ``001''.
The %%++ and %%-- format specifiers direct _p_c_a_l to substitute the follow-
ing/previous month/year in the following [[bbBBmmyyYY]] specifier. For exam-
ple, %%++BB prints the name of the next month.
The %%{{[[++--]]NN}}[[DDWWMMYY]] format specifiers do not print anything, but instead
adjust the working date by +- NNdays (DD), weeks (WW), months (MM), or
years (YY). Subsequent format specifiers use the adjusted date instead
of the current date. For example, %%++11MM %%BB %%YY adjusts the date forward
by one month and then prints the resulting month and year (``January
1992'' in December, 1991); %%--22WW %%bb %%dd adjusts the date backward by two
weeks and prints the resulting month and day (``Jul 26'' on August 9).
Such date adjustments are normally cumulative; for example, %%++11YY%%--11DD
adjusts the date forward by one year and then backward by one day. If
%%DD or %%MM is specified alone (or if NN is zero), _p_c_a_l restores the origi-
nal date. Note that %%MM has a different meaning to the strftime() func-
tion.
Here's a common, useful example of an event entry for the _p_c_a_l date
file which combines the ability to adjust working dates and the ability
to display ordinals. This particular example is used to display text
on the birthday of a person born in 1991:
May 10 Eric's %-1991Y%oY Birthday
That entry would result in the following text being displayed on May
10, 2005:
Eric's 14th Birthday
EEnnccaappssuullaatteedd PPoossttSSccrriipptt ((EEPPSS)) IImmaaggeess
For monthly PostScript calendars only, _p_c_a_l supports the embedding of
one or more EPS images (photos, icons, etc) into any given day of the
month. (EPS image specifications in the _p_c_a_l date file are ignored for
yearly PostScript calendars and for all HTML calendars.)
In order to associate an image with a given event, you must add one or
more entries to the date file. The event date is specified exactly as
described previously for simple event text specification lines. How-
ever, instead of specifying the text associated with the event, you
instead specify the EPS image filename and some additional parameters
in the following format:
image:
Where:
is the filename (which can include a path)
of the Encapsulated PostScript image.
NNoottee:: The EPS image filename must be pre-
ceded by the constant text `image:' in
order to distinguish an EPS image specifi-
cation from an ordinary event text specifi-
cation.
is a scaling factor in the horizontal
dimension for the EPS image. A value of
1.0 is nominal (i.e. no change to image
scale). Values between 0.0 and 1.0 shrink
the image in the horizontal dimension while
values over 1.0 expand the image in the
horizontal dimension. Generally speaking,
only positive values should be used. How-
ever, in the rare case that you find that
your EPS image needs to be flipped about
the vertical axis (i.e. left to right), you
can use a negative value to achieve this
without having to tweak the actual Post-
Script content within the EPS image file.
Use of a negative value will undoubtedly
necessitate a corresponding change to the
parameter to account for the
image's relocated position that occurs when
it gets flipped "left-to-right".
is a scaling factor in the vertical dimen-
sion for the EPS image. Values between 0.0
and 1.0 shrink the image in the vertical
dimension while values over 1.0 expand the
image in the vertical dimension. Note that
a negative value for this parameter can be
useful in the less-than-rare case that you
find that your EPS image needs to be
flipped about the horizontal axis (i.e. top
to bottom). In such cases, you can use a
negative value to achieve this
without having to tweak the actual Post-
Script content within the EPS image file.
Use of a negative value will undoubtedly
necessitate a corresponding change to the
parameter to account for the
image's relocated position that occurs when
it gets flipped "upside down".
:= a horizontal adjustment in typographic
`points' (i.e. 72nds of an inch) for the
positioning of the EPS image. With offsets
of 0 for X and Y, the image will be printed
at the extreme left edge of the box for
that day, just under the numerics for that
day. Positive values move the image to the
right and negative values move the image to
the left.
:= a vertical adjustment in typographic
`points' (i.e. 72nds of an inch) for the
positioning of the EPS image. With offsets
of 0 for X and Y, the image will be printed
at the extreme left edge of the box for
that day, just under the numerics for that
day. Positive values move the image up and
negative values move the image down.
Here's an example of a line from the date file that associates an EPS
image with an event:
4th Thu in Nov* Thanksgiving
4th Thu in Nov* image:/eps-path/turkey.eps 1.0 1.0 0 0
You can place as many images as you want on a single day of the month
by specifying repeated lines in the date file. For example, these
lines put icons of George Washington and Abraham Lincoln on the day of
the U.S. ``Presidents' Day'' holiday, along with the event text:
3rd Monday in Feb* Presidents' Day
3rd Monday in Feb* image:/eps-path/washington.eps 0.08 0.08 8 0
3rd Monday in Feb* image:/eps-path/lincoln.eps 0.22 0.22 48 0
Note that the icon for Lincoln is shifted to the right by 48 typo-
graphic points so as not to overlay the first icon.
The _p_c_a_l releases come with a single EPS sample file ('eps/recy-
cle.eps') of the ubiquitous 'recycle' icon (3 green arrows in a trian-
gular shape). Such an image might be used with configuration file set-
tings like this:
second Sat in all RECYCLE!
second Sat in all image:/eps-path/recycle.eps 0.039 0.039 34 -9
In cases where you're displaying non-holiday event text (e.g. someone's
birthday) and an EPS image, you'll often need to use a negative `Y-
delta' value on the EPS image specification line, in order to shift the
image down so that it doesn't cover the event text, which appears just
below the day's numerics for non-holiday events. (Text for holiday
events appears higher up, to the right of the day's numerics, so
there's usually no collision with the EPS image.)
NNoottee:: Unfortunately, most EPS images cannot be used directly by _p_c_a_l.
Depending on the EPS image used and how it was created, you may
have to remove or comment out some or all of the PostScript
`translate' commands, in order to avoid the use of illogical X-
delta and Y-delta values when specifying the EPS image in your
_p_c_a_l date file. Most programs that generate EPS output (either
directly or via conversion from some other graphic format) seem
to have these `translate' commands relatively early in the EPS
file.
It may take some experimentation to get it just right. Preview
the _p_c_a_l output using a PostScript viewer as you tweak the Post-
Script commands in the EPS image file and/or the event entry in
the _p_c_a_l date file.
NNoottee:: Depending upon what application you use to preview
PostScript content, the monthly calendars may not show
any embedded EPS images. Here's a rundown of some popu-
lar PostScript-viewing applications and whether they cor-
rectly display the embedded EPS images:
+o gv (version 3.5.8) -- EPS images appear fine
+o ggv (versions 2.4.0.1 and 2.6.1) -- EPS images
appear fine
+o older kghostview (versions 0.13.2 [KDE 3.1.4]
and 0.2.0 [KDE 3.2.3 and 3.3.2]) -- EPS images
DO NOT APPEAR!
+o newer kghostview (version 0.2.0 [KDE 3.4.2 and
3.5.4]) -- EPS images appear fine
For converting non-EPS images (e.g. photos) to EPS format, one can use
the graphical GNU Image Manipulation Program, a.k.a. `The GIMP':
_h_t_t_p_:_/_/_w_w_w_._g_i_m_p_._o_r_g
For icons/images in WMF format (which are popular in various 3rd-party,
legacy-OS, commercial calendar programs), the `libwmf'/`wmf2eps'
library/utility is useful for generating _p_c_a_l-capable EPS images. It
can be found at this site:
_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
For icons/images in SVG format, the ImageMagick `convert' utility is
sometimes useful for generating _p_c_a_l-capable EPS images. This suite of
utilities (which includes other useful ImageMagick utilities like `dis-
play' and `identify') may already be available on your Linux distribu-
tion. If not, it can be found at this site:
_h_t_t_p_:_/_/_w_w_w_._i_m_a_g_e_m_a_g_i_c_k_._o_r_g
For cases where ImageMagick's `convert' utility fails to properly con-
vert SVG-format images to EPS format, you can try the method of con-
verting the SVG image into an intermediate format (e.g. PNG) using the
`rsvg' utility. This utility may already be available on your Linux
distribution. If not, it can be found at this site:
_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_/
From the PNG format, the image can often then be successfully converted
to EPS format, using the above-mentioned ImageMagick `convert' utility.
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
(many of which are in SVG format) for decorating your events:
_h_t_t_p_:_/_/_w_w_w_._o_p_e_n_c_l_i_p_a_r_t_._o_r_g
NNoottee:: The EPS image content is not generated in the PostScript output
-- only a reference to the EPS image filename is generated. From a
practical standpoint, this means that normally you'll need to
print/preview the PostScript output of _p_c_a_l from the same computer/set-
up as that which was used to run _p_c_a_l in the first place. If you want
to generate a calendar with embedded EPS images that will later be
printed/viewed on another machine which does not have access to those
EPS images, you'll need to run the output through a pre-processor which
will put the EPS image content into the PostScript output file. For
example, assuming your initial calendar output was generated to a file
named `pcal.ps', on most GNU/Linux systems you could run this command,
which uses the popular `Ghostscript' interpreter:
gs -r300x300 -dBATCH -dNOPAUSE -sDEVICE=pswrite -sOutput-
File=out.ps pcal.ps
This would generate a PostScript file named `out.ps', at 300x300 dpi
resolution, which has the actual EPS image content embedded within,
allowing you to transport the `out.ps' file to another computer for
viewing/printing. Of course, the new file is substantially larger, but
it's portable. Furthermore, the EPS images will be viewable even in
PostScript-viewing applications (see above) which don't properly sup-
port the display of embedded (by filename only) EPS images.
PPrree--PPrroocceessssoorr FFuunnccttiioonnaalliittyy
_P_c_a_l supports rudimentary _c_p_p-like functionality in the date file,
allowing the following constructs:
+o ddeeffiinnee || uunnddeeff
+o iiff{{{{nn}}ddeeff}} ...... {{eelliiff ......}}** {{eellssee ......}} eennddiiff
+o iinncclluuddee
Note that these are not preceded by `#' as they are in C.
Symbol names defined using these keywords (or via the --DD option) are
case-insensitive. It is not an error to uunnddeeff an undefined symbol, nor
to ddeeffiinnee a previously-defined one.
A symbol can be defined with just a name (e.g. ``define MY_SYM'') or it
can take on a value (e.g. ``define MY_SYM SOME_VALUE''). Use of symbol
values is convenient for defining a starting date then using that sym-
bol to reference that starting date in one or more events. For exam-
ple, these definitions in the date file might be useful:
define semester_start 8/23 # Beginning of semester
semester_start Class Start
7th day after semester_start 1st Quiz
14th day after semester_start 2nd Quiz
undef semester_start
Be aware that the substitution of symbol values for symbol names is not
robust, so it's wise to use a symbol name that's unlikely to occur in
any of your other event text. In other words, if you defined the `se-
mester_start' symbol in the example above as merely `start', then you'd
get the undesired effect of having the text `Class 8/23' in your calen-
dar on that day instead of `Class Start'! The use of `undef semes-
ter_start' in the above example is optional and is really only useful
to prevent any unwanted symbol substitutions later on, which probably
won't happen unless you poorly choose your symbol name to begin with.
An iiffddeeff alone is always ffaallssee; an iiffnnddeeff alone is always ttrruuee. iiff is
accepted as a synonym for iiffddeeff.
The name of the file in the iinncclluuddee directive may optionally be sur-
rounded by either "" or <>, both of which are ignored. If the name is
not an absolute path, it is taken to be relative to the directory where
the file containing the directive is located. If the string "%y"
appears in the file name, it is replaced by the last two digits of the
current year or, if "year all" is in effect, is expanded to all appli-
cable years. _P_c_a_l is smart enough to translate ~~// to the user's home
directory.
_P_c_a_l normally terminates immediately if the file specified in an
iinncclluuddee directive does not exist. An alternate form of the directive,
iinncclluuddee??, directs _p_c_a_l to continue silently if the file does not exist
or cannot be opened.
In addition to pre-processing keywords, _p_c_a_l also accepts boolean
expressions in iiff{{{{nn}}ddeeff}} and eelliiff directives. These expressions con-
sist of symbol names joined by the boolean operators !!, &&, ^^, and ||, in
order of precedence, high to low. Parentheses may be used to alter the
precedence. The synonyms &&&& and |||| are accepted for && and ||. A symbol
name evaluates to ttrruuee if currently defined, ffaallssee if not; thus:
ifdef A | B | C
...is ttrruuee if any of the symbols A, B, and C is defined, and:
ifdef A & B & C
...is ttrruuee if they all are. Note that iiffnnddeeff <> is equivalent to
iiffddeeff !!(( <> ))..
TThhee MMoooonn FFiillee
If a file of the name _._m_o_o_n_#_# (_m_o_o_n_#_#_._d_a_t under MS-DOS), where #### is
the last two digits of the calendar year, exists in the same directory
as the date file (or in the directory where _p_c_a_l resides), _p_c_a_l uses
the information contained within to calculate the phase of the moon.
If a) no such file exists, b) the --ee flag (do not use a date file) is
specified, or c) the --zz flag (specify time zone) is specified, then
_p_c_a_l uses an algorithm to calculate the phase of the moon.
Entries in the moon file must conform to the following syntax:
If the --AA option (American date formats, the default) is given:
{}
If the --EE option (European date formats) is given:
{}
Where:
:= ``nm'', ``fq'' or ``1q'', ``fm'', ``3q'' or ``lq'' (new moon,
first quarter, full moon, last quarter)
:= number 0-23 (24-hour clock)
:= number 0-59
This file must contain entries for all quarter moons in the year, in
chronological order; if any errors are encountered, _p_c_a_l will revert to
using its default algorithm.
As in the date file, comments start with `#' and run through the end of
the given line.
The moon file may optionally contain an oopptt --AA or oopptt --EE line to spec-
ify the format of its own date entries independently of the format used
in the date file. No other flags are legal in the moon file.
GGeenneerraattiinngg PPoossttSSccrriipptt CCaalleennddaarrss VViiaa AA WWeebb BBrroowwsseerr IInntteerrffaaccee
PostScript-format _p_c_a_l calendars can be generated and viewed from a web
browser interface.
NNoottee:: This is not to be confused with the ability to generate
non-PostScript, HTML-format (using the --HH command-line option)
calendars, which is a different capability entirely.
_P_c_a_l comes with 4 files that provide this ability: `pcal.cgi' (a Bourne
shell script), `pcal.pl' (a Perl equivalent of `pcal.cgi'),
`pcal.html', and `pcalw.html'.
The CGI file (either `pcal.cgi' or `pcal.pl') must be edited before
using it. Change the definition for _`_p_c_a_l_=_' (Bourne shell script) or
_`_m_y _$_P_C_A_L _=_' (Perl script) to point to the location of the _p_c_a_l exe-
cutable file. Change the definition for _`_f_i_l_e_=_' (Bourne shell script)
or _`_m_y _$_F_I_L_E _=_' (Perl script) to point to the location of the _p_c_a_l
`date file' (e.g. `.calendar'), which contains the options for running
_p_c_a_l. Finally, copy the `pcal.cgi' (or `pcal.pl') file to the location
where your web server expects to find such files (e.g. `/var/www/cgi-
bin/').
The `pcal.html' and `pcalw.html' files must also be edited. Each one
has a line like this: