Implement RFC 2: Initial integration of "GDAL SRS barn" work

This work mostly consists of:
- a C++ implementation of the ISO-19111:2018 / OGC Topic 2
  "Referencing by coordinates" classes to represent Datums,
  Coordinate systems, CRSs (Coordinate Reference Systems) and
  Coordinate Operations.
- methods to convert between this C++ modeling and WKT1, WKT2
  and PROJ string representations of those objects
- management and query of a SQLite3 database of CRS and Coordinate Operation definition
- a C API binding part of those capabilities

This is all-in-one squashed commit of the work of
https://github.com/OSGeo/proj.4/pull/1040

1 files changed, 158 insertions, 0 deletions

diff --git a/src/general_doc.dox b/src/general_doc.dox
new file mode 100644
index 00000000..ce5a8130
--- /dev/null
+++ b/src/general_doc.dox
@@ -0,0 +1,158 @@
+/*!
+
+\page general_doc General documentation
+
+\section general_api_design General API design
+
+The design of the class hierarchy is strongly derived from \ref ISO_19111_2018.
+
+Classes for which the constructors are not directly accessible have their
+instances constructed with create() methods. The returned object is a non-null
+shared pointer. Such objects are immutable, and thread-safe.
+
+TODO
+
+\section general_properties General properties
+
+All classes deriving from IdentifiedObject have general properties that can
+be defined at creation time. Those properties are:
+
+<ul>
+<li>osgeo::proj::metadata::Identifier::DESCRIPTION_KEY ("description"): the
+natural language description of the meaning of the code value, provided a a string.</li>
+<li>osgeo::proj::metadata::Identifier::CODE_KEY ("code"): a numeric or
+alphanumeric code, provided as a integer or a string. For example 4326, for
+the EPSG:4326 "WGS84" GeographicalCRS</li>
+<li>osgeo::proj::metadata::Identifier::CODESPACE_KEY ("codespace"): the organization
+responsible for definition and maintenance of the code., provided a a string.
+For example "EPSG".</li>
+<li>osgeo::proj::metadata::Identifier::VERSION_KEY ("version"): the version
+identifier for the namespace, provided a a string.</li>
+<li>osgeo::proj::metadata::Identifier::AUTHORITY_KEY ("authority"): a citation for the authority,
+provided as a string or a osgeo::proj::metadata::Citation object. Often unused</li>
+<li>osgeo::proj::metadata::Identifier::URI_KEY ("uri"): the URI of the identifier,
+provided as a string. Often unused</li>
+
+<li>osgeo::proj::common::IdentifiedObject::NAME_KEY ("name"): the name of a
+osgeo::proj::common::IdentifiedObject, provided as a string or
+osgeo::proj::metadata::IdentifierNNPtr.</li>
+<li>osgeo::proj::common::IdentifiedObject::IDENTIFIERS_KEY ("identifiers"):
+the identifier(s) of a osgeo::proj::common::IdentifiedObject, provided as
+a osgeo::proj::common::IdentifierNNPtr or a
+osgeo::proj::util::ArrayOfBaseObjectNNPtr of
+osgeo::proj::metadata::IdentifierNNPtr.</li>
+<li>osgeo::proj::common::IdentifiedObject::ALIAS_KEY ("alias"):
+the alias(es) of a osgeo::proj::common::IdentifiedObject,
+provided as string, a osgeo::proj::util::GenericNameNNPtr or a
+osgeo::proj::util::ArrayOfBaseObjectNNPtr
+of osgeo::proj::util::GenericNameNNPtr.</li>
+<li>osgeo::proj::common::IdentifiedObject::REMARKS_KEY ("remarks"):
+the remarks of a osgeo::proj::common::IdentifiedObject,
+provided as a string.</li>
+<li>osgeo::proj::common::IdentifiedObject::DEPRECATED_KEY ("deprecated"):
+the deprecation flag of a osgeo::proj::common::IdentifiedObject,
+provided as a boolean.</li>
+
+<li>osgeo::proj::common::ObjectUsage::SCOPE_KEY ("scope"):
+the scope of a osgeo::proj::common::ObjectUsage, provided as a string.</li>
+<li>osgeo::proj::common::ObjectUsage::DOMAIN_OF_VALIDITY_KEY ("domainOfValidity"):
+the domain of validity of a osgeo::proj::common::ObjectUsage,
+provided as a osgeo::proj::metadata::ExtentNNPtr.</li>
+<li>osgeo::proj::common::ObjectUsage::OBJECT_DOMAIN_KEY ("objectDomain"):
+the object domain(s) of a osgeo::proj::common::ObjectUsage,
+provided as a osgeo::proj::common::ObjectDomainNNPtr or a
+osgeo::proj::util::ArrayOfBaseObjectNNPtr
+of osgeo::proj::common::ObjectDomainNNPtr.</li>
+
+</ul>
+
+\section standards Applicable standards
+
+\subsection ISO_19111 ISO:19111 / OGC Topic 2 standard
+
+Topic 2 - Spatial referencing by coordinates.
+
+This is an Abstract Specification describes the data elements, relationships and
+associated metadata required for spatial referencing by coordinates. It describes
+Coordinate Reference Systems (CRS), coordinate systems (CS) and coordinate
+transformation or coordinate conversion between two different coordinate
+reference systems.
+
+\subsubsection ISO_19111_2018 ISO 19111:2018
+
+This is the revision mostly used for PROJ C++ modelling.
+
+[OGC 18-005r1, 2018-04-04, ISO 19111:2018]
+(https://portal.opengeospatial.org/files/?artifact_id=78556)
+(not yet adopted, at time of writing)
+
+\subsubsection ISO_19111_2007 ISO 19111:2007
+
+The precedent version of the specification was:
+[OGC 08-015r2, 2010-04-27, ISO 19111:2007]
+(http://portal.opengeospatial.org/files/?artifact_id=39049)
+
+\subsection WKT2 WKT2 standard
+
+Well-known text representation of coordinate reference systems.
+
+Well-known Text (WKT) offers a compact machine- and human-readable
+representation of the critical elements of coordinate reference system (CRS)
+definitions, and coordinate operations. This is an implementation of
+\ref ISO_19111
+
+PROJ implements the two following revisions of the standard:
+
+\subsubsection WKT2_2018 WKT2:2018
+
+[OGC 18-010r1, 2018-06-08, WKT2-2018]
+(https://portal.opengeospatial.org/files/?artifact_id=79826)
+(not yet adopted, at time of writing)
+
+\subsubsection WKT2_2015 WKT2:2015
+
+[OGC 12-063r5, 2015-05-01, WKT2-2015]
+(http://docs.opengeospatial.org/is/12-063r5/12-063r5.html)
+
+\subsection WKT1 WKT1 specification
+
+Older specifications of well-known text representation of coordinate reference
+systems are also supported by PROJ, mostly for compatibility with legacy
+systems, or older versions of GDAL.
+
+GDAL v2.3 and earlier mostly implements:
+
+[OGC 01-009, 2001-01-12, OpenGIS Coordinate Transformation Service Implementation Specification]
+(http://portal.opengeospatial.org/files/?artifact_id=999)
+
+The [GDAL documentation, OGC WKT Coordinate System Issues]
+(http://www.gdal.org/wktproblems.html) discusses issues, and GDAL implementation
+choices.
+
+An older specification of WKT1 is/was used by some software packages:
+
+[OGC 99-049, 1999-05-05, OpenGIS Simple Features Specification For SQL v1.1]
+(http://portal.opengeospatial.org/files/?artifact_id=829)
+
+\subsection ISO_19115 ISO 19115 (Metadata)
+
+Defines the schema required for describing geographic information and services.
+It provides information about the identification, the extent, the quality, the
+spatial and temporal schema, spatial reference, and distribution of digital
+geographic data.
+
+PROJ implements a simplified subset of ISO 19115.
+
+\subsection GeoAPI GeoAPI
+
+A set of Java and Python language programming interfaces for geospatial
+applications.
+
+[GeoAPI main page](http://www.geoapi.org/)
+
+[GeoAPI Javadoc](http://www.geoapi.org/3.0/javadoc/index.html)
+
+[OGC GeoAPI Implementation Specification]
+(http://www.opengeospatial.org/standards/geoapi)
+
+*/