view release on metacpan or  search on metacpan

doc/astronomical-notes.pod  view on Meta::CPAN

-*- encoding: utf-8; indent-tabs-mode:nil -*-

=encoding utf-8

=head1 Document Status

This text is published under the I<Creative Commons> license
CC-BY-ND.

Copyright (c) 2017-2021 Jean Forget. All rights reserved.

I must precise that I am not a professional astronomer. The text
below may contain errors, be aware of this. I will not be held
responsible for any consequences of your reading of this text.
The "NO WARRANTY" paragraphs from the GPL and the Artistic License
apply not only to Perl code, but also to English (and French)
texts.

The text is often (but irregularly) updated on Github. There are
a French version and an English version. Since I am more at ease
discussing astronomical subjects in French, the English version
will lag behind the French one.

This text is an integral part of the module's distribution package.
So you can read it on web pages generated from CPAN
(for example L<https://metacpan.org>).
But it is not used during the module installation process.
So, I guess it will not appear in C<.deb> or C<.rpm> packages.

Although this text  is stored in the  L<Astro::Sunrise> repository, it
also  documents the  L<DateTime::Event::Sunrise> module,  which has  a
very  similar core  (astronomical computations)  and a  different API.
Since both  modules move at different  speeds, it may happen  that the
text you  are reading is  not synchronised with  the L<Astro::Sunrise>
module.

=head1 Why This Text? For Whom?

The main purpose of this text is to explain how the sunrises
and sunsets are computed. These explanations are much too long
to be included into the module's POD section.

=head2 For Whom? For My Teddy Bear

Have you read
L<brian's Guide to Solving Any Perl Problem|http://www252.pair.com/~comdog/brian's_guide.pod>?
While most advices deal with debugging Perl code, a few advices have
a broader scope and apply to any intellectual problem.
One of these advices consists in "talking to the teddy-bear".
And do not pretend to talk while just forming sentences in your
mind. You must really talk in a clear voice in front of your
teddy-bear, with syntactically correct sentences.
Actually, in the present case, the topic is so big that I skipped to the next level and
I prefer writing (on GitHub) for my teddy-bear.

I write this text to tell my teddy-bear which problems I have
encountered while maintaining this module and how I fixed them.
But mainly, I write this to give him a detailed description of the
precise iterative algorithm, because 
L<Paul Schlyter's explanations|https://www.stjarnhimlen.se/comp/riset.html#3>
are not detailed enough for my taste and there is no
compilable source available to check this algorithm (unlike the 
L<simple version without iteration|https://www.stjarnhimlen.se/comp/sunriset.c>).

=head2 For Whom? For The Next Module Maintainer

Actually, my teddy-bear understands French, so the present
English version is not for him.
The second person for whom I write is the next module maintainer. I have read
L<Neil Bowers' message|http://codeverge.com/perl.module-authors/the-module-authors-pledge/744969>
about I<the module authors pledge>. I agree with him and I declare that
should I stop maintaining my modules for whatever reason, I accept that 
any volunteer can take charge of them.

What Neil did not explain, is that the new maintainer must obey a few
criteria and must have three available resources to take over a module maintenance:
be competent in Perl programming, have enough available time to work on
the module and be enthusiastic enough to get around to it.