Not Documented: DateTime's two julian-date methods silently discard timezone data

[arkiuat]

Problem or new feature

The documentation for DateTime's julian-date and modified-julian-date methods do not warn that both these methods silently ignore timezone information.

Suggestions

I propose the following two changes in DateTime.rakudoc, first in the "method julian-date" section:

===
FROM ==============================================================================================
===
Returns the L<Julian date|https://en.wikipedia.org/wiki/Julian_day> (JD) for the UTC date and time.

    say DateTime.new('2021-12-24T12:23:00.43Z').julian-date; # OUTPUT: «2459573.0159772␤»
---
TO ----------------------------------------------------------------------------------------------
---
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.

    say DateTime.new('2021-12-24T12:23:00.43+03:00').julian-date; # OUTPUT: «2459573.0159772␤»
    say DateTime.new('2021-12-24T12:23:00.43Z').julian-date; # OUTPUT: «2459573.0159772␤»

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␤»
=================================================================================================

And then in the "method modified-julian-date" section:

===
FROM ==============================================================================================
===
Returns the L<Modified Julian Date|https://en.wikipedia.org/wiki/Julian_day> (MJD) for the UTC date and time.

    say DateTime.new('2021-12-24T12:23:00.43Z').modified-julian-date; # OUTPUT: «59572.5159772␤»
---
TO ----------------------------------------------------------------------------------------------
---
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.

    say DateTime.new('2021-12-24T12:23:00.43Z').modified-julian-date; # OUTPUT: «59572.5159772␤»
    say DateTime.new('2021-12-24T12:23:00.43+03:00').modified-julian-date; # OUTPUT: «59572.5159772␤»

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␤»
=================================================================================================

[arkiuat]

Closing issue 4577 per tbrowder's suggestion

[tbrowder]

That does show how to distinguish the two, but it bothers me that it furthers misunderstanding of use of the Julian Date. If a user knows that, he should have filed an issue. If he does not, we're leading him farther into the weeds.

I would like to see some words about our current shortcoming in Raku and note that it will be improved soon.

[arkiuat]

I agree, and thanks for confirming that. How about the following two additional changes?

In the "method julian-date" section:

===
FROM ==============================================================================================
===
the fraction of a day from that epoch to that instant.

Available as of the 2021.04 Rakudo compiler release.
---
TO ----------------------------------------------------------------------------------------------
---
the fraction of a day from that epoch to that instant.
Strictly speaking, the JD is defined only for a specific longitude, and the current implementation
always assumes zero longitude: this shortcoming should be improved soon.

Available as of the 2021.04 Rakudo compiler release.
=================================================================================================

And then in the "method modified-julian-date" section:

===
FROM ==============================================================================================
===
transformations between civil and astronomical time systems.

Available as of the 2021.04 Rakudo compiler release.
---
TO ----------------------------------------------------------------------------------------------
---
transformations between civil and astronomical time systems.
Strictly speaking, the MJD is defined only for a specific longitude, and the current implementation
always assumes zero longitude: this shortcoming should be improved soon.

Available as of the 2021.04 Rakudo compiler release.
=================================================================================================

[tbrowder]

Ok, I'm going to start a new PR using some of your language plus some other language based on comments from the #raku-dev channel.

[arkiuat]

resolved in https://github.com/Raku/doc/pull/4651