Document date input and output formats

diff --git a/doc/src/architecture.m4 b/doc/src/architecture.m4
index 5867e718ae6742e2eb576db62cabfc967ce3ab93..3e4518be7391d21936a98f5fe6a490e7fbd40cf6 100644 (file)
--- a/doc/src/architecture.m4
+++ b/doc/src/architecture.m4
@@ -28,5 +28,6 @@ System Architecture
 
    architecture/databases.rst
    architecture/special_values.rst
+   architecture/timestamps.rst
    architecture/users.rst
    architecture/schemas.rst

diff --git a/doc/src/architecture/timestamps.m4 b/doc/src/architecture/timestamps.m4
new file mode 100644 (file)
index 0000000..4f87a0e
--- /dev/null
+++ b/doc/src/architecture/timestamps.m4
@@ -0,0 +1,45 @@
+.. Copyright (C) 2023  The Meme Factory, Inc.  www.karlpinc.com
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU Affero General Public License as
+   published by the Free Software Foundation, either version 3 of the
+   License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU Affero General Public License for more details.
+
+   You should have received a copy of the GNU Affero General Public License
+   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+.. M4 setup
+include(constants.m4)
+include(macros.m4)
+sdb_rst_quotes(`on')
+sdb_generated_rst()
+
+.. _dates_and_times:
+
+Dates and Times
+---------------
+
+Date values are always output in YYYY-MM-DD format.\ [#f1]_
+This is unambiguous and more universal than most date representations.
+
+Date values may be input in a wide variety of formats.
+Ideally, they would be input as YYYY-MM-DD but when this is not
+the case the system first attempts to recognize dates as
+if they were written in MM-DD-YYYY format.
+
+For further information on date and time representation see the
+PostgreSQL_ documentation, either that on `dates and times
+<https://www.postgresql.org/docs/current/datatype-datetime.html>`_ or
+the `details of date/time interpretation
+<https://www.postgresql.org/docs/current/datetime-appendix.html>`_.
+
+
+
+.. rubric: Footnotes
+
+.. [#f1] This is the ISO 8601 format.