[newlib-cygwin] winsup/doc/faq-api.xml(faq.api.timezone): explain time zone updates

[newlib-cygwin] winsup/doc/faq-api.xml(faq.api.timezone): explain time zone updates

[Corinna Vinschen]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=573dda0cf2efa947a9c3d665abc1d94a0d600a9e

commit 573dda0cf2efa947a9c3d665abc1d94a0d600a9e
Author: Brian Inglis <Brian.Inglis@SystematicSW.ab.ca>
Date:   Thu Aug 27 01:17:09 2020 -0600

    winsup/doc/faq-api.xml(faq.api.timezone): explain time zone updates
    
    based on material from tz@IANA.org mailing list sources

Diff:
---
 winsup/doc/faq-api.xml | 40 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml
index 829e4d7fe..6283fb663 100644
--- a/winsup/doc/faq-api.xml
+++ b/winsup/doc/faq-api.xml
@@ -385,13 +385,43 @@ Cygwin version number details, check out the
 </answer></qandaentry>
 
 <qandaentry id="faq.api.timezone">
-<question><para>Why isn't timezone set correctly?</para></question>
+<question><para>Why isn't my time (or zone) set correctly?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
-</para>
-<para>Did you explicitly call tzset() before checking the value of timezone?
-If not, you must do so.
+<para>Daylight saving (Summer time) and other time zone changes are
+decided on by politicians, and announced by government officials,
+sometimes with short or no notice, so time zone updates are released at
+least a few, and sometimes several, times a year.
+Details of changes are not known until they are announced publicly by
+officials, often in foreign languages.
+Those details then have to be noticed, possibly translated, passed to,
+picked up, and applied by the official <filename>tzdata</filename>
+source package maintainers.
+That information has to be compiled, checked, and released publicly in
+an update to the official <filename>tzdata</filename> source package.
+Then those changes have to be picked up and applied to the Cygwin
+<filename>tzdata</filename> package, which has to be updated, built,
+tested, and released publicly.
+</para>
+<para>Time zone settings are updates to the daylight saving (Summer
+time) rules for dates of changes, hour offsets from UTC of time zones,
+and the geographic regions to which those rules and offsets apply,
+provided in the <filename>tzdata</filename> package included in all
+Cygwin installations.
+Have you run the Cygwin Setup program recently to update at least
+the <filename>tzdata</filename> package?
+</para>
+<para>Are you developing applications using times which may be affected
+by time zones?
+Since the <literal>ctime()</literal>, <literal>localtime()</literal>,
+<literal>mktime()</literal>, and <literal>strftime()</literal> functions
+are required to set time zone information as if by calling
+<literal>tzset()</literal>, there is no need for an explicit
+<literal>tzset()</literal> call before using these functions.
+However, if none of the above functions are called first, applications
+should ensure <literal>tzset()</literal> is called explicitly before
+using any other time functions, or checking or using time zone
+information.
 </para>
 </answer></qandaentry>