[DOC] New doc about Julian/Gregorian by BurdetteLamar · Pull Request #70 · ruby/date

BurdetteLamar · 2022-08-03T20:15:11Z

Adding a new free-standing doc about Julian and Gregorian calendars, also covering the argument start that's used by some methods in Date.

The goal is to push discussion of calendars and start out 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.)

peterzhu2118

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.

BurdetteLamar · 2022-08-04T12:51:56Z

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 start", which I think is irrelevant to most users. (How many applications deal with dates going back centuries?)

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?

peterzhu2118 · 2022-08-04T14:13:34Z

I see, that makes sense. I think it would also make sense to remove that part in the class doc for Date in the this PR so that we don't end up with duplicate documentation.

BurdetteLamar · 2022-08-04T15:07:55Z

I see, that makes sense. I think it would also make sense to remove that part in the class doc for Date in the this PR so that we don't end up with duplicate documentation.

Done.

peterzhu2118

Can you also add the doc directory into the .document file so that it's included when generating RDoc.

peterzhu2118 · 2022-08-04T17:41:31Z

doc/date/calendars.rdoc

+  # 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


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

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?

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.

Very well; I've removed them.

BurdetteLamar · 2022-08-04T19:02:16Z

Can you also add the doc directory into the .document file so that it's included when generating RDoc.

Done.

We also need to add to ruby/tool/sync_default_gems.rb.

.document

peterzhu2118

Looks good!

peterzhu2118 · 2022-08-05T02:22:33Z

I think we should update ruby/tool/sync_default_gems.rb before merging this PR so that it syncs this PR to ruby/ruby.

Co-authored-by: Peter Zhu <peter@peterzhu.ca>

nobu · 2022-08-08T05:26:44Z

doc/date/calendars.rdoc

+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.


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?

nobu · 2022-08-08T05:28:10Z

doc/date/calendars.rdoc

+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).


I think this sentence will need to refine too.

BurdetteLamar · 2022-08-08T10:46:28Z

Thanks, @nobu. I will look into these things.

nobu · 2022-08-08T13:02:48Z

doc/date/calendars.rdoc

+{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


These constants are no longer links.

I noticed that, too. Should RDoc have linked to the constants?

Before this commit, that is ~~inside~~ for class Date, these constants were linked properly.

This seems a bug of RDoc.
This off-page constant also isn't rendered as a link.

Should I link manually, as a stop-gap?

nobu · 2022-08-08T13:05:04Z

@BurdetteLamar I removed obviously wrong descriptions for now. Feel free to improve.

New doc about Julian/Gregorian

540971a

BurdetteLamar requested a review from peterzhu2118 August 3, 2022 20:15

BurdetteLamar added the documentation label Aug 3, 2022

peterzhu2118 reviewed Aug 4, 2022

View reviewed changes

New doc about Julian/Gregorian

4f2b807

BurdetteLamar requested a review from peterzhu2118 August 4, 2022 15:08

peterzhu2118 reviewed Aug 4, 2022

View reviewed changes

New doc about Julian/Gregorian

d8e8ee3

BurdetteLamar requested a review from peterzhu2118 August 4, 2022 19:04

peterzhu2118 reviewed Aug 4, 2022

View reviewed changes

.document Outdated Show resolved Hide resolved

New doc about Julian/Gregorian

45002f7

peterzhu2118 approved these changes Aug 5, 2022

View reviewed changes

Update .document

ae64281

Co-authored-by: Peter Zhu <peter@peterzhu.ca>

BurdetteLamar merged commit 9906677 into ruby:master Aug 5, 2022

nobu reviewed Aug 8, 2022

View reviewed changes

Conversation

BurdetteLamar commented Aug 3, 2022

Uh oh!

peterzhu2118 left a comment

Choose a reason for hiding this comment

Uh oh!

BurdetteLamar commented Aug 4, 2022

Uh oh!

peterzhu2118 commented Aug 4, 2022

Uh oh!

BurdetteLamar commented Aug 4, 2022

Uh oh!

peterzhu2118 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BurdetteLamar commented Aug 4, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

peterzhu2118 left a comment

Choose a reason for hiding this comment

Uh oh!

peterzhu2118 commented Aug 5, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BurdetteLamar commented Aug 8, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nobu Aug 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nobu commented Aug 8, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BurdetteLamar commented Aug 4, 2022 •

edited

Loading

nobu Aug 15, 2022 •

edited

Loading