Remove outdated questions from FAQ

More or less all old questions from the FAQ has been removed and
replaced by new questions that align better with the current state of
the project.

1 files changed, 54 insertions, 206 deletions

diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index 21fe158b..d6f118ce 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -10,208 +10,73 @@ FAQ
        :depth: 3
        :backlinks: none
 
-
-
-Where can I find the list of projections and their arguments?
+Which file formats does PROJ support?
 --------------------------------------------------------------------------------
 
-:doc:`Here<../operations/projections/index>`.
+The :ref:`command line applications <apps>` that come with PROJ only support text
+input and output (apart from :program:`proj` which accepts a simple binary data
+stream as well). :program:`proj`, :program:`cs2cs` and :program:`cct` expects
+text files with one coordinate per line with each coordinate dimension in a
+separate column.
+
+.. note::
 
-Additionally, the :program:`proj` command itself can report the list of projections
-using the ``-lp`` option, the list of ellipsoids with the ``-le`` option,
-the list of units with the ``-lu`` option, and the list of built-in datums with
-the ``-ld`` option.
+    If your data is stored in a common geodata file format chances are that
+    you can use `GDAL <https://gdal.org/>`_ as a frontend to PROJ and transform your data with the
+    :program:`ogr2ogr` application.
 
-How do I do datum shifts between NAD27 and NAD83?
+Can I transform from *abc* to *xyz*?
 --------------------------------------------------------------------------------
 
-Using the :program:`cs2cs` application.  The following example demonstrates using the
-default shift parameters for NAD27 to NAD83:
-
-::
+Probably. PROJ supports transformations between most coordinate reference systems
+registered in the EPSG registry, as well as a number of other coordinate reference
+systems. The best way to find out is to test it with the :program:`projinfo`
+application. Here's an example checking if there's a transformation between
+ETRS89/UTM32N (EPSG:25832) and ETRS89/DKTM1 (EPSG:4093):
 
-    % cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 -117 30
+.. code-block:: console
 
-producing:
+    $ ./projinfo -s EPSG:25832 -t EPSG:4093 -o PROJ
+    Candidate operations found: 1
+    -------------------------------------
+    Operation n°1:
 
-::
+    unknown id, Inverse of UTM zone 32N + DKTM1, 0 m, World
 
-    117d0'2.901"W   30d0'0.407"N 0.000
+    PROJ string:
+    +proj=pipeline +step +inv +proj=utm +zone=32 +ellps=GRS80
+    +step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.99998 +x_0=200000 +y_0=-5000000 +ellps=GRS80
 
-In order for datum shifting to work properly the various grid shift files must
-be available. See below. More details are available in the
-section on :doc:`resource files<resource_files>`.
+See the :program:`projinfo` :ref:`documentation <projinfo>` for more info on
+how to use it.
 
-How do I build/configure PROJ to support datum shifting?
+Coordinate reference system *xyz* is not in the EPSG registry, what do I do?
 --------------------------------------------------------------------------------
 
-After downloading and unpacking the PROJ source, also download and unpack the
-set of datum shift files. See :ref:`download` for instructions how to fetch
-and install these files.
+Generally PROJ will accept coordinate reference system descriptions in the form
+of WKT, WKT2 and PROJ strings. If you are able to describe your desired CRS
+in either of those formats there's a good chance that PROJ will be able to make
+sense of it.
 
-A default build and install on Unix will normally build knowledge of the
-directory where the grid shift files are installed into the PROJ library
-(usually ``/usr/local/share/proj``).  On Windows the library is normally built
-thinking that C:\PROJ\NAD is the installed directory for the grid shift files.
-If the built-in concept of the PROJ data directory is incorrect, the :envvar:`PROJ_LIB`
-environment variable can be defined with the correct directory.
+If it is important to you that a given CRS is added to the EPSG registry, you
+should contact your local geodetic authority and ask them to submit the CRS for
+inclusion in the registry.
 
-How do I debug problems with NAD27/NAD83 datum shifting?
+I found a bug in PROJ, how do I get it fixed?
 --------------------------------------------------------------------------------
 
