"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).

      . 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
07 October 1994


PS: Here's something handy - an alphabetical list of the Pcal options and
their meanings:


------------------------------- clip 'n' save -------------------------------

-A  parse American date	format		-a  <unused>
-B  don't fill unused boxes		-b  print day in black
-C  define center foot string		-c  generate "calendar"	utility	input
-D  define preprocessor	symbol		-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 gray-filled outline	-g  print day in gray
-H  <unused>				-h  generate full help message
-I  re-initialize program defaults	-i  <unused>
-J  print Julian day and days left	-j  print Julian day (day of year)
-K  prev in first box, next in last	-k  prev/next in first two boxes
-L  define left	foot 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 outline		-o  select alternate output file
-P  <unused>				-p  portrait mode
-Q  <unused>				-q  <unused>
-R  define right foot string		-r  remap fonts for 8-bit characters
-S  suppress small calendars		-s  define date/fill box shading
-T  <unused>				-t  select alternate title font
-U  undefine preprocessor symbol	-u  generate parameter usage message
-V  <unused>				-v  generate version ID
-W  <unused>				-w  print whole	year per page
-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

-----------------------------------------------------------------------------


PPS: Here's an admittedly-incomplete list of PostScript font names.  All of
these are supported by the printers (Imagen, HP, QMS) that I [AWR] use; your
mileage may vary:

	AvantGarde-Book			AvantGarde-BookOblique
	AvantGarde-Demi			AvantGarde-DemiOblique
	Bookman-Demi			Bookman-DemiItalic
	Bookman-Light			Bookman-LightItalic
	Courier				Courier-Bold
	Courier-BoldOblique		Courier-Oblique
	Helvetica			Helvetica-Bold
	Helvetica-BoldOblique		Helvetica-Narrow
	Helvetica-Narrow-Bold		Helvetica-Narrow-BoldOblique
	Helvetica-Narrow-Oblique	Helvetica-Oblique
	NewCenturySchlbk-Bold		NewCenturySchlbk-BoldItalic
	NewCenturySchlbk-Italic		NewCenturySchlbk-Roman
	Palatino-Bold			Palatino-BoldItalic
	Palatino-Italic			Palatino-Roman
	Times-Bold			Times-BoldItalic
	Times-Italic			Times-Roman
	ZapfChancery-MediumItalic
