-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
Overview:
Pcal is a multi-platform program which generates annotated PostScript or
HTML calendars in a monthly or yearly format.
It is usually run from the command line but there is an HTML/CGI capability
as well, to generate calendars from a web-browser interface.
Various events can be defined in an external text file to control the
appearance of the calendars generated by 'pcal'. On monthly PostScript
calendars, one or more EPS (Encapsulated PostScript) images (photos, icons,
etc) can be displayed on any given day of the month.
For much more detail on the available options and use of 'pcal', use any of
the following sources:
- View the manual page for 'pcal' by running 'man pcal' after
installation.
- View any one of the supplied help files:
'pcal-help.ps' -- PostScript (nicest to view)
'pcal-help.html' -- HTML
'pcal-help.txt' -- ASCII text
These files contain the same content as the manual page ('man pcal')
but in different formats. They were generated prior to the release of
'pcal' with these commands (on Unix-like systems):
groff -man -Tps pcal.man >pcal-help.ps
groff -man -Thtml pcal.man >pcal-help.html
groff -man -Tascii pcal.man >pcal-help.txt
A simpler way to generate those files is to run 'make man', which
should already have been done just prior to the release of a new
version of 'pcal'.
- Run the command 'pcal -h' to get a detailed list of help and
command-line options. This output is not always as thorough as the
help sources mentioned above, but since it is generated directly from
the program's internal variables, it will always show the most
up-to-date information, in the rare case that the documentation
mentioned above wasn't updated to match the program changes.
- Here's a quick, current, alphabetical list of all the 'pcal' options
and their associated meanings:
------------------------------- clip 'n' save -------------------------------
-A parse American date format -a select output language (for months/days)
-B don't fill unused day boxes -b print day in black
-C define centered footer string -c generate "calendar" utility input
-D define preprocessor symbol & value -d select alternate day font
-E parse European date format -e print empty calendar
-F define alternate starting day -f select alternate date file
-G print day as color-filled outline -g print days in special color (default gray)
-H generate calendar as HTML table -h generate full help message
-I re-initialize program defaults -i <unused>
-J print Julian day and days remaining -j print Julian day (day of year)
-K prev/next-month in 1st/last box -k prev/next-month in 1st 2 boxes
-L define left-justified footer string -l landscape mode
-M print all moons -m print new/half/full moons
-N define heading for notes box -n select alternate notes font
-O print day as empty colored outline -o select alternate output file
-P paper size (letter, legal, a4, tabloid) -p portrait mode
-Q <unused> -q generate yearly-planner style HTML calendar
-R define right-justified footer string -r remap fonts for 8-bit characters
-S suppress small prev/next-month calendars -s define date color & fill box shading color
-T select typeface for date/note text -t select alternate title font
-U undefine preprocessor symbol -u display parameter usage message
-V <unused> -v display version ID
-W <unused> -w print whole-year/page calendar
-X X-axis transformation -x X-axis scale factor
-Y Y-axis transformation -y Y-axis scale factor
-Z generate debugging information -z specify alternate time zone
-# print multiple copies of each page
The 'pcal' (and 'lcal' [lunar calendar]) homepage is:
http://pcal.sourceforge.net
The 'pcal' and 'lcal' applications are available at:
http://sourceforge.net/projects/pcal/
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
Building 'pcal':
Unix/Linux:
make
make install (as 'root' user)
OS/2:
make OS=OS2
make OS=OS2 install
Untested as of Dec 2004!
DOS (Borland, etc):
make -f Makefile.DOS
Successfully compiles with Borland C++ v5.0 (and probably several other
earlier/later versions of Borland C++ or Turbo C/C++).
DOS (using DJGPP):
make OS=DJGPP
make OS=DJGPP install
VAX:
Undocumented -- see the 'Make_Pcal.com', 'Makefile.MMS', 'SetUp.com',
and 'VaxCrtl.opt' files
Amiga:
Undocumented -- see the 'Makefile.Amiga' file
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.9.0
This release of 'pcal' includes additional functionality, some bug fixes,
and an update of the associated documentation.
Major changes:
1) New functionality:
- Added new PostScript encoding vectors to support the following
character sets:
- KOI8-R -- Russian
- ISO 8859-2 -- Latin2 (East European)
- ISO 8859-3 -- Latin3 (South European)
- ISO 8859-4 -- Latin4 (North European)
- ISO 8859-5 -- Cyrillic
- ISO 8859-7 -- Greek
- ISO 8859-9 -- Latin5 (Turkish)
- ISO 8859-10 -- Latin6 (Nordic)
- ISO 8859-11 -- Thai
- ISO 8859-13 -- Latin7 (Baltic Rim)
- ISO 8859-14 -- Latin8 (Celtic)
- ISO 8859-15 -- Latin9 (adds euro, etc)
Note that not all of these new encodings are currently used, simply
because a language which requires the use of a given encoding may
not yet be supported by 'pcal'. Any of these encodings which are
not yet used have been added with the intent of simplifying the
future addition of support for other languages.
Furthermore, encodings for Arabic (ISO 8859-6), Hebrew (ISO 8859-8),
and Latin10 (ISO 8859-16) are not currently supported at all, but
placeholders have been added to the 'pcal' source code to allow
easier entry of those encodings in the future, if someone comes up
with the necessary PostScript encoding vectors.
- Support for the following languages has been added:
- Czech ("-a cz")
- Hungarian ("-a hu")
- Catalan ("-a ca")
- Russian language support is no longer considered "experimental", now
that 'pcal' properly supports the KOI8-R character encoding.
The default encoding for Russian is now KOI8-R instead of KOI8-U
(which was used in v4.8.0 as a crude, temporary method).
Latvian and Lithuanian language support is no longer considered
"experimental", now that 'pcal' properly supports the 'Latin7' (ISO
8859-13) character encoding.
The default encoding for both Latvian and Lithuanian is now 'Latin4'
instead of 'Latin1' (which was used in v4.8.0 as a crude, temporary
method).
2) New date file functionality:
- Based on a patch from Bill Bogstad, added the capability to delete
specific events, thereby allowing one to exclude one or more events
that were inserted as a group of events, by using the new 'delete'
keyword.
More details are in the 'man' page.
The sample configuration file ('examples/pcal-cfg.txt') also
includes an example of the usage of this new capability.
3) Other changes:
- Changed the date/event separator character from a space to a tab
when using the '-c' option (to output text lines which are
compatible with the Unix 'calendar' program).
This was done at the behest of a user who found that the space
character was inadequate as a separator. In fact, the 'calendar'
program from a recent stable version (6.0.17) of the Debian
'bsdmainutils' package proves that the space character is truly
inadequate as a separator when running 'pcal -c > pcal-output.txt;
calendar -f pcal-output.txt'.
- Added a Perl script ('html/pcal.pl') from David Mathog which is an
alternate way (compared to the existing 'pcal.cgi' Bourne shell
script) to generate calendars via HTML/CGI.
- Now that new character encodings are available, the default
Greek-language character encoding was changed from 'Latin-1' (ISO
8859-1) to 'Greek' (ISO 8859-7) to prevent having to specify '-r
none' in order to get a usable Greek calendar.
- Added new 'pcal' calendar configuration files to the 'examples/'
directory:
- 'calendar_us.txt'
This example, provided by J. Rhett Hooper, contains events
for users in the USA.
- 'calendar_hu.txt'
This example, provided by Ferenc Kruzslicz, contains events
for users in Hungary.
- Now that the Latin3 (ISO 8859-3) character encoding is provided,
there's no need to use the previous (customized) method of
supporting the Esperanto language. Because of this, the custom
'Esperanto' encoding has been eliminated.
Esperanto speakers/users should now just use the standard 'Latin3'
(ISO 8859-3) characters, which fully support the unique characters
in the Esperanto language.
This change cleans up the code in several spots.
- Tweaked several of the sample calendar configuration files in the
'examples/' directory to not specify any fonts.
The specification of fonts is better left to the command line,
since the necessary fonts to display/print a given language's
calendar will undoubtedly differ amongst various users.
- Added several new 'examples/fonttest_*' files to support testing
of the various character encodings. These 'font test' files can
be used as shown in this example to check any of your fonts for
use with the specified character encoding:
pcal -f examples/fonttest_koi8r -n some_koi8_fontname
Renamed old 'examples/fonttest_x' files to be more explicit,
thereby avoiding confusion with newly-added 'fonttest' files.
- Fixed a long-standing misrepresentation of the Spanish word for
'Saturday'. The word is 'Sábado', but the acute accent on the
first 'a' was missing.
- Fixed misrepresentations of the Lithuanian word for 'August' and
the Latvian words for 'June' and 'July'. Since these languages
were added in the previous release, these months erroneously used a
'u'+circumflex instead of the proper 'u'+macron.
4) Bug fixes:
- Fixed a bug introduced in version 4.8.0 whereby the specification
of a plural form of the day-of-week name was not being properly
detected, reporting an 'unrecognized line in file' error. Here's
an example:
all Fridays in Oct xxxxx
Thanks to Pedro I. Sanchez <pedro.sanchez at rogers.com> for
reporting this bug.
A work-around for this bug was to simply change the plural form to
the singular form (e.g. "Fridays" to "Friday" or just "Fri").
- Fix a long-standing bug whereby a centered "footer" specification
with 'strftime()'-like date specifiers used in an HTML yearly
calendar was using/showing the correct date values for the HTML
'title' but the wrong date values for the centered header string at
the start of the actual displayed (HTML) content.
5) Documentation changes:
- Added an entry to this 'ReadMe.txt' file in the v4.8.0 'Bug fixes'
section due to a last-minute v4.8.0 change to fix a couple of
security holes which accidentally went undocumented in this file.
- Various updates throughout.
6) Of interest to 'pcal' hackers and installers:
- All PostScript encoding vectors used to define the various
character encodings were defined as 'readonly'. This is mostly a
cosmetic change rather than a functional change.
- Made changes to the 'Makefile.DOS' file to accommodate the separate
directories for the source, the objects, and the executables. That
change should have been part of the v4.8.0 release but was
accidentally neglected.
Make further changes to the DOS build process (via 'Makefile.DOS'):
- Define '-DEPS' so that EPS-compatible PostScript is generated,
just like has been done for the Unix build for a while. This
allows PostScript utilities to process pages more
intelligently (e.g. so that a preview utility can page up and
down properly).
- Define several compile-time flags to prevent certain warnings.
- Define the '-DPROTOS' compile-time flag to include full
prototypes, thereby preventing many warnings about 'missing
prototype'.
- Define the '-DSTDLIB' compile-time flag to prevent warnings
about multiply-defined prototypes.
- To enhance compatibility with the Debian GNU/Linux distribution,
made a change to the (Unix, OS/2, DOS+DJGPP) 'Makefile' file
(specifically, to the 'D_SEARCH_PCAL_DIR' variable) to default to
_not_ searching the directory with the 'pcal' executable file when
searching for the 'calendar' ('pcal' configuration) file.
- Made a minor change to the (Unix, OS/2, DOS+DJGPP) 'Makefile' file
based on a patch from Thiago F.G. Albuquerque to prevent an error
when building in the DOS+DJGPP environment when the directory
specified by 'CATDIR' does not exist.
- Remove obsolete comment in the 'Makefile' file about separate
directories for the source, the objects, and the executables. This
comment was accidentally left in place for the v4.8.0 release.
- In 'pcallang.h', to be consistent, converted all high-order
characters in the language string specifications to simple octal
format, to match the octal format used in the PostScript encoding
vector specifications of 'pcalinit.ps'. This makes it easier to
edit the 'pcallang.h' file in any editor. It also makes checking
of the language strings against the character encodings simpler.
Credits:
The original calendar PostScript was Copyright (c) 1987 by Patrick Wood
and Pipeline Associates, Inc. with permission to modify and
redistribute.
The following people contributed to Pcal v4.9.0:
Bug fixes, 12 new character encodings,
language support, various other fixes: Bill Marr
Event deletion capability: Bill Bogstad
Czech language support: Peter Cernoch
Hungarian language support: Ferenc Kruzslicz
Catalan language support: Carles Sadurní Anguita
Perl script for HTML/CGI: David Mathog
US example calendar: J. Rhett Hooper
DOS/DJGPP build fix/support: Thiago F.G. Albuquerque
For a list of all known contributors to date, see the 'Authors' section
of the 'man' page.
Bill Marr (marr99@users.sourceforge.net)
18 Aug 2005
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.8.0
This release of 'pcal' includes additional functionality, some bug fixes,
and a thorough update of the associated documentation.
Major changes:
1) New functionality:
- A method of adding Encapsulated PostScript (EPS) images to any
given day(s) on a monthly-format calendar has been incorporated.
Now you can have (e.g.) photos of a person on their birthday and/or
icons for various holiday events, etc.
For details, see the expanded documentation in the 'man' file, but
briefly, to add an EPS image (photo, icon, etc) to a day, use an
event entry like this (for the Thanksgiving holiday event):
4th Thu in Nov* image:/eps-path/turkey.eps 1.0 1.0 0 0
The 'image:' text is a keyword which precedes the EPS image
filename. As shown, a path to the file can be specified.
The first 2 values after the EPS image name are X/Y scaling values,
in case the output of the EPS file is not sized properly (which is
almost always the case) to fit in the 'day box'. The last 2 values
are X/Y translations, in case you want to move the EPS image around
within the 'day box'.
Note: Your EPS images will not be directly usable! As a minimum,
you'll first need to remove/comment-out the PostScript 'showpage'
command near the end of the EPS image file! Depending upon the
source of the EPS image, you may also want to remove/comment-out
some of the PostScript 'translate' commands too.
Again, much more information about all this can be found in the
'man' page for 'pcal', so please read that first!
A sample EPS image (the 'recycle' icon, with 3 green arrows in a
circle) has been provided with the 'pcal' distribution (under the
'eps/' directory) as a quick way to test the EPS image embedding
capability on one of your calendars. This file was converted from
a '.WMF' image file (using the 'libwmf'/'wmf2eps' library/utility
mentioned in the 'man' file) and the string '%%% DISABLED: ' was
prepended in 3 spots to disable the PostScript 'translate' and
'showpage' commands associated with those lines. This file is
intended as a guide for what needs to be done to make your own EPS
images usable by 'pcal'.
To test with this sample EPS icon, add lines like these to your
'pcal' configuration file:
second Sat in all RECYCLE!
second Sat in all image:/path-to-eps/recycle.eps 0.029 0.029 66 -28
With the provided X/Y scaling and X/Y translation values, it should
place the symbol in the lower right corner of the 'day box',
assuming you're using letter-sized paper and landscape orientation
on a monthly calendar.
- Support for 'legal' (8.5 x 14.0 inch) and 'tabloid' (11.0 x 17.0
inch) paper has been added.
Specifying the paper size is now done differently than in the past.
See the section 'New command-line options' (below) for details.
- Added new automatically-defined symbols based on the current paper
size:
- "PAPERSIZE_LETTER"
- "PAPERSIZE_LEGAL"
- "PAPERSIZE_A4"
- "PAPERSIZE_TABLOID"
These can be useful for providing alternate values in the 'pcal'
configuration file for EPS image placement and scaling, based on
paper size.
- Added new automatically-defined symbols based on the current page
orientation:
- "ORIENTATION_PORTRAIT"
- "ORIENTATION_LANDSCAPE"
These can be useful for providing alternate values in the 'pcal'
configuration file for EPS image placement and scaling, based on
the page orientation.
- Support the definition of a symbol value along with a symbol name in
'define' pre-processor directives in the 'pcal' configuration file.
For example:
define sem_start 8/23 # Beginning of semester
sem_start CIS136 Start
7th day after sem_start CIS136 Quiz 1
14th day after sem_start CIS136 Quiz 2
undef sem_start
This capability came from an unknown author via the Debian Bug
Tracking System for 'pcal'. It was somewhat buggy in the Debian
implementation, but was (completely?) repaired prior to inclusion in
this release of 'pcal'.
- Support for the following languages has been added:
- Swedish ("-a sv")
- Ukrainian ("-a uk")
- Portuguese ("-a pt")
- Estonian ("-a et")
- Russian ("-a ru")
- Latvian ("-a lv")
- Lithuanian ("-a lt")
Note: The support for Russian, Latvian, and Lithuanian is
considered "experimental". The day-of-week names and month names
have been provided for these languages, but the character encodings
have not been provided. Russian support has been set up to use the
KOI8-U (Ukrainian) character encoding instead of the KOI8-R
encoding that it should use. Latvian and Lithuanian support have
been set up to use the Latin-1 (ISO-8859-1) encoding instead of the
ISO-8859-13 character encoding that they should use. From a
practical standpoint, this probably means that these languages will
appear mostly correct (i.e. for characters which can be
displayed/printed in the encoding used) but will not be 100%.
Patches would be gratefully accepted from anyone with the expertise
to provide the necessary character encodings!
- Substantial changes were made to the HTML user interface used to
generate calendars.
Added the appropriate option for the (already-existing) Finnish
language support.
Changed the 'Language:' selection in HTML calendar generation files
('pcal.html' and 'pcalw.html') to support the new languages. Also,
make this a 'drop-down' list instead of a series of 'radio
buttons', which makes for a cleaner interface now that there are 12
language options.
Added a new 'Paper Size' option to correspond to the new '-P'
option to 'pcal'.
Changed the description of the last option ('Holidays:') to 'Bypass
Date File Processing:' to more accurately reflect what it really
does! Changed the interface for this item to a 'check box' instead
of 2 'radio buttons' to match common user interface guidelines and
to clean-up the interface.
Changed references to 'gray' date numerics to instead say "'date
shade' color (default = gray)" to reflect the fact that a user can
override the 'grey' default color in his/her 'pcal' options file
(via the 'opt -s ...' command/switch).
Provide a new 'default' option for all the 'Day Numerics' (Weekday,
Sat/Sun, Holiday) selection sets. This allows the CGI script to
bypass the specification of the '-g', '-O', '-G', and '-b' options.
This is needed because of odd interactions between these switches
which prevented the creation of a simple colored calendar. For
example, there was no way to generate a monthly or yearly calendar
with the defaults (Mon-Fri in black, Sat/Sun in the 'date shade'
[gray by default] color, and holidays in the 'date shade' [gray by
default] color, even though this is the common case when PostScript
calendars are generated from the command line version of 'pcal'.
Make separate entries for 'day numerics' font and 'title (etc)
font' to the user interface since these are distinct and therefore
separately controllable in 'pcal'. Previously, whatever font the
user selected was used in both cases.
Overhauled each group of 'radio buttons', changing from a
horizontal set of options (which was long and difficult to discern
for some entries) to a nicer, more-readable set of
vertically-aligned options in a clean, captioned table for each
group of radio buttons.
Provide the user interface option to generate HTML-format calendars
instead of PostScript-format calendars.
2) New command-line options:
- In the past, the paper size could only be specified via the
'Makefile', which required recompiling if you wanted to change
paper sizes. This is somewhat bothersome, but even more so now
that 'pcal' supports more paper sizes (i.e. not just 'letter' and
'A4').
Beginning with this release of 'pcal', a new '-P' option is now
supported to declare the 'paper size'. This option takes a value
which can be any of the following (case-insensitive) values:
- "letter"
- "legal"
- "a4"
- "tabloid"
This option can be specified using any of the 3 methods: (1) via
the 'PCAL_OPTS' environment variable, (2) via the 'pcal'
configuration file (aka '.calendar', aka the 'date' file), or (3)
via the command line itself.
3) New date file functionality:
- Added support for "Friday the 13th" events. Use the keyword 'F13'
on the event specification. For example:
F13 Avoid black cats!
- Added a new 'input-language' directive for the 'pcal' configuration
file. It takes a single parameter -- the 2-letter version of the
ISO 639 (language code) standard. This 'input language' will be
used when deciphering any month names and/or day-of-week names when
processing the event entries in the 'pcal' configuration file. The
default language is currently the same as the default 'output'
language (English).
An example entry in the 'pcal' configuration file:
input-language fr # interpret event dates in French
In previous versions of 'pcal', which had no concept of 'input' and
'output' languages, both the default language (English) and the
currently-selected ('output') language were checked when parsing
and checking for month names and day-of-week names during event
processing. For the same reason as the creation of this new
'input-language' directive (i.e. to avoid conflicts), the default
language is no longer checked in addition to the current (input)
language. Only the current 'input' language is checked.
Note that the input language only makes sense in the 'pcal'
configuration file, so it can only be specified there.
Note also that the 'input language' can be changed as needed at any
time during processing of the 'pcal' configuration file, for the
rare case where someone has multiple language event definitions
within the same file.
4) Other changes:
- The 2-letter language code for Greek was re-assigned from 'gr' to
'el' to be compatible with ISO 639 (2-letter and 3-letter language
codes).
This means that you need to (for example) use '-a el' on the 'pcal'
command line to generate a Greek-language calendar rather than the
old '-a gr'.
- Added the '-p' and '-l' flags ('portrait' and 'landscape' paper
orientations) to the list of those processed from the command line
prior to the processing of the 'pcal' configuration file.
This is needed so that directives like 'ifdef ORIENTATION_PORTRAIT'
in the configuration file work as expected.
- Collected all sample 'calendar options' files for various countries
(some which were on the 'pcal' website or in the mailing list
archives but weren't part of the actual distribution) and named
them all 'calendar_XX.txt' where 'XX' is the 2-letter country name
code based on the ISO 3166 standard. This required a change to the
Greek ('gk' to 'gr') and Estonian ('et' to 'ee') 2-letter codes
used in the filenames.
Since 'pcal' can be run under DOS, converted sample 'calendar
options' files from Unix-style to DOS-style line-endings (as
needed) for maximum portability.
- The '%a' format specifier (which is used to represent the
abbreviated day-of-week name [e.g. 'Wed']) was using a simplified
method of generating the abbreviated name from the full name -- by
using just the first 3 characters.
With the addition of Ukrainian and (later) Estonian language
support, this simple scheme became inadequate because those
languages don't use 3-character abbreviations for the day-of-week
names.
Instead, a new array (with entries for each supported language) of
the abbreviated day-of-week names was created. The '%a' format
specifier uses this new array to derive abbreviated day-of-week
names.
5) Bug fixes:
- Fixed a design flaw whereby certain languages (like Italian,
French, Esperanto, and Spanish) which have a day-of-the-week name
with the same first 3 letters as a month name can cause problems
detecting events in the 'pcal' configuration file.
Aside: When parsing unknown tokens, day-of-week names are compared
before month names.
For example, French has the day 'Mardi' (Tuesday) and the month
'Mars' (March). Finnish has the day 'Maanantai' (Monday) and the
month 'Maaliskuu' (March). The following event in the configuration
file will yield an error because the string intended as an
abbreviated month name 'Mar' (for 'Mars'/March) is erroneously
interpreted as a weekday name 'Mardi':
Mar 21 Event for March 21st
It should be possible to specify the full month name ('Mars') to
avoid the conflict, but 'pcal' was only examining the first 3
letters of the weekday names when looking for a matching token.
The code which looks for matching weekday names has now been
modified to use the full length of the specified token string from
the configuration file, which allows one to specify the full name
of the month to avoid any conflict.
Note: A similar change was made to the month name comparison,
because an event of 'Mars 21' (French) was being erroneously
detected in an English-language setting! This ties in with the new
'input-language' directive (described above).
- Fix bug whereby 'Holidays:' option in 'pcalw.html' was using older,
incorrect name, causing that option to be completely ignored.
- Fixed the bug (present since v4.7.1 of 'pcal', and previously
documented on the 'pcal' website) whereby use of the '-q' option to
generate 1-column-per-month HTML output required one to use the '-F
1' flag to force the day-of-week to begin with 'Monday'. This
restriction is now removed and one can generate HTML
1-column-per-month calendars with any value for the '-F' flag (or
without using the '-F' flag at all).
- Fixed a couple of security holes whereby a malicious calendar file
(e.g from an external source) could cause an exploitable buffer
overflow attack.
6) Documentation changes:
- Made major changes to the 'pcal.man' file to bring it up-to-date
and make it more useful and/or readable, both in raw format and as
a rendered 'man' page.
Those changes are described in detail in a newly-added comment
section at the beginning of that file, which acts as a 'ChangeLog'
section. See that file for details.
- Provided a new sample 'pcal' configuration file ('pcal-cfg.txt') in
the new 'examples/' subdirectory.
This file attempts to demonstrate the various features that are
possible with 'pcal' in a manner which is well-documented and can
be easily incorporated by others into their own 'pcal'
configuration file(s). It was created with the idea that "an
example (or two, or three) is worth a thousand words".
Among other things, it demonstrates the use of various format
specifiers, the use of the 'Notes' box, the use of pre-processor
directives and conditional processing, and the use of some
predefined events.
- Removed the 'Pcal.hlp' file, which was essentially just a duplicate
of the 'pcal.man' content in a human-readable form. The content of
the 'pcal.man' file is intended to be pre-rendered (by the 'pcal'
maintainer / release manager) into other human-readable forms
(PostScript, HTML, ASCII text) as described in the 'Overview:'
section at the beginning of this file.
Now, there are essentially just 2 files which need to be updated to
document 'pcal' operation: 'pcal.man' and 'ReadMe.txt'.
Renamed 'ReadMe' to 'ReadMe.txt' and merged all the old versions of
'ReadMe.4.x' into that single file for clarity, consistency, and
ease of access.
- Moved old 'pscalendar' file into the new 'doc/obsolete/' directory
since it only has historical significance.
7) Of interest to 'pcal' hackers and installers:
- Created new subdirectories to better organize the 'pcal'
distribution files:
- 'src/'
all 'pcal' source code (*.c, *.h, *.ps)
- 'obj/'
empty subdirectory which will contain all object code and the
single C header file ('pcalinit.h') which is auto-generated
at compile time
- 'exec/'
empty subdirectory which will contain all executable code
('pcal[.exe]' and 'pcalinit[.exe]')
- 'doc/' and 'doc/obsolete/'
various documentation (current and historical)
- 'examples/'
several sample 'calendar options' files, mostly for various
holidays in each of several countries; also includes various
'calendar options' files used to test the fonts and character
mappings
- 'html/'
files used to generate calendars using the HTML/CGI (web
browser) interface
- Added build instructions for the various platforms that 'pcal'
supports to this file ('ReadMe.txt').
- Added a new compile-time flags setting ('CFLAGS = -O2 -Wall -W') to
the Unix 'Makefile'. The first 2 of those flags were already in
the OS/2 'make' file (which was almost identical to the Unix
'Makefile'), but for some unknown reason they were not in the Unix
'Makefile'.
Added a brief description of each flag ('-O2' and '-Wall' and '-W')
used on the 'CFLAGS = ...' line to the Unix 'make' file.
For those not familiar with these flags, '-O2' provides code
optimization, '-Wall' enables many compile-time warning messages,
and '-W' enables more compile-time warning messages.
Made several minor code modifications to prevent the compile-time
warning messages that resulted from enabling those flags.
- Merged the OS/2 'make' file ('Makefile.os2') into the Unix 'make'
file ('Makefile'). These files were almost identical and did not
merit separate files.
Added support for the DOS+DJGPP environment to this same file.
Use these commands:
Unix/Linux: make
OS/2: make OS=OS2
DOS+DJGPP: make OS=DJGPP
- Added a (commented-out) '# PACK = gzip' option in the Unix 'make'
file for those who don't have the 'compress' utility.
- Modified the existing 'man' target in the Unix 'make' file
('Makefile') to generate the content of the 'pcal' 'man' page in
HTML, PostScript, and raw text formats.
Before a new release of 'pcal', the 'pcal' maintainer should run
'make man' to generate these help files.
These files should also be placed on the 'pcal' website, since the
main page provides links to these files.
- Removed Control-L ('^L', page eject) characters from C and
PostScript source code. Who puts that in source files?!?
- Remove obsolete, unused targets and definitions (used to compress
and 'uuencode' the source) from Unix and OS/2 'Makefile' files.
- Changed 'find_sym()' routine to 'find_sym_name()' to be distinct
from new 'find_sym_val()' routine in code searches.
- Removed extraneous files from previous distribution ('Makefile~'
and 'pcal' [pre-built DOS executable binary file]). If anyone
really needs a pre-built 'pcal.exe' DOS executable file, it can
always be provided separately on the project webpage.
- Change sense of and provide proper comment for 'SEARCH_PCAL_DIR'
flag setting in Unix and OS/2 'make' files.
- Provide comments in the 'Makefile' for the '-DEPS' option,
describing what it does and why it's useful.
- Removed executable permission from various text files:
moon98 Readme writefil.c Pcal.hlp
In general, fixed up the permissions on several files. For
example, some makefiles had 'rw' permission and others had just 'r'
permission!
- Changed the misleading name of array 'holidays[]' to
'predef_events[]' to reflect the fact that this is a list of
'predefined events', which are often, but not necessarily, holiday
events. For example, this includes the new 'Friday the 13th'
events, which, like every other event in this array, are not
treated as a 'holiday' event unless the user specifies a '*' after
the date portion of the event specification in the 'pcal' options
file.
- Converted the 'Makefile.DOS' file from Unix-style line-endings to
DOS-style.
Tweaked the same file to successfully compile under MS-DOS using
the Borland C++ v5.0 compiler.
Credits:
The original calendar PostScript was Copyright (c) 1987 by Patrick Wood
and Pipeline Associates, Inc. with permission to modify and
redistribute.
The following people contributed to Pcal v4.8.0:
EPS images, 'paper size' option,
new paper sizes, HTML UI update,
various other fixes: Bill Marr
"Friday the 13th" events: Don Laursen
Swedish language support: Joel Fredrikson
Ukrainian language support: Volodymyr M. Lisivka
Portuguese language support: Pedro Zorzenon Neto
Estonian, Russian, Lithuanian, and
Latvian language support: Neeme Praks
Enhanced 'define' capability: unknown (requested by
Louis Taber)
French example calendar: Valéry Bruniaux
DOS/DJGPP build support: Thiago F.G. Albuquerque
Detection of security holes: Danny Lungstrom
For a list of all known contributors to date, see the 'Authors' section
of the 'man' page.
Bill Marr (marr99@users.sourceforge.net)
15 Dec 2004
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.7.1
This is a new release of "Pcal", the PostScript calendar program. It has
minor changes to the 4.7 version: the -q flag that allows the printing of
a yearplanner and an additional Finnish languages support with the -a flag.
The -q flag gives prints out as one column per month resulting in table
that gives a quicker overview over several months and which can be used
as a yearplanner. As a yearplanner obviously has less space for text, only
the first character of the weekday and the first 5 characters of each calendar
entry are printed. Holidays are marked red but the text of the calendar
entry is not printed. The yearplanner gives output at the moment only in
HTML and therefore has effect only when used the -H flag.
To print a half-yearplanner of the first six months:
pcal -H -q 1 2003 6 > yearplanner_I_2003.html
The Finnish language is switched on with "-a fi".
For more general information see the readme-file of version 4.7 below.
Stefan Fronzek (stefan@fronzek.akshor.com), January 15 2003
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.7
This is a new release of "Pcal", the PostScript calendar program. The major
new features are the "-H" flag for generating output in HTML table form,
expansion of "%y" in the "include" filename into the last two digits of
every applicable year in "year all" mode, and the addition of build-time
support for A4 size paper.
Major changes:
1) Of interest to Pcal hackers and installers:
. Automatically looking for the calendar file in the directory where
the Pcal executable lives (Un*x only) is not a Good Thing when there
is already another executable named 'calendar' in the same directory.
This feature is now optional and may be disabled by #define'ing
SEARCH_PCAL_DIR as 0 in pcaldefs.h (or in the Makefile).
. The obsolete PRT() and FPR() macros have been scrapped and replaced
with simple calls to printf() and fprintf().
. The installer can specify different default output file names for
PostScript and HTML output (cf. pcaldefs.h) on those systems (VMS,
Amiga) where output is automatically directed to a file.
. In case anyone still uses moon files, moon96 and moon97 have been
deleted and moon98 added. There are no plans to support moon99.
. Support for OS/2 (new Makefile.os2, revised pcallang.h) has been
added.
. Cleaned up most gcc warnings in "-Wall" mode. This effort revealed
one long-unnoticed bug (see below).
. Realigned the page so that the top of the calendar boxes is now the
Y origin (instead of 35); the origin had not previously corresponded
to any physical feature on the page. Note that this changes the
default value for the little-used -Y flag from -120 to -85.
. Revised Makefile for use in cross-build environment: PCALINIT_CC
defines the host compiler for building pcalinit; CC defines the
cross-compiler for building pcal itself. For native builds (i.e.,
host == target), these are the same.
. Dropped the "EPSF" designator in the initial PostScript comment
since the output is not truly EPS. The special "%%" comments used
by some previewers (e.g., ghostview) are still generated when
built with -DEPS.
. Added support for A4 size paper at build time; see below.
2) New command-line options:
. Pcal now supports the -H flag to generate calendars in HTML table
format. Most of the other flags are overridden or ignored in HTML
mode (moons, note text, Julian dates, small calendars, date
color/style, scaling/transformation, font selection, left/right
footstrings), but one is overloaded in an appropriate manner: the
string specified by the -C flag (PostScript center footstring) is
used as the page title and as a centered page heading.
Other HTML formatting details - minimum lines per box, color and
format of holidays, etc. - can be configured at build time (see the
various Makefiles and pcaldefs.h), but not on the command line.
The latter is theoretically possible, but would require either a)
using up the remaining single-letter flags (all six of them), b)
supporting multiple-letter flags (as per many of the GNU utilities),
or c) overloading even more of the existing flags - none of which is
particularly appealing.
As of the 6/19/98 release, the "-w" flag in conjunction with "-H"
generates HTML whole-year calendars in a multicolumn format similar
to the PostScript equivalents. "-l" and "-p" may be used to specify
landscape or portrait mode, respectively. Pcal normally prints only
five weeks per row unless at least one month in the row requires six;
to print six weeks all the time, build with -DCONSISTENT_SPACING .
. Pcal now supports a numeric (0-6) argument for the -F (first day of
week) flag, thus allowing this to be specified independently of
selected language.
3) New date file functionality:
. Pcal attempts to be somewhat smart about converting simple HTML
tags (`<b>', '<i>', etc. to PostScript bold/italic fonts, and
` ' etc. to ASCII) when generating non-HTML output from a
date file containing these tags.
. In "year all" mode, the "include xxx%y" directive expands to include
a file corresponding to every applicable year (e.g., if the calendar
spans 1997, 1998, and 1999, "include xxx%y" will include xxx97, xxx98,
and xxx99 in that order) instead of just the initial year.
4) Other new functionality:
. Pcal predefines the symbol `v4_7'; this allows the user to ifdef out
v4.7-specific constructs from date files that might also be used
by older versions of Pcal. If "-H" is specified, Pcal also
predefines the symbol `html'; this allows the user to ifdef out
HTML code (e.g. links, font size/color changes, etc.) that is
undesirable in PostScript output.
. On systems where output is normally written to a file, the -o flag
without an argument redirects it to stdout.
. Pcal may optionally be built to generate output for A4 size (545x842)
paper by adding -DA4PAPER to the COPTS line in the Makefile and
rebuilding. There is a block of code in writefil.c that forces the
printer to select the appropriate paper tray in environments where
multiple trays are available; it is, however, known to confuse some
previewers and may be #ifdef'd out if desired (look for "#if 1").
5) Bug fixes:
. I have received reports of a Y2K-related problem on some Un*x systems:
when no year is specified on the command line, the year is calculated
as 100 instead of 2000. I can't reproduce this problem myself, but
incorporated the suggested fix anyway - see pcal.c and pcalutil.c.
. Revised pcallang.h to parse the F_HELP, F_USAGE, and F_VERSION flags
in the preliminary command line pass (P_CMD0) instead of in the first
"real" command line pass (P_CMD1), generating the appropriate message
and exiting without attempting to parse any numeric arguments. This
fixes an obscure bug where "pcal -v 99999" generates a "year out of
range" error instead of the version stamp.
. Fixed a long-standing bug where "note/1" text would overwrite the
small calendar for the next month if the "-k" flag was specified and
the month began on Sunday. See note_box() in pcalutil.c.
. Minor tweakage for compatibility with C++ compilers: ensure that
"C" prototypes are visible wherever necessary (cf. protos.h); change
"template" (C++ reserved word) to "templt" (cf. moonphas.c).
. Fixed a long-standing bug where the final month and year were
miscalculated when spanning year boundaries in whole-year mode.
Credits:
The original calendar PostScript was Copyright (c) 1987 by Patrick Wood and
Pipeline Associates, Inc. with permission to modify and redistribute.
The following people contributed to Pcal v4.7:
C and HTML code: Andrew Rogers
OS/2 support: Alexander Mai
For a list of all known contributors to date, see the Orig.ReadMe file and
topline comments in pcal.c.
Future updates of Pcal v4.7 will be available at the following URL:
http://www.geocities.com/SunsetStrip/Palms/5555/PS/pcal_4_7_tar_Z.txt
Andrew W. Rogers (andrew.rogers@east.sun.com)
09 February 2000
PS: Here's something handy - an alphabetical list of the Pcal options (v4.7)
and their meanings: (04 Dec 2004 Note: This has been moved to the section
corresponding to the current release and updated accordingly.)
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.6
This is a new release of "Pcal", the PostScript calendar program. The major
new features are:
a) the "-a" flag to select a language other than English;
b) the "-T" flag (and \f* escape sequences) to select bold or italic
typefaces in date/note box text;
c) the "year all" directive to wildcard date file entries against
all applicable years;
d) the distribution includes .html and .cgi files for setting up a
Pcal server using Netscape (maybe others; I haven't tried them)
under Un*x;
e) the date box height for single-month portrait-mode calendars
has been expanded from 80 points to 117;
f) the distribution includes moon phase files for 1997 and 1998
g) two new keywords, "nearest_before" and "nearest_after", are
supported.
h) the default century has been changed from 1900 to the current
century.
All are described in detail below.
Major changes:
1) Of interest to Pcal hackers and installers:
. The following new files have been added to the distribution:
days.h day names in multiple languages (see -a below)
months.h month names in multiple languages
calendar.gk calendar with Greek holidays (in Greek)
calendar.uk calendar with British holidays
fonttest_e test Esperanto font mapping (see -a below)
cvt7to8.c To avoid mailer problems, days.h, months.h,
cvt8to7.c and calendar.gk are distributed in 7-bit
format (8-bit characters are represented as
octal escape sequences). cvt7to8.c converts
these files to true 8-bit format to
facilitate editing by users with 8-bit
editors; cvt8to7.c converts them back to
7-bit format for mailing.
The distribution also includes the "ReadMe" files from several
earlier releases.
. moon94 and moon95 have been replaced with moon97 and moon98.
. My [AWR] site finally got a color printer, and after playing with it
for a while I decided I prefer the appearance of black outlines
(dates when -O flag is specified) to color outlines; if you agree,
define the symbol OUTLINE_BLACK in the COPTS line of your Makefile.
. The Un*x Makefile supports selecting the default language (see
-a description below).
. The Un*x Makefile has two new targets: "compress" to create a
compressed 'tar' file (suitable for installation in a public ftp
directory, WWW page, etc.) and "uuencode" to create a uuencoded
version thereof.
2) New command-line options:
. Pcal now supports the -a <language> flag to generate calendars
in the following languages:
de German
en English [default]
eo Esperanto
es Spanish
fr French
gr Greek
it Italian
In order to display diacritical marks, languages other than English
require that the fonts be remapped (Esperanto uses a stripped-down
version of ISO 8859-3; the others use "Latin1"). If no remapping
is specified, \fIpcal\fP selects a remapping appropriate to the
selected language; note that the Greek language also requires an
ELOT-928 font (available from Angelo Haritsis, ah@doc.ic.ac.uk).
If Esperanto is selected, Pcal converts [cghjsuCGHJSU][xX^] and
[uU]~ to the corresponding accented character; e.g. "jxauxdo"
"j^au~do", or any equivalent form will print as "j-circumflex a
u-breve d o".
Day and month names in the date file may be expressed in either
the default language specified at compile-time or the language
selected on the command line.
Pcal predefines the symbol "lang_XX" where XX is the two-character
abbreviation for the current language.
. Pcal now supports the -T [B|I|R] flag to select the typeface (Bold,
Italic, or Roman) for printing date/note text (see below). This flag
may be specified multiple times within the date file (via "opt") to
reset the font style on the fly - for example, to print all holidays
in Bold. (Also see "'troff'-like escape sequences" below.)
3) New date file functionality:
. Pcal now supports the "year all" (or "year *") directive to address
a long-standing Pcal deficiency: the requirement that recurring dates
appear in the date file once for each year. While "year all" is in
effect, pcal will wildcard each date specification (and note box
entry) in the date file into a date entry for each applicable year,
as determined by the starting month/year and number of months.
"Year all" is disabled by a date of the form "mm/dd/yy" or a "year
yy" directive.
. Pcal now supports 'troff'-like escape sequences to change the style
of the font used for printing the text: \fB = Bold; \fI = Italic;
\fR = Roman; \fP = previous font. (Since there is no consistent
means of converting a generic font name to its bold or Italic
equivalent, these are simulated through overstrikes and 'makefont'
respectively.) Pcal also supports their HTML equivalents: <B> =
Bold; <I> = Italic; </B> or </I> = previous font (lower case is
also accepted).
Each of these escape sequences causes a word break, so the effective
granularity is word-level, not character-level. Maybe some day...
The font style is reset to Roman following each line break.
. Pcal now supports three Orthodox Easter related dates: "GEaster",
"Gstgeorge", "Gmarcus".
. Pcal now supports the "nearest_before" and "nearest_after" keywords
to specify how pcal is to disambiguate between two dates that are
equally near; e.g., "nonworkday nearest_before [Wed.] 9/25/96" refers
to Sunday, 9/22 and "nonworkday nearest_after 9/25/96" refers to
Saturday, 9/28. (Note that in the absence of any such ambiguity,
"nearest" takes precedence over "before" or "after": "nonworkday
nearest_before 9/26/96" refers to Saturday, 9/28.)
4) Other new functionality:
. Pcal predefines the symbol v4_6; this allows the user to ifdef out
v4.6-specific constructs from date files that might also be used
by older versions of Pcal.
. Pcal compresses the date font text as necessary to prevent overflow
of extremely long words into the next box.
. The distribution now includes pcal.html (HTML form to generate
single-month calendars), pcalw.html (HTML form to generate whole-year
calendars) and pcal.cgi (common /bin/sh script to parse the options
selected on either of the HTML forms and pass them to pcal). (You
will need to tweak site-specific paths in all of them.)
. The date box height for single-month portrait-mode calendars has
been expanded from 80 points to 117. If you prefer the original
date box proportions (basically a scaled-down landscape-mode
calendar), compile with -DORIG_BOX_HEIGHT.
. The default century for two-digit years has been changed from 1900
to the current century. This presumes standard Un*x behavior: that
the "tm_year" field in the "tm" struct (<time.h>) represents the
current year minus 1900, not the current year itself; if this is not
the case on your system, change the TM_YEAR definition (pcaldefs.h)
accordingly.
5) Bug fixes:
. Fixed a long-standing (but not previously reported) bug in readfile.c
which caused Pcal to crash upon an "undef <sym>" in the date file.
. Depending on the underlying hardware, a bit pattern of all zeroes
may not necessarily be a null (or even a valid) pointer; pointers
previously assumed initialized by a calloc() call are now initialized
explicitly to NULL.
. The Un*x "calendar" utility interprets asterisks as wildcards;
consequently, v4.6 does not propagate asterisks from the date file
to the -c output (note also that holidays with no associated text
will not be printed). To retain them (as per v4.5), define the
symbol KEEP_ASTERISKS in the COPTS line of your Makefile.
. Vestiges of a never-implemented experiment have been deleted from
next_token() in exprpars.c.
. Fixed a long-standing bug where "note/1" text would overwrite the
small calendar for the next month if the "-k" flag was specified and
the month began on Sunday. [merged from v4.7 12/21/97]
Credits:
The original calendar PostScript was Copyright (c) 1987 by Patrick Wood and
Pipeline Associates, Inc. with permission to modify and redistribute.
The following people contributed to Pcal v4.6:
European language and Greek Orthodox calendar
support: Angelo Haritsis
Esperanto support: Andrew Rogers
"nearest_*" suggestion: Brad Knowles
Updated VMS help file: Richard Dyson
Other C and PostScript code: Andrew Rogers
For a list of all known contributors to date, see the Orig.ReadMe file and
topline comments in pcal.c.
Future updates of pcal v4.6 will be available at the following URL:
http://www.geocities.com/SunsetStrip/Palms/5555/pcal.4.6.tar.Z.txt
Andrew W. Rogers
21 December 1997
PS: Here's something handy - an alphabetical list of the Pcal options (v4.6)
and their meanings: (04 Dec 2004 Note: This has been moved to the section
corresponding to the current release and updated accordingly.)
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.5
This is a new release of "Pcal", the PostScript calendar program. (An
intermediate version, 4.4, was not released publicly.)
Major changes:
1) Of interest to Pcal hackers and installers:
. See various comments below regarding options configurable for your
site by tweaking various .h files.
. "noprotos.h" has been scrapped; K&R-style function declarations are
automagically derived from "protos.h" by means of a clever macro,
thus eliminating the need to keep two .h files in sync.
. Two new files have been added to the distribution: "fonttest_r" and
"fontmaps_l" (sample calendar files for testing the Roman8 and Latin1
European language character mappings respectively). This feature is
discussed in greater detail below.
. The v4.0 moon phase algorithm has pretty much obviated the need for a
moon file, but "moon94" and "moon95" have been included nevertheless
(replacing "moon91" and "moon92"). The moon file message has been
dropped from the on-line help and from the comments in the sample
calendar file. The moon file may now contain "opt -A" and "opt -E"
lines, thus allowing American-style moon files (those supplied) to be
used in Europe without modification.
. The Makefiles have been changed: "make clean" leaves pcal intact
while removing object files and other debris created on the fly;
"make clobber" removes pcal as well (as "make clean" used to do).
A new target, "make fresh", has been added to rebuild pcal from
scratch.
. Selected site-specific defaults (DATEFONT, DATE_STYLE, DOUBLE_SIDED,
FIRST_DAY, MAPFONTS, NOTESFONT, TIMEZONE, TITLEFONT, SHADING, EPS)
may now be defined in the Un*x Makefile and its VMS equivalent; see
Makefile and pcaldefs.h for details. (Be a part of history - tweak
the other Makefiles and get your name in the credits for v4.6!)
. The Un*x Makefile has been revised: "make install" now installs
the executable, raw man page, and packed/compressed man page as
per current Un*x conventions. (Thanks to Andrew P. Houghton for
these modifications.)
. The "help" message is automagically piped through a user-specified
filter pointed to by environment variable PAGER (default: "more"),
at least on Un*x systems. If your non-Un*x system supports/simulates
pipes via the "popen(3)" interface - or if you'd prefer to use a
different environment variable or default filter - set/change the
PAGER_ENV and PAGER_DEFAULT macros in pcaldefs.h.
. The "Generated by..." message confuses some PostScript interpreters
(e.g., QMS) and has been converted to an EPS-like comment block.
. Additional EPS-isms (page headers and trailers, courtesy of Andrew
P. Houghton) may be specified by #define'ing EPS as 1 in pcaldefs.h
or in the Makefile.
. Pcal now pre-scales all the required fonts/sizes as part of its
startup code in order to eliminate the overhead of doing so on the
fly (again, thanks to Andrew P. Houghton for this suggestion). The
resulting performance improvement will be most apparent on multi-page
or whole-year calendars.
. The "pcalinit" program now supports #BEGIN <name> .. #END blocks
to split the PostScript boilerplate into sub-arrays; writefil.c is
now smart enought to generate only the PostScript code required
for any given calendar (e.g., if moons are not requested, the moon
generation boilerplate will not be generated). Additionally,
pcalinit propagates PostScript comments delimited by "%%" to the
output file (stripping the first '%').
. It has come to my attention that at least one older compiler
sign-extends the expression (<anychar> & 0377) when promoting it to
int, resulting in an unwanted negative value. The masking constant
0377 has been redefined as CHAR_MSK in pcaldefs.h (and wherever used
throughout the source) so that it may easily be redefined if
necessary (see the related comments in pcaldefs.h).
. VMS changes (thanks to Richard Dyson): 1) the old "Makefile.VMS" has
been been replaced by "Makefile.MMS", which works with either the
official DEC unbundled product MMS or its public-domain clone MMK;
2) Make_Pcal.com has been replaced by a simpler version generated
directly by MMS.
2) New command-line options:
. Pcal now supports "-z <timezone>", which adjusts the moon phase
calculation by <timezone> hours (where <timezone> is expressed in
hours west of UTC: e.g., Boston = "-z5"). If "-z" is specified -
with or without a value - Pcal will use its internal algorithm for
the moon phase calculation even in the presence of a moon file. The
default for <timezone> is 0 as shipped, but may be overridden at your
site by specifying the appropriate value in TIMEZONE (pcaldefs.h).
(Some thought was given to extracting the value from the "TZ"
environment variable, but that is far from universal even on Un*x,
let alone the other platforms. Maybe next time...)
. Pcal generates PostScript code to disable duplex mode (double-sided
output) on printers which support this.
. Pcal also supports -#<n>, which directs Pcal to print <n> copies of
each output page. (Most printer spoolers support this in one form or
another, but at some sites - including mine [AWR] - multiple copies of
PostScript files are each preceded by a separate banner page, which
could be wasteful if you're making, say, 75 copies of your company's
holiday calendar.) This may appear in the datefile if '#' is escaped
by '\' (see below).
. The flags responsible for setting day colors have been expanded and
revised: -b and -g now accept "holiday" (or "hol") to set the color
for holidays; -G and -O have been expanded to accept all of the -b
and -g flags. (For backward compatibility with v4.3, -G and -O alone
work more or less as they used to, changing all non-black days to
outline-gray or outline; cf. change_color() in pcal.c.) Thus, the
user can now specify
-O -Ghol
to print weekends as outline, holidays in outline-gray, and (by
default) other days in black.
The "weekday", "workday", and related keywords now use "logical
black" - the predominant day color - to define weekdays. The user
can thus specify
-Gall -Osat -Osun
and "weekday" will refer to Monday through Friday, even though none
of the dates are actually printed in black. Related issue: If not
explicitly specified otherwise, holidays will print in the least-
frequently used color of those selected, or in a contrasting color
if only one color is used; in the above case, holidays will print as
outlines.
Pcal also accepts ranges of weekdays, which may wrap around the end
of the week:
-Gfri-sun
prints Friday, Saturday, and Sunday as outline-gray.
. The "-s" flag now allows the user to specify a set of red/green/blue
values for the dates and fill boxes. If a single value is specified,
it is taken to be a gray scale value (as before); if three colon-
separated values are specified, they are taken to be red:green:blue
respectively; for example,
-s1.0:0.0:0.0
directs pcal to print "gray" dates in red. Outline dates will
appear in the specified color; "outline-gray" dates will appear
in the specified color with a black outline. The fill boxes
are probably useless in any but the lightest colors, but for
consistency's sake I decided to support r:g:b values for them
too. (Thanks to Denis Girou for the idea and sample code.)
. The "-r" flag has been added. This flag takes a single argument
which is the name of a standard 8-bit character set mapping for
printing the diacritical marks common to European languages; at
present, this argument may be "roman8" or "latin1" (abbreviated to
the first character if desired) to specify the Roman8 or ISO Latin1
mappings respectively. The default is no mapping; this may be
overridden by defining MAPFONTS as ROMAN8 or LATIN1 in the Makefile.
Note that this flag may not be changed on the fly; the final value
specified will be in effect.
Since the date font is usually used only for printing numbers, it
is not remapped; if any of the secondary fonts are redefined as
"datefont", define MAP_DATEFONT as 1 (cf. pcaldefs.h).
New files: "fonttest_r" and "fontmaps_l" are sample calendar files
for testing the Roman8 and Latin1 character mappings respectively.
3) New date file functionality:
. Pcal now handles dates of the form "second Thursday after 12/1".
Note that the ordinal must be positive; while it could be argued that
"last Thursday before 12/1" is synonymous with "first Thursday before
12/1", what does "last Thursday after 12/1 mean?"
. Pcal now supports predefined holidays; at present, it understands
"Christmas", "Thanksgiving", "Good_Friday", and "Easter" (cf.
pcallang.h). So the date file may contain lines like:
Easter* Easter Sunday
Wed before 6th Sun before Easter Ash Wednesday
day after Thanksgiving* holiday
(Algorithms and/or source code to determine the date of other movable
holidays - e.g., the Jewish calendar, Chinese New Year, solstices,
etc. - would be welcome!)
. '#' is no longer treated as start-of-comment if escaped by '\'.
. Pcal now accepts two additional European date formats: "dd. mm." and
and "dd. mon".
4) Other new functionality:
. The user may now override the default font size used in printing the
dates, note text, and month/year title (single-month calendars only);
for example, "-dCourier/32" sets the date font to 32-point Courier.
The font and size may be overridden independently: "-[dnt]<font>"
overrides only the font name, while "-[dnt]/<size>" overrides only
the size.
The PostScript code responsible for positioning dates, text, etc.
now does so using actual font sizes, not hard-coded constants.
. Calculating the color in which to print each date has been moved
from pcalinit.ps to writefil.c, allowing the PostScript code to
perform a simple array lookup rather than a weekday/holiday
calculation.
. All of the font size initialization has been moved from pcalinit.ps
to pcaldefs.h and writefil.c.
. The grid border is drawn using "closepath" to ensure that the lines
meet properly in the corners (yes, this was visible when using a
high-resolution printer with repro-grade paper); additionally, the
grid lines have been increased in width for the small and medium
calendars (to help ensure uniform line width as physically printed).
. The note box heading and weekday names are now printed in the same
font as the title and footers; it makes more sense to print all the
heading text in the same font. Prefer the old way? Just change
WEEKDAYFONT in pcaldefs.h, where the initialization has been moved.
. The font sizes used in printing the medium (whole-year) calendars
can't be overridden by the user, but they have been enlarged yet
again for legibility: title = 64, weekdays = 30, dates = 56, footers
= 14.
. Empty text associated with a date or note entry is propagated to the
calendar as a blank line; this is useful for grouping related lines
together. If you prefer to ignore such lines (as before), define
KEEP_NULL_LINES (pcaldefs.h) as 0.
. The "help" message is automagically piped through "more" on Un*x
systems (see section 1 above).
. The "include?" preprocessing directive has been added; if the
specified file cannot be opened, pcal will silently continue instead
of terminating with an error.
. The earliest valid year has been moved back from 1900 to 1753 (the
first full year of the Gregorian calendar in England and her
colonies).
. The distribution includes "pscalendar", the original shell script/
PostScript boilerplate (by Patrick Wood, King Ables, and Tim Tessin)
that would eventually become Pcal. This is provided primarily as a
historical curiosity, but it is indeed interesting to reflect on how
a 300-line shell script eventually turned into over 10,000 lines of
C and PostScript source.
5) Bug fixes:
. Pcal now handles date specifications of the form "Friday nearest
12/25"; previously, the "nearest" keyword only worked in conjunction
with wildcard weekdays. (This fix has been issued previously as a
patch to v4.3.)
. PostScript routine "holidaytext" has been revised to calculate the
right margin more accurately, avoiding the occasional overflow into
the next box. (In fact, all of the margins have been parameterized,
as were some hard-coded font sizes in "notetext".)
Credits:
The original calendar PostScript was Copyright (c) 1987 by Patrick Wood and
Pipeline Associates, Inc. with permission to modify and redistribute.
The following people contributed to Pcal v4.4 and v4.5:
Overall coordinator: Joe Brownlee
VMS support: Richard Dyson
"-z" support: Steve Grandi
Color date support and testing: Denis Girou
Un*x makefile revision, EPS assistance and
testing, font prescaling: Andrew Houghton
Internationalization assistance: Denis Girou (France)
Robert Joop (Germany)
Other C and PostScript code: Andrew Rogers
For a list of all known contributors to date, see the Orig.ReadMe file and
topline comments in pcal.c.
Andrew W. Rogers
15 November 1994
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.3
This is a new release of "Pcal", the PostScript calendar program. (An earlier
release, 4.2, was not distributed publicly.)
Major changes:
1) Of interest to Pcal hackers, installers, and power users :-) :
. The promised comments about X_OK in pcalutil.c are now actually there.
. Pcal now generates debugging information (see -Z flag below).
2) New command-line options:
. The "-c" flag has been added; this directs Pcal to generate a date
file suitable for input to the Un*x "calendar" utility (instead of
a PostScript file). This file may also be used as input for
subsequent runs of Pcal, but be forewarned that "opt" lines,
preprocessing directives, comments, etc. will be lost. (Idea
courtesy of Bruce Mohler.)
. The "-k" and "-K" flags have been added. The former moves the two
small calendars to the first two boxes (upper-left corner) while
the latter splits them so the previous month is in the first box
and the next month is in the last. Should there be a conflict
with a date, the body of the calendar is moved down one row. (Why
"-[kK]"? Well, "k" sort of sounds like "calendar", and anyway all
the letters that made any more sense were taken.)
. The "-N" flag has been added; this allows the user to override the
default "Notes" header in the notes box. If set to "", Pcal will
not print a header in the notes box.
. The "-u" flag has been added; this prints the version information
and parameter usage message to stdout and terminates normally.
. The "-s" flag has been added; this allows the user to override the
default values for date and/or fill box shading. For example,
-s 0.45/0.98
sets the date shading to 0.45 (white = 1, black = 0) and the fill box
shading to 0.98; this looks good on the whole-year calendars. The
date and fill box shading values may be changed independently; e.g.
"-s 0.45" or "-s /0.98".
. The "-S" flag has been added; this suppresses generation of the
small calendars in the lower right corner, thus freeing two more
boxes for notes (cf. "note/<number>" below).
. The "-Z" flag has been added to print debugging information of interest
primarily to Pcal hackers. This flag is a "hidden" flag; it does not
appear on the man page or as part of the usage message. At present,
the following options are supported:
-ZD print dates and text as read from date file
-ZF print date file search paths
-ZM print moon phases and identify quarters
-ZO print option flags and where set
-ZP print "preprocessor" debug info
-ZT print dates and text as written to output file
-Z turn off all debugging info
The subflags may be combined: e.g., "-ZDF" is equivalent to "-ZD -ZF".
All of the aforementioned debugging information is written to stderr.
(This brings the grand total up to 41 flags; -[aiqrzHPQTVW] are still
unused.)
3) New date file functionality:
. The file name in the "include" directive may contain the string "%y",
which will be replaced by the last two digits of the current year.
. Wildcards "new_moon", "first_quarter", "full_moon", and "last_quarter"
(plus appropriate synonyms) are now accepted in the date file.
. If the "-w" flag has been specified (in PCAL_OPTS, on the command
line, or in an "opt" line), Pcal automatically defines the symbol
"whole_year". This allows the user to specify different "gray"
character styles and densities, alternate foot strings, etc.,
depending on whether s/he is generating a single month or a full year:
ifdef whole_year
opt -s 0.45/0.98 # improve contrast in whole-year mode
endif
. The keyword "nearest" has been added, allowing constructs such as
"workday nearest every 10th". (Thanks to Andy Fyfe for the idea
and code.) In this example, Pcal would look first at the 10th,
then at the 11th, 9th, 12th, 8th, etc. until a workday is found.
(If you would prefer to disambiguate "nearest" in favor of the
earlier date, see the comments by "NEAREST_INCR" in pcaldefs.h.)
. The preprocessor now accepts "if" as a synonym for "ifdef".
. The preprocessor now accepts "elif" as per most recent flavors of
cpp; "elif A" is true if A is defined. Multiple "elif" clauses
are allowed; as in cpp, at most one "if{{n}def}", "elif", or "else"
clause will be processed per block.
. The user may place "Notes" text in any empty box: Pcal now supports
"note/<n>", where <n> is a positive or negative integer. If <n>
is positive, Pcal counts forward from the first empty box; if
negative, backward from the last. Default is -1 (last empty box:
as before, on the bottom row adjacent to the small calendars
unless -S is specified). (Thanks to Geoff Kuenning for the idea.)
4) Other new functionality:
. A new message, "no match for wildcard", has been added.
. The date sizes for the small and medium calendars have been enlarged
for legibility.
. If Pcal can't find the moon file in the date file's directory, it
looks in the directory where the Pcal executable lives. This allows
all users to access the same moon file; in fact, they need not even
know of its existence.
. The "%u" and "%w" format specifiers have been added. These behave
much like "%U" and "%W" except that they treat the week containing
January 1 (instead of the first full week) as week 01, as done by
some companies.
. The %{[+-]<n>}[DWMY] format specifiers have been added. These do
not print anything per se, but instead adjust the working date by
[+-]<n> days (D), weeks (W), months (M), or years (Y); subsequent
format specifiers reference the adjusted date. %D or %M alone
reset the original date.
Since the above format specifiers do not print anything, expand_fmt()
and print_word() were revised further to avoid generating null words.
. The "moon92" file has been supplied.
. The user may now override the default notes font size as well as
the font name:
pcal -n Helvetica/8
sets the font to 8-point Helvetica. (This is the easy one. User
override of the other font sizes may appear later.)
5) Bug fixes:
. The algorithm for finding the date file has been changed slightly:
pcal searches the current directory before PCAL_DIR for a user-
defined date file. More importantly, the man page has been
rewritten to accurately describe the search algorithm; the
documentation had never been correct.
. Pcal no longer requires a space between -[LCRN] and the following
quoted string in an "opt" line; loadwords() has been made smart enough
to split the flag and the string into separate words.
. Pcal has been made much smarter about escape sequences (octal or
hex formats) and now handles them on the command line in addition
to "opt" lines in the date file.
. MIN_ORD_LEN has been expanded from 3 to 4 in order to distinguish
"every" from "even".
. is_quarter() has been revised to eliminate the occasional duplicate
(1/92) or missing (12/92) quarter moon in -m mode.
Credits:
The original calendar PostScript was Copyright (c) 1987 by Patrick Wood
and Pipeline Associates, Inc. with permission to modify and redistribute.
Many others have worked on it since; see the Orig.ReadMe file and topline
comments in pcal.c.
The following people contributed to Pcal v4.2 and v4.3:
Overall coordinator: Joe Brownlee
"nearest" keyword: Andy Fyfe
"note/n" suggestion: Geoff Kuenning
VMS support, moon phase algorithm: Richard Dyson
"-c" suggestion, new SYNOPSIS for man page: Bruce Mohler
Other C and PostScript code: Andrew Rogers
Andrew W. Rogers
08 December 1991
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
"Pcal" Version 4.1
This is an intermediate release of "Pcal", the PostScript calendar making
program.
Major changes:
1) Of interest to Pcal hackers and installers:
. The Un*x flavor of Pcal is now considerably smarter about finding
the date file, using the PATH environment variable to identify
the directory where the executable lives. (This is so system-
dependent that it exists only for Un*x; in fact, it may require
some tweaking for your particular system. See the comments in
pcalutil.c regarding X_OK.)
2) New command-line options:
. The "-v" option has been added to print version information without
the entire usage message.
. The "-G" option has been added to print "gray" dates as filled
outlines (thanks to Richard Dyson for the idea).
3) New date file functionality:
. Pcal now supports format specifiers (derived mostly from strftime())
which allow the user to substitute the current month, day, weekday,
year, etc. into a text or foot string. For further information,
refer to the manual page and/or the comments in "pcal.c".
4) Other new functionality:
. The default moon phase algorithm has been replaced with an
astronomer-quality version; moon file ".moonXX" will continue
to be supported for now.
5) Portability:
. Some VMS-specific files have been updated. Also, a TeX style sheet
is now included in the distribution [this has since been dropped
since whoever wrote it was no longer around to keep it in sync
with the man page - any volunteers?].
Credit where credit is due:
The following people contributed to Pcal v4.1:
Overall coordinator, troff manual page: Joe Brownlee
VMS/TeX support, moon phase algorithm: Richard Dyson
Other C and PostScript code: Andrew Rogers
Although they probably wouldn't recognize the current version, countless
others worked on Pcal long before any of us ever heard of it; see the
Orig.ReadMe file and topline comments in pcal.c.
Andrew W. Rogers
20 August 1991
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
Original 'ReadMe' file from "Pcal"
"Pcal" is a program to print PostScript calendars for any month and year.
By default, it looks for a file in the home directory named "calendar"
for entries with leading dates matching dates on the calendar, and prints
any following text under the appropriate day.
The program may be a little System V flavored (getopt, time routines)
but should be easily portable to other vintages of UNIX.
Pcal is the combined effort of several people, most notably Patrick Wood
of Pipeline Associates, Inc. for the original PostScript code and Bill
Vogel of AT&T for the calendar file mechanism. My part was simple
translation to a "C" program, the addition of a couple options and a more
generalized date searching routine (oh yes, and a manual page :-).
The original calendar PostScript was Copyright (c) 1987 by Patrick Wood
and Pipeline Associates, Inc. with permission to modify and redistribute.
Please retain this README file with the package.
Ken Keirnan
Pacific Bell
San Ramon, CA.
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
Download Latest Version
pcal-4.11.0.tgz (324.4 kB)
