[m-rev.] for review: improve the documentation of the calendar module

[Julien Fischer]

On Fri, 13 Mar 2026 at 20:05, Julien Fischer <jfischer at opturion.com> wrote:

> > > @@ -138,41 +152,62 @@
> > >
> > >  %---------------------%
> > >
> > > -    % Convert a string of the form "YYYY-MM-DD HH:MM:SS.mmmmmm" to a date.
> > > -    % The microseconds component (.mmmmmm) is optional.
> > > +    % Convert a string of the form "[-]YYYY-MM-DD HH:MM:SS.mmmmmm" to a date.
> > > +    % The year must have at least four digits; years with more than four digits
> > > +    % are accepted. The microseconds component (.mmmmmm) is optional. If
> > > +    % present, it may have between one and six digits.
> > > +    %
> > > +    % Fail if the string does not conform to the above format, or if any
> > > +    % date or time component is outside its valid range.
> >
> > What is the justification for restricting to 4+ digit years?
>
> Good question. The short answer is I don't know.
> I intend to investigate further and lift the restriction if I can't
> find a reason.

Requiring that years have at least four digits in date-time
representations comes
from ISO 8601-1.  Other time-related standards have picked it up. For
example, both RFC 3339 and the XML Schema standard on which this
module was based.

Given the prevalence of the four-digit requirement, I don't think
there is anything
to be gained by doing something different in Mercury here.

Julien.