Re: [boost] Re: reminder about Date/Time formal review

From: William E. Kempf (williamkempf_at_[hidden])
Date: 2002-04-23 16:44:24

----- Original Message -----
From: "Jeff Garland" <jeff_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Tuesday, April 23, 2002 3:26 PM
Subject: RE: [boost] Re: reminder about Date/Time formal review

> > (Trivia related to the above:  Did you know that Sept. 2, 1752 was
followed
> > by Sept. 14, 1752?  Or that George Washington's birthday, which we give
> > today as Feb. 22, 1732 was recorded on that day as Feb. 11, 1731?  Gotta
> > love this date stuff, no?)
>
> It makes your head spin after awhile :-)

Yep.  I've got several other interesting trivia things in this realm.  In
addition to the fun of change over dates we also have the fact that the new
year has been moved around the calendar for political reasons as well.  Mix
all this together and you wind up with a lot of dates that don't "jibe" with
what most people would expect today.

> > 4.  The string conversion and parsing routines should simply be removed.
> > Instead, we should have iostream capabilities for the various date
systems
> > which obey the locale.  This is, after all, a C++ library and not a Java
> > library.
>
> I think this will take some discussion as I think some folks would really
> like to have string conversion routines (I for one).  And while I agree
> we need locale compliant streaming, in my experience this isn't usually
> enough.  That each different parts of the GUI etc want to extract
different
> dates and times using different parts and pieces.  So I would suggest
> we add the streaming and leave the string conversions.

I don't care for this at all.  Note that none of the current C++ types in
the standard provide any sort of string conversions.  They rely on iostreams
for this, and I think that's appropriate.  It provides the most flexibility
and insures a uniform way to obtain string representations.  Providing both
will only confuse new users, and I think you'll find that most of your
experienced users will choose to use the iostream interface (probably
through something like a boost::string_cast()).

> > 5.  I still disagree about the presence of a "universal representation"
and
> > the ability to convert to/from this representation and a particular time
> > system.
>
> See my other mail.  I think we are actually in agreement here.

Then, if GDTL is accepted, can I expect to see this included with the
initial release?

> > 6.  <personal opinion>I don't care for the doxygen documentation.  I
believe
> > in the concept of keeping the documentation in the code, but I think
there
> > are issues with the Doxygen generated documentation that will make it
> > problematic for Boost (such as the size of generated documentation), and
as
> > someone else pointed out most of the technical documentation currently
can
> > only be found in the Doxygen generated documentation.  I think this will
> > cause nothing but trouble for Boost users.</personal opinion>
>
> Fair enough.  Regardless of the extractor I intend to keep the core
> of the code documentation inline so that it can be read by browsers of
> the code.  I have been doing this since way before doxygen was ever
> invented. My thought is to include an 'extender guide' that provides
> examples of how to use the library components to build new date-time
> systems. Of course we still need direct documentation of the components.
> Anyway, I'm committed to making the documentation work better.

The only thing I see wrong with "keeping the core of the code documentation
inline" is that the Boost libraries are static in nature.  You can't expect
users to generate the documentation, and I think it's also unlikely that the
release procedure will be changed to generate the documentation for you.
So, by keeping the code inline you're committing yourself to producing the
static documentation every time the inline documentation is made.  If you
can live with that then great.  I do understand the appeal of keeping the
documentation in the code.

Bill Kempf