Pcal v4.0, part 1 of 5

[joseph.a.brownlee]

Oops, I messed up.  I inadvertently posted a slightly older version of the
ReadMe file with pcal v4.0.  Here is the updated version.  Sorry for the
inconvenience.

(continue now if you don't want to see it)

------------------------------- 8< cut here >8 ---------------------------------
"Pcal" Version 4.0

This is yet another version of "Pcal", the PostScript calendar program.  Since
the changes to program structure and functionality were so extensive, it has
been given a new release number.

Major changes:

    1) Of interest to Pcal hackers, porters, and installers:

      .	You will notice several new files.  Pcal.c was getting so large
	that it was in imminent danger of breaking some mailers;
	consequently it has been split into six .c files and three new
	.h files:

		pcal.c		main, arg parsing, usage message
		pcalutil.c	misc. utility routines
		readfile.c	reading and parsing of date file
		writefil.c	output of PostScript code
		moonphas.c*	phase-of-moon calculations
		exprpars.c*	parse Boolean expressions in "if{n}def"

		pcalglob.h	global variables
		protos.h*	ANSI-style function prototypes
		noprotos.h*	K&R-style function declarations

		* all-new for v4.0

	(Note that encapsulating all of the PostScript output routines into
	a single file - writefil.c - facilitates porting Pcal to other
	typesetting packages, e.g., troff.  Any takers?)

      . All of the routines now have ANSI function prototypes in addition
	to the older K&R-style declarations, selected automagically by a
	macro PROTOS which is defined whenever __STDC__ is present (or which
	may be explicitly defined for compilers which accept prototypes but
	are not fully ANSI-conformant).  Similarly, a macro STDLIB controls
	inclusion of <stdlib.h>, an ANSI standard header which exists on
	some (but not all) non-ANSI systems.

      .	Pcal now runs on the Commodore Amiga and under MS-DOS, thanks to the
	respective efforts of Bill Hogsett and Floyd Miller.

      . All of the calendar calculations - starting day, length, etc. - have
	been moved from the PostScript code to the C code; pcalinit.ps is
	now concerned only with formatting and printing the output.

      .	The title inside the "notes" box has been moved from pcalinit.ps to
	pcallang.h so it may be easily translated to languages other than
	English.

      .	The month/year title and dates in the small calendars have been
	enlarged (from 48 points to 60 and 54, respectively).  The font sizes
	for the small, medium (new), and large calendars are now in arrays
	to facilitate any future changes.

      .	Pcalinit strips trailing comments (and the spaces preceding them) and
	allows <FF> in the input text.  The logic of pcalinit.c has been
	revised for clarity, and the source has been documented.  An optional
	parameter has been added to allow the user to specify the name of
	the string array in the output file.


    2) New command-line options:

      .	The "-w" option has been added to print calendars for a whole year
	on a single page, printing 3 rows by 4 columns in landscape mode and
	4 rows by 3 columns in portrait mode.  This option effectively disables
	the -M|m (moons) and -J|j (Julian dates) flags, and also suppresses
	the text in the calendar boxes.  The numeric parameters also work
	slightly differently:

		yy		print Jan/yy .. Dec/yy
		mm yy		print 12 months starting with mm/yy
		mm yy n		print n months (rounded up to multiple of 12)
					starting with mm/yy
		(default)	print Jan .. Dec of current year

	Note that "-w" in conjunction with "-p" overrides any Y-scale factor
	(default or set with "-y") in order to use the full portrait page.

      .	The "-B" option has been added; this directs Pcal to leave unused
	calendar boxes blank.

      .	The "-O" option has been added; this directs Pcal to print all "gray"
	dates as outlined characters.


    3) New date file functionality:

      .	The Pcal "preprocessor" now accepts Boolean expressions in "if{n}def"
	directives.  These expressions consist of symbol names joined
	by Boolean operators !, &, ^, and | (in order of precedence, high
	to low).  Parentheses may be used to alter the precedence; && and
	|| are accepted as synonyms for & and |.  A symbol name evaluates
	to TRUE if currently defined, FALSE if not; thus, "ifdef A | B | C"
	is TRUE if any of the symbols A, B, and C is defined, and
	"ifdef A & B & C" is true if they all are.

	"ifndef <expr>" is equivalent to "ifdef !( <expr> )".

      .	Pcal supports "odd" and "even" - meaning "alternate, starting with
	first" and "alternate, starting with second" - as ordinals and "year"
	to refer to the entire year as an entity (as opposed to "all", which
	refers to each individual month).  Thus "odd Thursdays in year" expands
	to 1/3/91, 1/17, 1/31, 2/14, 2/28... while "odd Thursdays in all"
	expands to 1/3, 1/17, 1/31, 2/7, 2/21... .

      .	Pcal supports all ordinal numbers (e.g., "100th day of year"),
	including negative ordinals ("-2nd" means "next to last", etc.).
	As before, only "first" through "fifth" may be spelled out.

      .	Pcal now allows C-style escape sequences ('\' followed by a character,
	1-3 octal digits, or 'x' followed by 1-2 hexadecimal digits) in the
	date file.  Escaped whitespace (including <NL>) and the standard
	ANSI character escapes ('\a', '\b', '\f', '\n', '\r', '\t', '\v')
	are all replaced by a single blank.

      .	Pcal now reads phase-of-the-moon information from file .moonXX (where
	XX is the last two digits in the current year) if such a file exists
	in the same directory as the .calendar file.  If no such file exists,
	Pcal calculates the approximate phase for each date (as before).  (The
	file name may vary between systems.)


    4) Other new functionality:

      . If Pcal cannot find the date file in the standard search places
	(PCAL_DIR and HOME), it makes one last attempt to find it in the
	directory where the Pcal executable resides.

      . Pcal now prints the name of the date and moon files (if used) as
	a comment in the PostScript output.


    5) Bug fixes:

      .	"1 << n" has been rewritten as "1L << n" throughout; this caused 
	problems on some machines where "int" is 16 bits.

      .	Fixed loadwords() to correctly handle single- and double-quoted
	strings, including those containing escaped quotes.

      .	In response to popular demand, revised enter_day_info() to silently 
	ignore Feb 29 of common years (this may be disabled by setting
	FEB_29_OK to 0 in pcaldefs.h).

      .	The -f flag works correctly in conjunction with PCAL_DIR.

      .	Pcalinit correctly escapes backslashes and double quotes.



Credit where credit is due:

Pcal 4.0 has been more of a collaborative effort than usual.  The following
people contributed in some way to its final form:

	Overall coordinator, man page, useful ideas:	Joe Brownlee
	VMS support:					Richard Dyson
	Amiga support, prototypes:			Bill Hogsett
	DOS support, executable path search		Floyd Miller
	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.