-1. Verify that you have the binary files (e.g. ``/usr/local/share/proj/conus``)
-   installed on your system.  If not, see the previous question.
-2. Try a datum shifting operation in relative isolation, such as with the :program:`cs2cs`
-   command listed above.  Do you get reasonable results?  If not, it is likely that
-   the grid shift files aren't being found.  Perhaps you need to define
-   :envvar:`PROJ_LIB`?
-3. The :program:`cs2cs` command and the underlying :c:func:`pj_transform()` API know how to do a
-   grid shift as part of a more complex coordinate transformation; however, it
-   is imperative that both the source and destination coordinate system be
-   defined with appropriate datum information.  That means that implicitly or
-   explicitly there must be a ``+datum=`` clause, a ``+nadgrids=`` clause or a
-   ``+towgs84=`` clause.  For instance
-   ``cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +ellps=WGS84`` won't work because defining the output
-   coordinate system as using the ellipse WGS84 isn't the same as defining it
-   to use the datum WGS84 (use ``+datum=WGS84``).  If either the input or output
-   are not identified as having a datum, the datum shifting (and ellipsoid
-   change) step is just quietly skipped!
-4. The :envvar:`PROJ_DEBUG` environment can be defined (any value) to force extra output
-   from the PROJ library to stderr (the text console normally) with
-   information on what data files are being opened and in some cases why a
-   transformation fails.
-
-   ::
-
-        export PROJ_DEBUG=ON
-        cs2cs ...
-
-
-   .. note::
-        ``PROJ_DEBUG`` support is not yet very mature in the PROJ library.
-
-5. The :option:`-v` flag to :program:`cs2cs` can be useful in establishing more detail on what
-   parameters are used internally for a coordinate system.  This will include
-   expanding the definition of ``+datum`` clause.
-
-How do I use EPSG coordinate system codes with PROJ?
---------------------------------------------------------------------------------
+Please report bugs that you find to the issue tracker on GitHub. :ref:`Here's how
+<add_bug_report>`.
 
-There is somewhat imperfect translation between 2D geographic and projected
-coordinate system codes and PROJ descriptions of the coordinate systems
-available in the ``epsg`` definition file that normally lives in the ``proj/data``
-directory.  If installed (as is the default on Unix), it is possible
-to use EPSG numbers like this:
-
-::
-
-
-    % cs2cs -v +init=epsg:26711
-    # ---- From Coordinate System ----
-    #Universal Transverse Mercator (UTM)
-    #       Cyl, Sph
-    #       zone= south
-    # +init=epsg:26711 +proj=utm +zone=11 +ellps=clrk66 +datum=NAD27 +units=m
-    # +no_defs +nadgrids=conus,ntv1_can.dat
-    #--- following specified but NOT used
-    # +ellps=clrk66
-    # ---- To Coordinate System ----
-    #Lat/long (Geodetic)
-    #
-    # +proj=latlong +datum=NAD27 +ellps=clrk66 +nadgrids=conus,ntv1_can.dat
-
-The ``proj/data/epsg`` file can be browsed and searched for coordinate systems
-using a text editor. There are known to be problems with some coordinate
-systems. In particular, any coordinate system with odd axes, a non-greenwich prime
-meridian, or other quirky characteristics is unlikely to work properly. Caveat Emptor!
-
-How do I use 3 parameter and 7 parameter datum shifting
---------------------------------------------------------------------------------
-
-Datum shifts can be approximated with 3 and 7 parameter transformations. Their
-use with :program:`cs2cs` is more fully described in the
-:ref:`geodetic transformation<cs2cs_specific_options>` section.
-
-More generically, the :ref:`helmert` can be used with :program:`cct`.
+If you know how to program you can also try to fix it yourself. You are welcome
+to ask for guidance on one of the :ref:`communication channels <channels>` used
+by the project.
 
-
-Does PROJ work in different international numeric locales?
+How do I contribute to PROJ?
 --------------------------------------------------------------------------------
 
