-- Documented remind -p format.

-- Documented some new features (SPECIAL).  Still need to do
   TAG and DURATION.

man/rem2ps.1

@@ -1,5 +1,5 @@
-.\" $Id: rem2ps.1,v 1.1 1998-01-15 02:50:18 dfs Exp $
-.TH REM2PS 1 "27 April 1996"
+.\" $Id: rem2ps.1,v 1.2 1998-02-02 02:57:46 dfs Exp $
+.TH REM2PS 1 "1 February 1998"
 .UC4
 .SH NAME
 rem2ps \- draw a PostScript calendar from Remind output
@@ -9,6 +9,11 @@ rem2ps \- draw a PostScript calendar from Remind output
 \fBRem2ps\fR reads the standard input, which should be the results of running
 \fBRemind\fR with the \fB\-p\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.
+
 .SH OPTIONS
 .TP
 .B \-v
@@ -300,6 +305,71 @@ 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
+\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.
+.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.
+.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.
+.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.
+.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
+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
 .SH AUTHOR
 David F. Skoll
 .SH BUGS

man/remind.1

@@ -1,5 +1,5 @@
-.\" $Id: remind.1,v 1.1 1998-01-15 02:50:18 dfs Exp $
-.TH REMIND 1 "31 July 1997"
+.\" $Id: remind.1,v 1.2 1998-02-02 02:57:47 dfs Exp $
+.TH REMIND 1 "1 February 1998"
 .UC 4
 .SH NAME
 remind \- a sophisticated reminder service
@@ -61,6 +61,8 @@ The \fB\-p\fR option is very similar to the \fB\-s\fR option, except
 that the output contains additional information for use by the
 \fBrem2ps\fR program, which creates a PostScript calendar.  For this
 option, \fIn\fR cannot start with "+"; it must specify a number of months.
+The format of the \fB\-p\fR output is described in the \fBrem2ps(1)\fR
+man page.
 .TP
 .B \-m
 The \fB\-m\fR option causes the \fB\-c\fR or \fB\-p\fR options to produce
@@ -268,8 +270,10 @@ Its syntax is:
 [\fBWARN\fR \fIwarn_function\fR]
 [\fBUNTIL\fR \fIexpiry_date\fR]
 [\fBSCANFROM\fR \fIscan_date\fR]
-\fBMSG\fR | \fBMSF\fR | \fBRUN\fR | \fBCAL\fR | \fBSATISFY\fR |
-\fBPS\fR | \fBPSFILE\fR
+[\fBDURATION\fR \fIduration\fR]
+[\fBTAG\fR \fItag\fR]
+<\fBMSG\fR | \fBMSF\fR | \fBRUN\fR | \fBCAL\fR | \fBSATISFY\fR |
+\fBSPECIAL\fR \fIspecial\fR | \fBPS\fR | \fBPSFILE\fR>
 .I body
 .RE
 .PP
@@ -283,7 +287,7 @@ such as \fBOMIT\fR or \fBRUN\fR.  The portion of the \fBREM\fR command
 before the \fBMSG\fR, \fBMSF\fR \fBRUN\fR, \fBCAL\fR or \fBSATISFY\fR clause
 is called a \fItrigger\fR.
 .PP
-.B "MSG, MSF, RUN, CAL, PS and PSFILE"
+.B "MSG, MSF, RUN, CAL, SPECIAL, PS and PSFILE"
 .PP
 These keywords denote the \fItype\fR
 of the reminder.  (\fBSATISFY\fR is more complicated and will be explained
@@ -324,6 +328,15 @@ programmer.  The \fBPS\fR and \fBPSFILE\fR reminders are ignored unless
 \fBRemind\fR is run with the \fB\-p\fR option.  See the section
 "More about PostScript" for more details.
 .PP
+A \fBSPECIAL\fR-type reminder is used to pass "out-of-band" information
+from \fBRemind\fR to a calendar-producing back-end.  It should be followed
+by a word indicating the type of special data being passed.  The type
+of a special reminder depends on the back-end.  For the \fBRem2PS\fR
+back-end, \fBSPECIAL PostScript\fR is equivalent to a \fBPS\fR-type
+reminder, and \fBSPECIAL PSFile\fR is equivalent to a \fBPSFILE\fR-type
+reminder.  The body of a \fBSPECIAL\fR reminder is obviously dependent
+upon the back-end.
+.PP
 .B DATE SPECIFICATIONS
 .PP
 A \fIdate_spec\fR consists of zero to four parts.