# Copyright (c) 1995-2009 Sullivan Beck. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.

=pod

=head1 NAME

Date::Manip::Problems - problems and bugs

=head1 KNOWN PROBLEMS

The following are not bugs in Date::Manip, but they may give some people
problems.

=over 4

=item Unable to determine Time Zone

Please refer to the Date::Manip::TZ documentation for a discussion
of this problem.

=item Missing date formats

Due to the large number of date formats that Date::Manip CAN process,
people often assume that other formats that they want to use should
work as well, and when they don't, it comes as a surprise.

If this happens, I'm willing to entertain the suggestion that they be
added. I'm a little more hesitant about adding date formats at this
point than in the past due to the ever increasing complexity of the
parsing routines, but I always consider each request, and if the
format isn't too abstract, I often add them.

There is a class of formats that I will not add however.

I have frequently been asked to add formats such as "the 15th of last
month", or "Monday of next week". I will NOT add these date formats to
Date::Manip. Since I have received the request several times, I
decided to include my reasoning here.

Date::Manip can parse pretty much any static date format that I could
think of or find reference to. Dates such as "today", "Jan 12", or
"2001-01-01" are all understood.

These are fairly limited however. Many very common date formats are
best thought of as a date plus a modification. For example,
"yesterday" is actually determined internally as "today" plus a
modification of "- 1 day".  "2nd Sunday in June" is determined as
"June 1" modified to the 2nd Sunday.

As these types of formats were added over time, I quickly realized
that the number of possible date plus modification formats was
huge. The number of combinations has caused the parsing in Date::Manip
to be quite complex, and adding new formats occasionally causes
unexpected conflicts with other formats.

The first time I received a request similar to "the 15th of last
month", I intended to add it, but as I analyzed it to see what changes
needed to be made to support it, I realized that this needed to be
expressed as a date plus TWO modifications. In other words, today
modified to last month modified to the 15th day of the month.

As bad as date plus modification formats are, a date plus TWO
modifications would be exponentially worse. On realizing that, I made
a firm decision that Date::Manip will NOT support this type of format
now, or at any time in the future. Although I apologize for the
inconvenience, I do not intend to change my position on this.

=item Date::Manip is slow

NOTE: This section will be rewritten with version 6.01. Version 6.00
is a complete rewrite with emphasis on getting a version out. 6.01
will take that and do some speed optimization, and at that point, I
will run some benchmarks using Date::Manip and some other Date/Time
modules to be able to address this better.

Date::Manip is probably one of the slower Date/Time modules due to the
fact that it is huge and written entirely in perl.

Some things that will definitely help:

ISO-8601 dates are parsed first and fastest.  Use them whenever possible.

Avoid parsing dates that are referenced against the current time (in 2
days, today at noon, etc.).  These take a lot longer to parse.

Business date calculations are extremely slow.  You should consider
alternatives if possible (i.e. doing the calculation in exact mode and
then multiplying by 5/7).  Who needs a business date more accurate
than "6 to 8 weeks" anyway, right :-)

=item RCS Control

If you try to put Date::Manip under RCS control, you are going to have
problems.  Apparently, RCS replaces strings of the form "$Date...$" with
the current date.  This form occurs all over in Date::Manip.  To prevent the
RCS keyword expansion, checkout files using:

   co -ko

Since very few people will ever have a desire to do this (and I don't
use RCS), I have not worried about it, and I do not intend to try to
workaround this problem.

=item Using functions/methods which are not supported

There have been a handful of incidents of people using a function from
Date::Manip which were not documented in the manual.

Date::Manip consists of a large number of user functions which are
documented in the manual. These are designed to be used by other
programmers, and I will not make any backwards incompatible changes in
them unless there is a very compelling reason to do so, and in that
case, the change will be clearly documented in the
Date::Manip::Changes documentation for this module.

Date::Manip also consists of a large number of functions which are NOT
documented. These are for internal use only.  Please do not use them!
I can (and do) change their use, and even their name, without notice,
and without apology!

As of the most recent versions of Date::Manip, all internal functions
have names that begin with an underscore (_). If you choose to use
them directly, it is quite possible that new versions of Date::Manip
will cause your programs to break due to a change in how those
functions work.

Some of these internal functions even have test scripts, but that
is not a guarantee that they will not change, nor is any support
implied.

Any changes to these internal functions will not be documented, and
will not be regarded by me as a backwards incompatibility. Nor will I
(as was requested in one instance) revert to a previous version of
the internal function.

If you feel that an internal function is of more general use, feel free
to contact me with an argument of why it should be "promoted".  I
welcome suggestions, and a huge number of changes made to Date::Manip
come directly from user suggestions.

=back

=head1 BUGS AND QUESTIONS

If you find a bug in Date::Manip, please send it directly to me (see
the AUTHOR section below).  Alternately, you can submit it on CPAN. This
can be done at the following URL:

   http://rt.cpan.org/Public/Dist/Display.html?Name=Date-Manip

Please do not use other means to report bugs (such as Usenet newsgroups,
or forums for a specific OS or Linux distribution) as it is impossible
for me to keep up with all of them.

When filing a bug report, please include the following information:

=over 4

=item *

The version of Date::Manip you are using.  You can get this by using
the script:

   use Date::Manip;
   print DateManipVersion(),"\n";

or

   use Date::Manip::Date;
   $obj = new Date::Manip::Date;
   print $obj->version(),"\n";

=item *

The output from "perl -V"

=back

If you have a problem using Date::Manip that perhaps isn't a bug
(can't figure out the syntax, etc.), you're in the right place.  Start
by reading the main Date::Manip documentation, and the other documents
that apply to whatever you are trying to do.  If this still doesn't
answer your question, mail me directly.

I would ask that you be reasonably familiar with the documentation
BEFORE you choose to do this. Date::Manip is a hobby, and I simply do
not have time to respond to hundreds of questions which are already
answered in this manual.

=head1 KNOWN BUGS

None known.

=head1 SEE ALSO

Date::Manip        - main module documentation

=head1 LICENSE

This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut
