[DOC] New doc about Julian/Gregorian #70
Conversation
There was a problem hiding this comment.
I'm in favor of this change but why not directly change the documentation in the Date class rather than creating a separate document for this change? Many parts of the calendars.rdoc file already exists in the documentation for the Date class so this duplicates the existing documentation.
Sorry I was not more clear about what I'm trying to do. The problem I see is that in reading the overview of the Date class, the reader comes to the large and complicated section "Argument I think this material should not be in the overview, but should instead be in a separate doc that gets link to from each relevant method doc. I intend to remove that section from the overview, and to change the links to point to the section in the new doc. Does it make better sense to go ahead with those additional changes in this PR? |
|
I see, that makes sense. I think it would also make sense to remove that part in the class doc for |
Done. |
doc/date/calendars.rdoc
Outdated
| # Julian date, incremented to a Gregorian date. | ||
| d0 = Date.new(1582, 1, 1, Date::ITALY) # => #<Date: 1582-01-01> | ||
| d0.julian? # => true | ||
| d1 = d0.next_year # => #<Date: 1583-01-01 > | ||
| d1.gregorian? # => true | ||
|
|
||
| # Gregorian date, decremented to a Julian date. | ||
| d0 = Date.new(1583, 1, 1, Date::ITALY) # => #<Date: 1583-01-01)> | ||
| d0.gregorian? # => true | ||
| d1 = d0.prev_year # => #<Date: 1582-01-01> | ||
| d1.julian? # => true |
There was a problem hiding this comment.
I don't see how this example highlights any implications when incrementing or decrementing dates, it seems to work exactly as expected. I think it only affects dates around the switchover date. For example:
d = Date.new(1582, 10, 15) # => #<Date: 1582-10-15>
d.prev_day # => #<Date: 1582-10-04>
Date.new(1582, 10, 14) # => Date::Error: invalid dateThere was a problem hiding this comment.
I don't see how this example highlights any implications when incrementing or decrementing dates, it seems to work exactly as expected. I think it only affects dates around the switchover date. For example:
d = Date.new(1582, 10, 15) # => #<Date: 1582-10-15> d.prev_day # => #<Date: 1582-10-04> Date.new(1582, 10, 14) # => Date::Error: invalid date
Works exactly as you and I expect. Naive user may be surprised that in/de/crementing from one calendar may lead to the other.
Also, I have not illustrated the error you cite (trying to create into the jump); should we include that?
There was a problem hiding this comment.
Right, but the documentation above it says
For a Date object created with Date::JULIAN or Date::GREGORIAN,
there are implications when the date is incremented or decremented
I see no implications in the examples that follow. The call to Date#next_year returns a date with the same month and day in the following year and the call to Date#prev_year returns a date with the same month and day in the previous year. Everything works exactly as expected. So I'm a bit confused as to what the examples are trying to show.
There was a problem hiding this comment.
Very well; I've removed them.
Done. We also need to add to |
|
I think we should update |
Co-authored-by: Peter Zhu <[email protected]>
| may matter to your program if it uses dates in the interval: | ||
|
|
||
| - October 15, 1582. | ||
| - September 14, 1752. | ||
|
|
||
| A date outside that interval (including all dates in modern times) | ||
| is the same in both calendars. | ||
| However, a date _within_ that interval will be different | ||
| in the two calendars. |
There was a problem hiding this comment.
This description is totally wrong.
This "interval" is the duration a date is represented differently across countries.
Gregorian calendar has never match Julian calendar since its creation (except for 3C in proleptic Gregorian calendar).
If the two calendars were match since 16C or 19C, why they needed switch it?
| When your code uses a date in this "gap" interval, | ||
| it will matter whether it considers the switchover date | ||
| to be the earlier date or the later date (or neither). |
There was a problem hiding this comment.
I think this sentence will need to refine too.
|
Thanks, @nobu. I will look into these things. |
| {Julian and Gregorian calendars}[rdoc-ref:calendars.rdoc@Julian+and+Gregorian+Calendars] | ||
| by accepting an optional argument +start+, whose value may be: | ||
|
|
||
| - Date::ITALY (the default): the created date is Julian |
There was a problem hiding this comment.
These constants are no longer links.
There was a problem hiding this comment.
I noticed that, too. Should RDoc have linked to the constants?
There was a problem hiding this comment.
Before this commit, that is inside for class Date, these constants were linked properly.
There was a problem hiding this comment.
This seems a bug of RDoc.
This off-page constant also isn't rendered as a link.
There was a problem hiding this comment.
Should I link manually, as a stop-gap?
|
@BurdetteLamar I removed obviously wrong descriptions for now. Feel free to improve. |
Adding a new free-standing doc about Julian and Gregorian calendars, also covering the argument
startthat's used by some methods inDate.The goal is to push discussion of calendars and
startout of the general discussion, where they are of little interest to many (most?) users. Instead, links would take the reader off-page, when relevant.Also: corrects two errors in
date_core.c. (If this PR is rejected, I'll put up these corrections separately.)