@@ -15,12 +15,137 @@ \section{\module{calendar} ---
 week to Sunday (6) or to any other weekday.  Parameters that specify
 dates are given as integers.
 
-Most of these functions rely on the \module{datetime} module which
-uses an idealized calendar, the current Gregorian calendar indefinitely
-extended in both directions.  This matches the definition of the
-"proleptic Gregorian" calendar in Dershowitz and Reingold's book
-"Calendrical Calculations", where it's the base calendar for all
-computations.
+Most of these functions and classses rely on the \module{datetime}
+module which uses an idealized calendar, the current Gregorian
+calendar indefinitely extended in both directions.  This matches
+the definition of the "proleptic Gregorian" calendar in Dershowitz
+and Reingold's book "Calendrical Calculations", where it's the
+base calendar for all computations.
+
+\begin{classdesc}{Calendar}{\optional{firstweekday}}
+Creates a \class{Calendar} object. \var{firstweekday} is an integer
+specifying the first day of the week. 0 is Monday, 6 is Sunday.
+
+A \class{Calendar} object provides several method that can
+be used for preparing the calendar data for formatting. This
+class doesn't do any formatting itself. This is the job of
+subclasses.
+\versionadded{2.5}
+
+\begin{methoddesc}{firstweekday}{}
+Return the first day of the week (as specified in the constructor
+or changed via \method{setfirstweekday()}.
+
+\begin{methoddesc}{setfirstweekday}{weekday}
+Set the first day of the week.
+
+\begin{methoddesc}{iterweekdays}{weekday}
+Return an iterator for the week day numbers that will be used
+for one week. The first number from the iterator will be the
+same as the number return by \method{firstweekday()}.
+
+\begin{methoddesc}{itermonthdates}{year, month}
+Return an iterator for the month \var{month} (1-12) in the
+year \var{year}. This iterator will return all days (as
+\class{datetime.date} objects) for the month and all days
+before the start of the month or after the end of the month
+that are required to get a complete week.
+
+\begin{methoddesc}{itermonthdays2}{year, month}
+Return an iterator for the month \var{month} in the year
+\var{year} similar to \method{itermonthdates()}. Days returned
+will be tuple consisting of a day number and a week day
+number.
+
+\begin{methoddesc}{itermonthdays}{year, month}
+Return an iterator for the month \var{month} in the year
+\var{year} similar to \method{itermonthdates()}. Days returned
+will simply be day numbers.
+
+\begin{methoddesc}{monthdatescalendar}{year, month}
+Return a list of the weeks in the month \var{month} of
+the \var{year} as full weeks. Weeks are lists of seven
+\class{datetime.date} objects.
+
+\begin{methoddesc}{monthdays2calendar}{year, month}
+Return a list of the weeks in the month \var{month} of
+the \var{year} as full weeks. Weeks are lists of seven
+tuples of day numbers and weekday numbers.
+
+\begin{methoddesc}{monthdayscalendar}{year, month}
+Return a list of the weeks in the month \var{month} of
+the \var{year} as full weeks. Weeks are lists of seven
+day numbers.
+
+\begin{methoddesc}{yeardatescalendar}{year, month\optional{, width}}
+Return the data for the specified year ready for formatting. The return
+value is a list of month rows. Each month row contains upto \var{width}
+months (defaulting to 3). Each month contains between 4 and 6 weeks and
+each week contains 1-7 days. Days are \class{datetime.date} objects.
+
+\begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}}
+Return the data for the specified year ready for formatting (similar to
+\method{yeardatescalendar()}). Entries in the week lists are tuples of
+day numbers and weekday numbers. Day numbers outside this month are zero.
+
+\begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}}
+Return the data for the specified year ready for formatting (similar to
+\method{yeardatescalendar()}). Entries in the week lists are day numbers.
+Day numbers outside this month are zero.
+
+
+\begin{classdesc}{TextCalendar}{\optional{firstweekday}}
+This class can be used for generating plain text calendars.
+
+\versionadded{2.5}
+
+\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}}
+Returns a month's calendar in a multi-line string. If \var{w} is
+provided, it specifies the width of the date columns, which are
+centered. If \var{l} is given, it specifies the number of lines that
+each week will use. Depends on the first weekday as set by
+\function{setfirstweekday()}.
+
+\begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
+Prints a month's calendar as returned by \method{formatmonth()}.
+
+\begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{, l\optional{, c\optional{, m}}}}}
+Returns a \var{m}-column calendar for an entire year as a multi-line string.
+Optional parameters \var{w}, \var{l}, and \var{c} are for date column
+width, lines per week, and number of spaces between month columns,
+respectively. Depends on the first weekday as set by
+\method{setfirstweekday()}.  The earliest year for which a calendar can
+be generated is platform-dependent.
+
+\begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{, c\optional{, m}}}}}
+Prints the calendar for an entire year as returned by  \method{formatyear()}.
+\end{funcdesc}
+
+
+\begin{classdesc}{HTMLCalendar}{\optional{firstweekday}}
+This class can be used for generating HTML calendars.
+
+\versionadded{2.5}
+
+\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}}
+Returns a month's calendar as an HTML table. If \var{withyear} is
+true the year will be included in the header, otherwise just the
+monthname will be used.
+
+\begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}}
+Returns a year's calendar as an HTML table. \var{width} (defaulting to 3)
+specifies the number of months per row.
+
+\begin{methoddesc}{formatyearpage}{theyear, themonth\optional{, width\optional{, css\optional{, encoding}}}}
+Returns a year's calendar as an complete HTML page. \var{width}
+(defaulting to 3) specifies the number of months per row. \var{css}
+is the name for the cascading style sheet to be used. \constant{None}
+can be passed, if no style sheet should be used. \var{encoding}
+specifies the encoding to be used for the output (defaulting
+the the system default encoding).
+
+
+For simple text calendars this module provides the following functions.
 
 \begin{funcdesc}{setfirstweekday}{weekday}
 Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start
@@ -80,11 +205,8 @@ \section{\module{calendar} ---
 \end{funcdesc}
 
 \begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}}
-Returns a month's calendar in a multi-line string. If \var{w} is
-provided, it specifies the width of the date columns, which are
-centered. If \var{l} is given, it specifies the number of lines that
-each week will use. Depends on the first weekday as set by
-\function{setfirstweekday()}.
+Returns a month's calendar in a multi-line string using the
+\method{formatmonth} of the \class{TextCalendar} class.
 \versionadded{2.0}
 \end{funcdesc}
 
@@ -94,12 +216,8 @@ \section{\module{calendar} ---
 \end{funcdesc}
 
 \begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}}
-Returns a 3-column calendar for an entire year as a multi-line string.
-Optional parameters \var{w}, \var{l}, and \var{c} are for date column
-width, lines per week, and number of spaces between month columns,
-respectively. Depends on the first weekday as set by
-\function{setfirstweekday()}.  The earliest year for which a calendar can
-be generated is platform-dependent.
+Returns a 3-column calendar for an entire year as a multi-line string
+using the \method{formatyear} of the \class{TextCalendar} class.
 \versionadded{2.0}
 \end{funcdesc}