Document language packs.

man/remind.1

@@ -2441,6 +2441,12 @@ order, or 2 if sorting by time in descending order.
 The number of spaces by which all lines (except the first) of an
 \fBMSF\fR-type reminder should be indented.  The default is 0.
 .TP
+.B $SysInclude (read-only, STRING type)
+A directory path containing standard reminder scripts.  Currently,
+Remind ships with some standard holiday files and language packs.
+The value of \fB$SysInclude\fR is likely to be something like
+"/usr/share/remind" or "/usr/local/share/remind"
+.TP
 .B $T (read-only, DATE type)
 Exactly equivalent to \fBtrigdate()\fR.  (See BUILT-IN FUNCTIONS.)
 .TP
@@ -4692,7 +4698,7 @@ error messages.  For an example of this, define the following:
 	fset msgprefix(x) x/0
 .fi
 .PP
-.SH SUPPORT FOR OTHER LANGUAGES
+.SH COMPILE-TIME SUPPORT FOR OTHER LANGUAGES
 .PP
 Your version of \fBRemind\fR may have been compiled to support a
 language other than English.  This support may or may not be complete -
@@ -4705,10 +4711,14 @@ selected language rather than for English.
 Note that a non-English version of \fBRemind\fR will accept \fIonly\fR
 English names of weekdays and months in a reminder script.
 .PP
-If there is no support for your particular language, you can set
-\fBRemind\fR system variables so that calendars are printed using
-your language's day and month names.  The system variables that you
-can set are:
+.SH RUN-TIME SUPPORT FOR OTHER LANGUAGES
+.PP
+\fBRemind\fR has run-time support for other languages, and it is
+expected that compile-time support will be deprecated in favour of
+run-time support.
+.PP
+A number of system variables let you translate various phrases
+to other languages.  These system variables are:
 .PP
 .TP
 .B $Monday, $Tuesday, $Wednesday, $Thursday, $Friday, $Saturday
@@ -4718,16 +4728,113 @@ day's name in your language.  Strings must be valid UTF-8 strings.
 .B $January, $February, $March, $April, $May, $June, $July, $August, $September, $October, $November, $December
 Set each of these system variables to a string representing the corresponding
 month's name in your language.  Strings must be valid UTF-8 strings.
+.TP
+.B $Ago, $Am, $And, $At, $Hour, $Is, $Minute, $Now, $On, $Pm, $Was
+Set each of these system variables to the translation of the corresponding
+English word into your language.  Note that \fB$Am\fR and \fB$Pm\fR should
+be the translations of "AM" and "PM" (morning and afternoon time indicators)
+respectively.
+.TP
+.B $Hplu, $Mplu
+Set these to the suffix to add to the word for "hour" and "minute" to
+make them plural.  In English, both would be set to "s".
+.TP
+.B $Fromnow
+Set this to the translation of the English phrase "from now"
 .PP
-Note that if you set the day- or month-name system variables, they
-should be set in a section of your script that always is evaluated.
-If you set them inside an \fBIF\fR statement, for example, results
-are unpredictable.
+Note that if you set any of the language-related system variables,
+they should be set in a section of your script that always is
+evaluated.  If you set them inside an \fBIF\fR statement, for example,
+results are unpredictable.
 .PP
 Note also that the \fBRem2PS\fR back-end does not support the full
 range of UTF-8 characters.  The \fBTkRemind\fR, \fBrem2html\fR and
 \fBrem2pdf\fR back-ends all do support the full UTF-8 range.
-
+.PP
+.SH RUN-TIME MODIFICATION OF THE SUBSTITUTION FILTER
+.PP
+The system variables mentioned in the previous section are not typically
+sufficient to properly translate Remind's output to another language.
+Some languages have complicated rules for AM vs PM times and others have
+complex rules for making words plural.  \fBRemind\fR therefore allows
+you to define a number of functions that modify the behavior of
+the substitution filter at run-time.  The functions are:
+.PP
+.TP
+.B subst_ampm(h)
+This function is passed a single integer, namely an hour from 0 to 23.
+It should return a string that indicates "AM" or "PM" or even finer
+gradations in some languages.
+.TP
+.B subst_ordinal(d)
+This function is passed a single integer, namely a day of the month from
+1 to 31.  It should return a string that is suffixed to the day number to
+turn it into an ordinal number.  In English, for example, the function
+might return "st", "nd", "rd" or "th", depending on \fId\fR.
+.TP
+.B subst_N(alt, date, time)
+This is actually a \fIfamily\fR of functions, where \fIN\fR is a letter
+or number.  This function \fIcompletely overrides\fR the substitution
+sequence "%X".  The three arguments are an integer \fIalt\fR which,
+if non-zero, indicates that the alternate-mode substitution sequence
+"%*X" was encountered; \fIdate\fR which is the trigger date of the
+reminder and \fItime\fR which is the trigger time.
+.TP
+.B subst_Nx(alt, date, time)
+Again, this is a \fIfamily\fR of functions.  It is similar to the
+\fBsubst_x\fR family except it is only called if \fIdate\fR is two or
+more days away from \fItoday()\fR.  This is useful if you don't want to
+override the "today" or "tomorrow" output for most substitution sequences.
+.PP
+Here's an example of how you might customize your substitution filter.
+Suppose you want to change the "%b" sequence to substitute "the day
+after tomorrow" for an event two days from now.  You could do this:
+.nf
+    FSET subst_bx(a,d,t) iif(d==today()+2, "the day after tomorrow", \
+                             "in " + (d-today()) + " days' time")
+    REM [today()+3] ++3 MSG Event 1 is %b%
+    REM [today()+2] ++3 MSG Event 2 is %b%
+    REM [today()+1] ++3 MSG Event 3 is %b%
+    REM [today()]   ++3 MSG Event 4 is %b%
+.fi
+.PP
+The output of this script is:
+.nf
+    Event 1 is in 3 days' time
+    Event 2 is the day after tomorrow
+    Event 3 is tomorrow
+    Event 4 is today
+.fi
+.PP
+Note how Event 2's wording was changed from the normal "in 2 days'
+time", and note also that the "tomorrow" and "today" events used the
+normal substitution---\fBsubst_bx\fR is not called for trigger days of
+today or tomorrow.
+.PP
+.SH LANGUAGE PACKS
+.PP
+\fBRemind\fR ships with a number of language packs, which are simply reminder
+scripts located in [$SysInclude]/lang.  The currently-shipping
+language packs are:
+.PP
+da.rem (Danish), de.rem (German), es.rem (Spanish), fr.rem (French),
+is.rem (Icelandic), it.rem (Italian), nl.rem (Dutch), no.rem (Norwegian),
+pl.rem (Polish), pt.rem (Portuguese) and ro.rem (Romanian).
+.PP
+To use a language pack (in this example, de.rem), simply place this at
+the top of your reminders file:
+.nf
+    INCLUDE [$SysInclude]/lang/de.rem
+.fi
+.PP
+If you want \fBRemind\fR to try to find the language pack appropriate
+for your locale settings, use:
+.nf
+    INCLUDE [$SysInclude]/lang/auto.rem
+.fi
+.PP
+You are encouraged to study the language packs to see how to translate
+Remind into additional languages.
 .PP
 .SH THE HEBREW CALENDAR
 .PP