Methods 'julian-date' and 'modified-julian-date' have incomplete description

[tbrowder]

The methods are only defined for one timezone (UTC-0000) and cannot be converted to local time

There are currently no core methods to convert then to local time, but those routines are available in distribution 'DateTime::Julian'.

Such details are missing from the current descriptions, and this PR attempts to remedy that.

• Addresses doc issue doc for DateTime.julian-date doesn't mention that it silently discards timezone info in the DateTime object #4577
• Addresses doc issue Ensure the docs mention there is no way in Raku core to convert julian-date to local time, so use DateTime::Julian #4575

[arkiuat]

Currently, the example in the doc uses a DateTime that is already set to UT timezone Z, and so can't demonstrate this behavior. It might be helpful if there were an example using a DateTime object with a non-UT timezone, showing that the timezone information is silently disregarded.

The submitted commit 84df054 is a big improvement on what's currently there, but what would be even more helpful is a recommendation to doc-readers advising to code the silent behavior explicitly, by always prefixing .julian-date with .utc (e. g. $dt.utc.julian-date) whenever applying it to DateTime objects for which the timezone status is unknown.

I thought these were two separate issues because I didn't think my issue had anything to do with converting to local time, and didn't see any need to mention non-core modules.

[tbrowder]

My point is one should not normally need a .julian-date for a given timezone. Your method doesn't actually mean much.

Maybe say that in the docs, but be aware [Coke] is very picky about going much afield for examples and such. So an example showing the no-julian-date change would be better in a roast test IMHO.

[lizmat]

Perhaps mention the .utc method, so that: $ raku -e 'for -11..11 {DateTime.new("2025-05-19T17:00:00"~"%+03d".sprintf($_)).utc.julian-date.say}' 2460815.666667 2460815.625 2460815.583333 2460815.541667 2460815.5 2460815.458333 2460815.416667 2460815.375 2460815.333333 2460815.291667 2460815.25 2460815.208333 2460815.166667 2460815.125 2460815.083333 2460815.041667 2460815 2460814.958333 2460814.916667 2460814.875 2460814.833333 2460814.791667 2460814.75 ? Or am I missing something?

…

On 22 May 2025, at 00:27, Tom Browder ***@***.***> wrote: tbrowder left a comment (Raku/doc#4578) My point is one should not normally need a .julian-date for a given timezone. Your method doesn't actually mean much. Maybe say that in the docs, but be aware [Coke] is very picky about going much afield for examples and such. So an example showing the no-julian-date change would be better in a roast test IMHO. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[tbrowder]

I'll do something like that, but I'll shorten it. I'll work on it tomorrow.

[arkiuat]

This latest commit, just specifically at line 272, doesn't seem to be an improvement on the current wording. (The insertions at lines 282 and 298 seem fine). I think the reference to "noon" needs to be dropped.

(Also there's a typo on 273: dgrees s/b degrees.)

The class here is DateTime, not Date, and this makes it sound as if this always returns a number ending in .5

[1] > DateTime.new("2025-05-22T13:00:00Z").julian-date
2460818.041667
[2] > DateTime.new("2025-05-22T14:00:00Z").julian-date
2460818.083333
[3] > DateTime.new("2025-05-22T12:00:00-05:00").utc.julian-date
2460818.208333

Also, don't we want to correctly document the current behavior? The longitudinal aspects aren't implemented in the release being documented.

[tbrowder]

First, I think the current behavior does need to be mentioned, but also mention the caveat that it's misleading a bit. At the same time we are discussing a fix to Raku.

Why don't you submit a complete chunk of text describing exactly how you think the current situation ought to be described.

A new doc issue might be best, with an appropriate title. (And please close this one.)

[arkiuat]

Why don't you submit a complete chunk of text describing exactly how you think the current situation ought to be described.

A new doc issue might be best, with an appropriate title. (And please close this one.)

Here is my proposed change to DateTime.rakudoc. I'll close this doc issue as soon as I'm confident of the appropriate title for the new one, and will include this diff there.

272c272,273
< Returns the L<Julian date|https://en.wikipedia.org/wiki/Julian_day> (JD) for the UTC date and time.
---
> Returns the L<Julian date|https://en.wikipedia.org/wiki/Julian_day> (JD) at zero degrees longitude 
> for the given date and time, silently discarding any timezone information.
273a275
>     say DateTime.new('2021-12-24T12:23:00.43+03:00').julian-date; # OUTPUT: «2459573.0159772␤»
275a278,281
> To preserve such distinctions, explicitly apply .utc before applying .julian-date.
> 
>     say DateTime.new('2021-12-24T12:23:00.43+03:00').utc.julian-date; # OUTPUT: «2459572.8909772␤»
> 
289c295,296
< Returns the L<Modified Julian Date|https://en.wikipedia.org/wiki/Julian_day> (MJD) for the UTC date and time.
---
> Returns the L<Modified Julian Date|https://en.wikipedia.org/wiki/Julian_day> (MJD) for the UTC date and time,
> silently discarding any timezone information.
291a299
>     say DateTime.new('2021-12-24T12:23:00.43+03:00').modified-julian-date; # OUTPUT: «59572.5159772␤»
292a301,304
> To preserve such distinctions, explicitly apply .utc before applying .modified-julian-date.
> 
>     say DateTime.new('2021-12-24T12:23:00.43+03:00').utc.modified-julian-date; # OUTPUT: «59572.3909772␤»
>