.TH REM2PS 1 "@RELEASE_DATE@" "User Commands" "VERSION @VERSION@"
.UC 4
.SH NAME
rem2ps \- draw a PostScript calendar from Remind output
.SH SYNOPSIS
.B rem2ps [\fIoptions\fR]
.SH DESCRIPTION
\fBRem2ps\fR reads the standard input, which should be the results of
running \fBRemind\fR with the \fB\-p\fR or \fB\-pp\fR option.  It
emits PostScript code (which draws a calendar) to the standard output.
.PP
See the section "Rem2PS Input Format" for details about the \fB\-p\fR
data.  This may be useful if you wish to create other \fBRemind\fR
back-ends.
.PP
Note that \fBRem2PS\fR does not handle UTF-8 input.  If you need to
render characters outside the ASCII character set, see
\fBrem2pdf\fR instead.

.SH OPTIONS
.TP
.B \-v
Be more verbose.  This causes \fBRem2ps\fR to print progress messages
to the standard error stream.  Normally, it is silent.
.TP
.B \-p file
Include the contents of \fIfile\fR in the PostScript prologue.  This
allows you to define procedures, variables etc. which can be used
by the \fBPS\fR and \fBPSFILE\fR reminders.  You should not
include any document structuring comments in your prologue.
.TP
.B \-l
Produce the calendar in landscape mode rather than the default
portrait mode.
.TP
.B \-x
When printing the calendar, place the day numbers in the top-left of each
day's box.  If this option is omitted, the day numbers appear in the
top-right.
.TP
\fB\-c\fR[\fIn\fR]
If \fIn\fR is omitted, disables the small calendars for next and previous
months which are normally generated.  If \fIn\fR is supplied, it can range
from 0 to 3, with the following meanings:
.RS
.TP
.B 0
Disable small calendars
.TP
.B 1
Place the small calendars at the bottom-right if there is room; otherwise,
place them at the top-left.
.TP
.B 2
Place the small calendars at the top-left if there is room; otherwise,
place them at the bottom-right.
.TP
.B 3
Place the previous month's small calendar at the top-left and the next
month's at the bottom-right if there is room; otherwise, follow \fIn\fR=1.
A moment's thought reveals that an option which splits the calendars if
there is room and otherwise follows \fIn\fR=2 yields the same results as
\fIn\fR=3.
.RE
.TP
.B \-i
Use ISO 8859-1 standard encoding for the PostScript fonts.  If you do
not use this option, the default encoding is used.  If you use this option,
you probably also need to convert Remind's output (typically UTF-8)
to ISO-8859-1 using \fBiconv\fR(1).
.TP
.B \-e
Make the calendar fill the entire page.  By default, the calendar is
slightly smaller than the page.  This allows days with many reminders
to "expand" as needed.  However, if you don't have days which expand,
you can use this option to make all of the boxes slightly bigger.  
One caveat: If you do use the \fB\-e\fR option and one day has many
reminders, the calendar may expand off the page, losing some information.
Experiment!
.TP
.B \-m media
Set the page size.  If you use the \-m option, you must specify the
media type, which can be one of the
following.  (Sizes are approximate.)
.RS
.TP
Letter
8.5 x 11 in.
.TP
Legal
8.5 x 14 in.
.TP
Ledger
11 x 17 in.
.TP
Statement
5.5 x 8.5 in.
.TP
Executive
7.5 x 10 in.
.TP
A3
29.7 x 42 cm.
.TP
A4
21 x 29.7 cm.
.TP
A5
14.8 x 21 cm.
.TP
B4
25.7 x 36.4 cm.
.TP
B5
18.3 x 25.7 cm.
.TP
Folio
8.5 x 13 in.
.TP
Quarto
8.5 x 10.8 in.
.TP
10x14
10 x 14 in.
.TP
\fIX\fRx\fIY\fRin
\fIX\fR by \fIY\fR inches, where \fIX\fR and \fIY\fR can be floating-point
numbers.
.TP
\fIX\fRx\fIY\fRcm
\fIX\fR by \fIY\fR centimetres, where \fIX\fR and \fIY\fR can be floating-point
numbers.

