Document new cal-period methods.

doc/calendar.md

@@ -143,24 +143,48 @@ after the period.
 
     (*current-month* [month])
 
-* ```month``` - valid month structure as specified in the ```month``` module
+* ```month``` - valid month structure as specified in the ```cal-month``` module
 
 Configuration parameter specifying the current month. Defaults to the
 current month derived from the current system time.
 
-    (period-since p)
+
+    (make-cal-period since before [scomment [bcomment]])
+
+* ```since``` - a valid cal-month of the first month of the period
+* ```before``` - a valid cal-month - first after the end of the period
+* ```scomment``` - optional "since" comment
+* ```bcomment``` - optional "before" comment
+
+Creates new cal-period structure with mandatory ```since``` and
+```before``` fields and optional ```scomment``` and ```bcomment```
+fields (these default to ```#f```).
+
+    (cal-period-since p)
 
 * ```p``` - valid period
 
 Returns the ```since``` part of given period.
 
-    (period-before p)
+    (cal-period-before p)
 
-Returns the ```since``` part of given period.
+* ```p``` - valid period
 
 Returns the ```before``` part of given period.
 
-    (period-markers->periods l)
+    (cal-period-scomment p)
+
+* ```p``` - valid period
+
+Returns the comment for the since field.
+
+    (cal-period-bcomment p)
+
+* ```p``` - valid period
+
+Returns the comment for the before field.
+
+    (period-markers->cal-periods l)
 
 * ```l``` - list of sorted (list tag month)
 
@@ -170,7 +194,7 @@ each period is represented by ```(list start-month end-month)```.
 The ```end-month``` may be ```#f``` in which case it is an open-ended
 period which has not ended yet.
 
-    (periods-duration l)
+    (cal-periods-duration l)
 
 * ```l``` - list of periods
 
@@ -178,7 +202,7 @@ Returns the total duration in months of the periods given in the list
 ```l```. Each period is represented as ```(list start-month
 end-month)```.
 
-	(month-in-periods p [m (*current-month*)])
+	(cal-month-in-period? p [m (*current-month*)])
 
 * ```p``` - a periods
 * ```m``` - a valid month - defaults to ```(*current-month*)```
@@ -186,7 +210,7 @@ end-month)```.
 Returns ```#t``` if given month ```m``` lies within the period
 ```p```.
 
-	(month-in-periods? ps [m (*current-month*)])
+	(cal-month-in-periods? ps [m (*current-month*)])
 
 * ```ps``` - a list of periods
 * ```m``` - a valid month - defaults to ```(*current-month*)```
@@ -194,7 +218,7 @@ Returns ```#t``` if given month ```m``` lies within the period
 Returns ```#t``` if given month ```m``` lies within any of the periods
 given in the list of periods ```ps```.
 
-    (periods->string ps)
+    (cal-periods->string ps)
 
 * ```ps``` - a list of periods
 
@@ -204,14 +228,14 @@ periods ```ps```. The periods are represented as
 ```"____-__"```.
 
 
-	(periods-match ps [m (*current-month*)])
+	(cal-periods-match ps [m (*current-month*)])
 
 * ```ps``` - a list of periods
 
 Returns the period from the list of periods ```ps``` the given month
 ```m``` falls into. If no period matches, returns ```#f```.
 
-    (make-period-lookup-table source)
+    (make-cal-period-lookup-table source)
 
 * ```source``` a list of specifications
 
@@ -220,10 +244,20 @@ starts with a month and the rest of the list is value to be stored in
 the lookup table. The resulting lookup table contains periods with the
 last period being open-ended without ending month.
 
-    (lookup-by-period table)
+    (lookup-by-cal-period table)
 
 * ```table``` - period lookup table
 
 Looks up the value(s) as specified by the table created by
 ```make-period-lookup-table``` for current month from parameter
 ```(*current-month*)```.
+
+    (cal-ensure-month v [stop?])
+
+* ```v``` - valid month or day
+* ```stop?``` - if ```#t```, treat as ending month, default ```#f```
+
+If ```v``` is a valid month, returns it unchanged. If it is a day,
+uses ```cal-day->month``` for conversion with given ```stop?``` as
+second argument.
+