-No. PROJ makes extensive use of the :c:func:`sprintf()` and :c:func:`atof()` C functions
-internally to translate numeric values.  If a locale is in effect that modifies
-formatting of numbers, altering the role of commas and periods in numbers, then
-PROJ will not work. This problem is common in some European locales.
-
-On UNIX-like platforms, this problem can be avoided by forcing the use of the
-default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable to ``C``.
-
-::
-
-    $ export LC_NUMERIC=C
-    $ proj ...
-
-.. note::
-
-    NOTE: Per ticket #49, in PROJ 4.7.0 and later pj_init() operates with locale
-    overridden to "C" to avoid most locale specific processing for applications
-    using the API.  Command line tools may still have issues.
-
-Changing Ellipsoid / Why can't I convert from WGS84 to Google Earth / Virtual Globe Mercator?
-----------------------------------------------------------------------------------------------
-
-The coordinate system definition for Google Earth and Virtual Globe Mercator
-is as follows, which uses a sphere as the earth model for the Mercator
-projection.
-
-::
-
-    +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0
-         +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs
-
-But, if you do something like:
-
-::
-
-    cs2cs +proj=latlong +datum=WGS84
-        +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0
-                       +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs
-
-to convert between WGS84 and Mercator on the sphere there will be substantial
-shifts in the Y Mercator coordinates.  This is because internally :program:`cs2cs` is
-having to adjust the lat/long coordinates from being on the sphere to being on
-the WGS84 datum which has a quite differently shaped ellipsoid.
-
-In this case, and many other cases using spherical projections, the desired
-approach is to actually treat the lat/long locations on the sphere as if they
-were on WGS84 without any adjustments when using them for converting to other
-coordinate systems.  The solution is to "trick" PROJ into applying no change
-to the lat/long values when going to (and through) WGS84.  This can be
-accomplished by asking PROJ to use a null grid shift file for switching from
-your spherical lat/long coordinates to WGS84.
-
-::
-
-    cs2cs +proj=latlong +datum=WGS84 \
-        +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 \
-        +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs
-
-Note the strategic addition of ``+nadgrids=@null`` to the spherical projection
-definition.
-
-Similar issues apply with many other datasets distributed with projections
-based on a spherical earth model, such as many NASA datasets.  This coordinate
-system is now known by the EPSG code 3857 and has in the past been known as
-EPSG:3785 and EPSG:900913.  When using this coordinate system with GDAL/OGR it
-is helpful to include the +wktext so the exact PROJ string will be preserved
-in the WKT representation (otherwise key parameters like ``+nadgrids=@null`` will
-be dropped):
-
-::
-
-    +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0
-               +units=m +nadgrids=@null +wktext  +no_defs
-
+Any contributions from the PROJ community is welcome. See :ref:`contributing` for
+more details.
 
 How do I calculate distances/directions on the surface of the earth?
 --------------------------------------------------------------------------------
@@ -219,32 +84,15 @@ How do I calculate distances/directions on the surface of the earth?
 These are called geodesic calculations. There is a page about it here:
 :ref:`geodesic`.
 
-
-What options does PROJ allow for the shape of the Earth (geodesy)?
---------------------------------------------------------------------------------
-
-See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c
-for possible ellipse options. For example, putting ``+ellps=WGS84`` uses
-the ``WGS84`` Earth shape.
-
-What if I want a spherical Earth?
---------------------------------------------------------------------------------
-
-Use ``+ellps=sphere``.  See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c
-for the radius used in this case.
-
-How do I change the radius of the Earth?  How do I use PROJ for work on Mars?
---------------------------------------------------------------------------------
-
-You can supply explicit values for the semi minor and semi major axes instead
-of using the symbolic "sphere" value.  Eg, if the radius were 2000000m:
-
-::
-
-     +proj=laea +lon_0=-40.000000 +lat_0=74.000000 +x_0=1000000 +y_0=1700000 +a=2000000 +b=2000000"
-
-How do I do False Eastings and False Northings?
+What is the best format for describing coordinate reference systems?
 --------------------------------------------------------------------------------
 
-Use ``+x_0`` and ``+y_0`` in the projection string.
+A coordinate reference system (CRS) can in PROJ be described in several ways:
+As PROJ strings, Well-Known Text (WKT) and as spatial reference ID's (such as EPSG
+codes). Generally, WKT or SRID's are preferred over PROJ strings as they can
+contain more information about a given CRS. Conversions between WKT and PROJ
+strings will in most cases cause a loss of information, potentially leading to
+erroneous transformations.
 
+For compatibility reasons PROJ supports several WKT dialects
+(see :option:`projinfo -o`). If possible WKT2 should be used.