.PP
Type "rem2ps \-m help" for a list of available media.  Note that the media
type (and all \fBRem2ps\fR options) are case-sensitive.  If you don't use
the \fB\-m\fR option, the media defaults to a compiled-in default - this
is usually Letter for North America and A4 for Europe.  The "\-m help"
option will display the compiled-in default.
.RE
.TP
\fB\-f\fR[\fBtshed\fR] \fIfont\fR
Set the font for the calendar title,
the small calendars, the day-of-week headings, the calendar
entries, and the day numbers, respectively.  \fIFont\fR must be the
name of a valid PostScript font.  The default fonts are equivalent to
specifying:
.RS
.PP
.nf
	\-ftshe Helvetica \-fd Helvetica-BoldOblique
.fi
.PP
In other words, the heading, entry and small-calendar fonts are set
to Helvetica, and the font for the day numbers is set to
Helvetica-BoldOblique.
.RE
.TP
\fB\-s\fR[\fBthed\fR] \fIsize\fR
Set the size (in points) of the text for the the calendar title,
day-of-week headings, the calendar entries, and the day numbers,
respectively.  \fISize\fR must be a decimal number.  The default sizes
are equivalent to specifying:
.RS
.PP
.nf
	\-sthd 14 \-se 8
.fi
.PP
In other words, the heading and day numbers are 14-point fonts, and the
calendar entries are printed in 8-point text.
.RE
.TP
\fB\-b\fR \fIsize\fR
Set the size of the blank white border in each calendar box to \fIsize\fR
points.  The default border size is 6 points, or 1/12 in.
.TP
\fB\-t\fR \fIsize\fR
Set the thickness of the black calendar grid lines.  The default is 1,
for a line thickness of one point (1/72 in.)
.TP
\fB\-o\fR[\fBlrtb\fR] \fIsize\fR
Set the left, right, top, and/or bottom margins to \fIsize\fR points.
For this option only, \fIsize\fR must be an integer.  It represents the
margin size in units of 1/72 in.  The default margin sizes are 36, for
half-inch margins.  If you wish to punch holes in the calendar page to insert
it into a binder, you may wish to increase the left margin to one inch.
In that case, you should also decrease the heading font size to 12 points
for good output:
.PP
.nf
	# This gives good results for putting into a binder
	rem2ps \-ol 72 \-sh 12
.fi
.SH USAGE
To use \fBRem2ps\fR, you should pipe the output of \fBRemind\fR with the \fB\-p\fR
option to \fBRem2ps\fR, and then send the result to a printer.  This is most easily
illustrated with examples:
.PP
.nf
	remind \-p12 /dev/null 1 jan 1994 | rem2ps | lpr \-Plaser
.fi
.PP
That example creates a blank calendar for the entire year of 1994, and
sends it the the printer named "laser."
.PP
.nf
	remind \-p ~/.reminders | rem2ps \-l \-sd 18 > cal.ps
.fi
.PP
This reminder creates a calendar for the current month, filling in
entries from the reminder file "~/.reminders."  The calendar is produced
in landscape mode, with a font size of 18 for the day numbers.  The result
is put in the PostScript file "cal.ps."
.PP
.SH VARIABLES AVAILABLE TO USER-SUPPLIED POSTSCRIPT CODE
.PP
The following variables are available to \fBPS\fR and 
\fBPSFILE\fR-type reminders.  (This material is duplicated
in the \fBRemind\fR manual page.)
.TP
LineWidth
The width of the black grid lines making up the calendar.
.TP
Border
The border between the center of the grid lines and the space used to print
calendar entries.  This border is normally blank space.
.TP
BoxWidth and BoxHeight
The width and height of the calendar box, from center-to-center of the
black gridlines.
.TP
InBoxHeight
The height from the center of the bottom black gridline to the top
of the regular calendar entry area.  The space from here to the top
of the box is used only to draw the day number.
.TP
/DayFont, /TitleFont, /EntryFont, /SmallFont and /HeadFont
The fonts used to draw the day numbers, the month and year title,
the calendar entries, the small
calendars, and the day-of-week headings, respectively.
.TP
DaySize, TitleSize, EntrySize and HeadSize
The sizes of the above fonts.  (The size of the small calendar font
is \fInot\fR defined here.)  For example, if you wanted to print
the Hebrew date next to the regular day number in the calendar, use:
.PP
.nf
	REM PS Border BoxHeight Border sub DaySize sub moveto \\
	   /DayFont findfont DaySize scalefont setfont \\
	   ([hebday(today())] [hebmon(today())]) show
.fi
.PP
.RS
Note how /DayFont and DaySize are used.
.RE
.PP
Note that if you supply PostScript code, it is possible to produce invalid
PostScript files.  Always test your PostScript thoroughly with a PostScript
viewer before sending it to the printer.  You should not use any document
structuring comments in your PostScript code.
.PP
In addition, prior to drawing a calendar page, \fBRem2ps\fR emits
the following PostScript code:
.PP
.nf
	save (mon) (yr) PreCal restore
.fi
.PP
where \fImon\fR and \fIyr\fR are the month and year of the calendar
page.  The default \fBPreCal\fR procedure simply pops
the arguments and does nothing.  However, you can define a \fBPreCal\fR
function in your prologue file to do whatever you want - it can draw a
background for the entire calendar, for instance.
.PP
In the context of the \fBPreCal\fR procedure, the following conditions
hold:
.TP
o
The PostScript origin is at the bottom left-hand corner of the page, and
PostScript units of 1/72 inch are in effect.
.TP
o
The variables MinX, MinY, MaxX and MaxY define the bounding box within
which the calendar will be drawn.
.TP
o
The font and font-size variables, as well as Border and LineWidth described
previously, are valid.
.PP
For an example, create a file called "myprolog" whose contents are:
.PP
.nf
		/PreCal {
		 /yr exch def
		 /mon exch def
		 /xsiz1 MaxX MinX sub def
		 /ysiz1 MaxY MinY sub def
		 /xsiz xsiz1 MinX sub MinX sub def
		 /ysiz ysiz1 MinY sub MinY sub def
		 xsiz
		 ysiz
		 lt
		 {/len xsiz 1.41 mul def
		  MinX MinX add ysiz1 xsiz1 sub 2 div MinY add MinY add moveto}
		 {/len ysiz 1.41 mul def
		  xsiz1 ysiz1 sub 2 div MinX add MinX add MinY MinY add moveto}
		 ifelse
		 /Helvetica-Bold findfont 1 scalefont setfont
		 mon stringwidth pop
		 ( ) stringwidth pop add
		 yr stringwidth pop add
		 len exch div /len exch def
		 /Helvetica-Bold findfont len scalefont setfont
		 0.95 setgray
		 45 rotate
		 mon show
		 ( ) show
		 yr show
		} bind def
.fi
.PP
Use that file with the \fBRem2ps\fR \fB\-p\fR option to create calendars
with the year and month in large grey letters in the background of the
calendar.
.PP
.SH REM2PS INPUT FORMAT (-P OPTION)
The \fB\-p\fR option is an older, simpler interchange format used by
\fBRemind\fR to communicate with back-ends.  New back-ends are
encoraged to support the new \fB\-pp\fR format preferably, though they
are encouraged to support the older \fB\-p\fR format as well if the
older format contains enough information for them to work properly.
.PP
\fBRemind \-p\fR sends the following lines to standard output.
The information is designed to be easily parsed by back-end programs:
.TP
.B # rem2ps begin
This line signifies the start of calendar data.  Back-ends can search
for it to verify they are being fed correct information.
.TP
\fImonth_name year num_days first_day monday_first\fR
On this line, \fImonth_name\fR is the name of the month whose calendar
information is about to follow.  \fInum_days\fR is the number of days
in this month.  \fIfirst_day\fR is the weekday of the first day of the
month (0 = Sunday, 1 = Monday, 6 = Saturday.)  And \fImonday_first\fR is
1 if the \fB\-m\fR flag was supplied to \fBRemind\fR, or 0 if it was not.
All this information is supplied so back-ends don't need any date calculation
facilities.

Note that all spaces in \fImonth_name\fR will be replaced with
underscores.  Back-ends should undo this replacement.

.TP
\fIsun mon tue wed thu fri sat\fR
This line consists of
space-separated names of days in whatever language \fBRemind\fR was
compiled for.  This information can be used by back-ends to annotate
calendars, and means they don't have to be created for a specific
language.

Note that all spaces in day names will be replaced with
underscores.  Back-ends should undo this replacement.
.TP
\fInext_mon next_days\fR
The name of the next month and the number of days in it.
.TP
\fIprev_mon prev_days\fR
The name of the previous month and the number of days in it.  The
\fInext_mon\fR and \fIprev_mon\fR lines could be used to generate small
inset calendars for the next and previous months.
.PP
The remaining data consists of calendar entries, in the following format:
.PP
\fIyyyy/mm/dd special tag dur time body\fR
.PP
Here, \fIyyyy\fR is the year, \fImm\fR is the month (01-12) and
\fIdd\fR is the day of the month.  Note that the date components are
always separated by "/" even if the date separator in \fBRemind\fR has
been set to "-".  The consistent use of "/" is designed to ease parsing.
.PP
\fIspecial\fR is a string used
for "out-of-band" communication with back-ends.  If the reminder
is a normal reminder, \fIspecial\fR is "*".  The \fBRem2PS\fR
back-end understands the specials \fBPostScript\fR and \fBPSFile\fR.
Other back-ends may understand other specials.  A back end should
\fIsilently ignore\fR a reminder with a special it doesn't understand.
.PP
\fItag\fR is whatever tag the user provided with the \fBTAG\fR clause,
or "*" if no tag was provided.  If there is more than one \fBTAG\fR clause,
the tags appear in a comma-separated list.  For example, the command
\fBREM TAG foo TAG bar TAG quux\fR would result in \fBfoo,bar,quux\fR
in the \fItag\fR field.
.PP
\fIdur\fR is the \fBDURATION\fR value in minutes, or "*" if no duration
was provided.
.PP
\fItime\fR is the time of the reminder in minutes past midnight, or
"*" if the reminder was not a timed reminder.
.PP
\fIbody\fR is the body of the reminder.
.PP
Future versions of \fBRemind\fR may add additional keys to the JSON
object.  Back-ends \fImust\fR ignore keys they don't recognize.
.PP
After a month's worth of reminders have been emitted, \fBRemind\fR
emits the line:
.PP
\fB# rem2ps end
.PP
However, back-ends should keep reading until EOF in case more data for
subsequent months is forthcoming.
.PP
If you supply the \fB\-l\fR option to \fBremind\fR, then reminders
may be preceded by a line that looks like this:
.PP
\fB# fileinfo \fIlineno filename\fR
.PP
The word \fBfileinfo\fR is literal; \fIlineno\fR and \fIfilename\fR specify
the line number and file name of the file containing the reminder.  Back-ends
that don't care about this information should ignore lines starting with
"#" (except, of course, for the # rem2ps lines.)
.PP
.SH REM2PS PARTIAL JSON INPUT FORMAT (-PP OPTION)
\fBRemind \-pp\fR sends the following lines to standard output.  They
are designed to be easily parsed, but contain much more information
than the old-style \fBremind -p\fR output.  The extra information
contains a representation of the parsed "REM" statement, which could
allow converters to better preserve semantics of a reminder.  For
example, this format passes enough information to allow a back-end to
(in many cases) determine a reminder's recurrence rather than just treating
each reminder as a one-off event.
.PP
The lines emitted by \fBremind \-pp\fR are as follows:
.TP
.B # rem2ps2 begin
This line signifies the start of calendar data.  Back-ends can search
for it to verify they are being fed correct information.  Note the
"2" after "rem2ps", which distinguishes this format from the older \fB\-p\fR
format.
.TP
\fImonth_name year num_days first_day monday_first\fR
Same as the \fB\-p\fR format
.TP
\fIsun mon tue wed thu fri sat\fR
Same as the \fB\-p\fR format
.TP
\fInext_mon next_days\fR
Same as the \fB\-p\fR format
.TP
\fIprev_mon prev_days\fR
Same as the \fB\-p\fR format
.PP
.B CALENDAR ENTRIES
.PP
The remaining data consists of calendar entries expressed as a JSON object
on a single line.  Each such line will begin with "{" and will be a well-formed
JSON object.  The keys that may be present in the JSON object are as
follows:
.TP
.B date \fIYYYY-MM-DD\fR
The \fbdate\fR key will \fIalways\fR be present; it is the trigger date
of the reminder expressed as a string in the format \fIYYYY-MM-DD\fR
.TP
.B filename \fIf\fR
The filename in which the reminder was found.
.TP
.B lineno \fIn\fR
The line number within the file on which the reminder was found.
.TP
.B nonconst_expr 1
If the reminder contained a non-constant expression that had to be evaluated
to determine the trigger date, this key will be present with the value 1.
If this key is present, then it is unsafe for a back-end to rely on
recurrence semantics or even the semantics of any part of the parsed
reminder, as they may have been computed in a way that cannot be expressed
in JSON.
.TP
.B if_depth \fIn\fR
If the reminder is inside one or more IF or ELSE statements, this key
will be present and the value will be the number of nested IFs from
the top-level to the reminder.  Back-ends should be wary of
interpreting recurrence semantics of reminders within an IF or ELSE
block.
.TP
.B passthru \fIspecial\fR
If the reminder was a SPECIAL reminder, the \fBpassthru\fR key will be
present and the value will be the type of SPECIAL (such as SHADE, COLOR,
MOON, etc.)
.TP
.B tags \fIdata\fR
If any TAG clauses are present, the \fBtags\fR key will be present and consist
of a comma-separated list of tags.
.TP
.B time \fIt\fR
If an AT clause was present, this key will contain the time of the AT clause
in minutes after midnight.
.TP
.B tdelta \fIn\fR
If a time delta (+n after an AT clause) was present, this key contains the
delta value in minutes.
.TP
.B trep \fIn\fR
If a time repeat (*n after an AT clause) was present, this key contains the
repeat value in minutes.
.TP
.B eventduration \fIn\fR
If a DURATION clause was present, this key contains the event duration in
minutes.
.TP
.B duration \fIn\fR
If a DURATION clause was present, this key contains today's duration in
minutes.  See the \fBremind(1)\fR man page, "MULTI-DAY EVENTS", for a
discussion of duration vs. event duration.
.TP
.B eventstart \fIdt\fR
If an AT clause was present, this key contains the event start time in
the format \fIYYYY-MM-DDTHH:MM\fR.
.TP
.B back \fIn\fR
If the reminder contained a "back" clause (\-n or \-\-n), this key
contains the back value.  If the "back" value was \-n, the value will
be positive; if it was \-\-n, the value will be negative.
.TP
.B delta \fIn\fR
If the reminder contained a "delta" clause (\+n or \+\+n), this key
contains the delta value.  If the "delta" value was \+n, the value will
be positive; if it was \+\+n, the value will be negative.
.TP
.B rep \fIn\fR
If the reminder contained a "repeat" clause (*n), this key contains
the repeat value.
.TP
.B skip \fItype\fR
If the reminder contained a SKIP, BEFORE or AFTER keyword, then this
key will contain that keyword.
.TP
.B localomit \fIarray\fR
If the reminder contains a local OMIT keyword, this key will be present.
Its value will be an array of English day names that are OMITted.
.TP
.B wd \fIarray\fR
If the reminder contains one or more weekdays, this key will be present.
Its value will be an array of English day names that are present.
.TP
.B d \fIn\fR
If a day-of-month is present in the reminder specification, this key
will be present and its value will be the day number.
.TP
.B m \fIn\fR
If a month is present in the reminder specification, this key
will be present and its value will be the month number.
.TP
.B y \fIn\fR
If a year is present in the reminder specification, this key
will be present and its value will be the year.
.TP
.B until \fIYYYY-MM-DD\fR
If the reminder contains an UNTIL or THROUGH clause, this key
will be present.  Its value will be a string of the form YYYY-MM-DD.
.TP
.B once 1
If the reminder contains a ONCE keyword, this key will be present
with a value of 1.
.TP
.B scanfrom \fIYYYY-MM-DD\fR
If the reminder contains a SCANFROM keyword, this key will be present
and its value will be a string of the form YYYY-MM-DD.
.TP
.B from \fIYYYY-MM-DD\fR
If the reminder contains a FROM keyword, this key will be present
and its value will be a string of the form YYYY-MM-DD.
.TP
.B priority \fIn\fR
The priority of the reminder.  Always present; if no PRIORITY keyword
is specified, then a reminder has a default priority of 5000.
.TP
.B r \fIn\fR
For a SHADE or COLOR special, the red color component.
.TP
.B g \fIn\fR
For a SHADE or COLOR special, the green color component.
.TP
.B b \fIn\fR
For a SHADE or COLOR special, the blue color component.
.TP
.B body \fIbody\fR
The body of the reminder to issue.  Always present.
.TP
.B calendar_body \fIbody\fR
The text appropriate to include in a calendar.  Only present if the
original body contains %"...%" sequences and the "q" modifier was used
with Remind's "-pp..." flag.
.TP
.B plain_body \fIbody\fR
The "plain" body of the reminder with any %"...%" sequences removed.
If your back-end is designed to draw a calendar, then it should
use the \fBcalendar_body\fR if present.  If not, then it
should use the \fBplain_body\fR if present, and if not, then it
should fall back on the \fBbody\fR.
.TP
.B rawbody \fIraw\fR
The "raw" body of the reminder, before any expression-pasting or
substitution-sequence processing.  If the raw body would be the same
as the processed body, then this key is not present.
.PP
After a month's worth of reminders have been emitted, \fBRemind\fR
emits the line:
.PP
\fB# rem2ps2 end
.PP
However, back-ends should keep reading until EOF in case more data for
subsequent months is forthcoming.
.PP

.SH REM2PS PURE JSON INPUT FORMAT (-PPP OPTION)
\fBRemind \-ppp\fR emits \fIpure JSON\fR output.  The format is
as follows:
.PP
\fBRemind\fR outputs a JSON array.  Each element of the array is a
\fImonth descriptor\fR.
.PP
Each month descriptor is a JSON object with the following elements:
.TP
.B monthname \fIname\fR
The name of the month.
.TP
.B year \fIyyyy\fR
The year.
.TP
.B daysinmonnth \fIn\fR
The number of days in the current month.
.TP
.B firstwkday \fIn\fR
The weekday of the first day of the month (0 = Sunday, 1 = Monday, 6 = Saturday).
.TP
.B mondayfirst \fIn\fR
An indicator of whether or not the calendar week should start with
Sunday (n=0) or Monday (n=1).
.TP
.B daynames \fR[\fIdays\fR]
A seven-element array of day names; each element is a string representing
the names of the days from Sunday through Saturday.
.TP
.B prevmonthname \fIname\fR
The name of the previous month.
.TP
.B daysinprevmonth \fIn\fR
The number of days in the previous month.
.TP
.B prevmonthyear \fIyyyy\fR
The year of the previous month.  (The same as \fByear\fR unless the current
month is January.)
.TP
.B nextmonthname \fIname\fR
The name of the following month.
.TP
.B daysinnextmonth \fIn\fR
The number of days in the following month.
.TP
.B nextmonthyear \fIyyyy\fR
The year of the following month.  (The same as \fByear\fR unless the
current month is December.)
.TP
.B entries \fR[\fIarray\fR]
The \fBentries\fR key consists of an array of calendar entries; each
entry is a JSON object that has the same format as described in the
\fBCALENDAR ENTRIES\fR section in the \fB\-PP FORMAT\fR section,
\fIwith the following difference\fR: In \fB\-PP\fR mode, if a reminder
has \fB%"\fR markers, only the text between the markers
is included in the \fBbody\fR element.  In \fB\-PPP\fR mode, the
entire text \fIincluding\fR the \fB%"\fR markers is included and it's up to
the back-end to extract the portion between the markers if that
is desired.


.SH AUTHOR
Rem2PS was written by Dianne Skoll <dianne@skoll.ca>
.SH BUGS
All \fBRem2ps\fR options are case-sensitive, unlike \fBRemind\fR.
Any time you supply
a font name or size, line thickness, or border width, it is treated as a
string and sent straight to the PostScript interpreter.  Thus, if you
supply invalid fonts or sizes, \fBRem2ps\fR will not complain, but the
resulting PostScript output will probably not work.
.PP
You should ensure that the values you supply for margin widths are sensible.
If they are too big for the media size, \fBRem2ps\fR will not complain,
but again, the PostScript output will probably not work.
.SH HOME PAGE
https://dianne.skoll.ca/projects/remind/
.SH SEE ALSO
\fBremind\fR, \fBrem2pdf\fR, \fBrem2html\fR, \fBtkremind\fR.