update with results of commit https://github.com/OSGeo/PROJ/commit/53c07a8bd211b7aee4bc07a9c6726005504b7181gh-pages

8 files changed, 1108 insertions, 0 deletions

diff --git a/_sources/usage/differences.rst.txt b/_sources/usage/differences.rst.txt
new file mode 100644
index 00000000..3bc2f54d
--- /dev/null
+++ b/_sources/usage/differences.rst.txt
@@ -0,0 +1,147 @@
+.. _differences:
+
+================================================================================
+Known differences between versions
+================================================================================
+
+Once in a while, a new version of PROJ causes changes in the existing behavior.
+In this section we track deliberate changes to PROJ that break from previous
+behavior. Most times that will be caused by a bug fix. Unfortunately, some bugs
+have existed for so long that their faulty behavior is relied upon by software
+that uses PROJ.
+
+Behavioural changes caused by new bugs are not tracked here, as they should be
+fixed in later versions of PROJ.
+
+Version 4.6.0
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The default datum application behavior changed with the 4.6.0 release. PROJ
+will now only apply a datum shift if both the source and destination coordinate
+system have valid datum shift information.
+
+The PROJ 4.6.0 Release Notes states
+
+    MAJOR: Rework :c:func:`pj_transform()` to avoid applying ellipsoid to ellipsoid
+    transformations as a datum shift when no datum info is available.
+
+
+Version 5.0.0
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Longitude wrapping when using custom central meridian
+-------------------------------------------------------------------------------
+
+By default PROJ wraps output longitudes in the range -180 to 180. Previous to
+PROJ 5, this was handled incorrectly when a custom central meridian was set with
+:option:`+lon_0`. This caused a change in sign on the resulting easting as seen
+below::
+
+    $ proj +proj=merc +lon_0=110
+    -70 0
+    -20037508.34    0.00
+    290 0
+    20037508.34     0.00
+
+From PROJ 5 on onwards, the same input now results in same coordinates, as seen
+from the example below where PROJ 5 is used::
+
+    $ proj +proj=merc +lon_0=110
+    -70 0
+    -20037508.34    0.00
+    290 0
+    -20037508.34    0.00
+
+The change is made on the basis that :math:`\lambda=290^{\circ}` is a full
+rotation of the circle larger than :math:`\lambda=-70^{\circ}` and hence
+should return the same output for both.
+
+Adding the ``+over`` flag to the projection definition provides
+the old behavior.
+
+Version 6.0.0
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Removal of :file:`proj_def.dat`
+-------------------------------
+
+Before PROJ 6, the :file:`proj_def.dat` was used to provide general and per-projection
+parameters, when ``+no_defs`` was not specified. It has now been removed. In case,
+no ellipsoid or datum specification is provided in the PROJ string, the
+default ellipsoid is GRS80 (was WGS84 in previous PROJ versions).
+
+Changes to :ref:`deformation<deformation>`
+------------------------------------------------------------------
+.. _differences_deformation:
+
+
+Reversed order of operation
+...........................
+
+In the initial version of the of :ref:`deformation<deformation>` operation
+the time span between :math:`t_{obs}` and :math:`t_c` was determined by the
+expression
+
+.. math::
+
+    dt = t_c - t_{obs}
+
+With version 6.0.0 this has been reversed in order to behave similarly to
+the :ref:`Helmert operation<helmert>`, which determines time differences as
+
+.. math::
+
+    dt = t_{obs} - t_c
+
+Effectively this means that the direction of the operation has been reversed,
+so that what in PROJ 5 was a forward operation is now an inverse operation and
+vice versa.
+
+Pipelines written for PROJ 5 can be migrated to PROJ 6 by adding :option:`+inv`
+to forward steps involving the deformation operation. Similarly
+:option:`+inv` should be removed from inverse steps to be compatible with
+PROJ 6.
+
+Removed ``+t_obs``  parameter
+.............................
+
+The ``+t_obs`` parameter was confusing for users since it effectively
+overwrote the observation time in input coordinates. To make it more clear
+what is the operation is doing, users are now required to directly specify
+the time span for which they wish to apply a given deformation. The parameter
+:option:`+dt` has been added for that purpose. The new parameter is mutually
+exclusive with :option:`+t_epoch`. :option:`+dt` is used when deformation
+for a set amount of time is needed and :option:`+t_epoch` is used (in
+conjunction with the observation time of the input coordinate) when
+deformation from a specific epoch to the observation time is needed.
+
+Version 6.3.0
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+projinfo
+--------
+
+Before PROJ 6.3.0, WKT1:GDAL was implicitly calling ``--boundcrs-to-wgs84``, to
+add a ``TOWGS84[]`` node in some cases. This is no longer the case.
+
+
+Version 7.0.0
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+proj
+--------
+
+Removed ``-ld`` option from application, since it promoted use of deprecated
+parameters like ``+towgs`` and ``+datum``.
+
+cs2cs
+--------
+
+Removed ``-ld`` option from application, since it promoted use of deprecated
+parameters like ``+towgs`` and ``+datum``.
+
+UTF-8 adoption
+--------------
+
+The value of all path, filenames passed to PROJ through function calls, PROJ
+strings or environment variables should be encoded in UTF-8.
diff --git a/_sources/usage/ellipsoids.rst.txt b/_sources/usage/ellipsoids.rst.txt
new file mode 100644
index 00000000..cd4b0c43
--- /dev/null
+++ b/_sources/usage/ellipsoids.rst.txt
@@ -0,0 +1,159 @@
+.. _ellipsoids:
+
+================================================================================
+Ellipsoids
+================================================================================
+An ellipsoid is a mathematically defined surface which approximates the *geoid*:
+the surface of the Earth's gravity field, which is approximately the same as
+mean sea level.
+
+
+.. figure:: ../../images/general_ellipsoid.png
+   :width: 500 px
+   :align: center
+   :alt:   Global and local fitting of the ellipsoid
+
+   Global and local fitting of the ellipsoid
+
+
+A complete ellipsoid definition comprises a size (primary) and a shape (secondary)
+parameter.
+
+.. _ellipsoid_size_parameters:
+
+Ellipsoid size parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +R=<value>
+
+   Radius of the sphere, :math:`R`.
+
+.. option:: +a=<value>
+
+   Semi-major axis of the ellipsoid, :math:`a`.
+
+.. _ellipsoid_shape_parameters:
+
+Ellipsoid shape parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +rf=<value>
+
+   Reverse flattening of the ellipsoid, :math:`1/f`.
+
+.. option:: +f=<value>
+
+   Flattening of the ellipsoid, :math:`f`.
+
+.. option:: +es=<value>
+
+   Eccentricity squared, :math:`e^2`.
+
+.. option:: +e=<value>
+
+   Eccentricity, :math:`e`.
+
+.. option:: +b=<value>
+
+   Semi-minor axis, :math:`b`.
+
+The ellipsoid definition may be augmented with a spherification flag, turning
+the ellipsoid into a sphere with features defined by the ellipsoid.
+
+.. _ellipsoid_spherification_parameters:
+
+Ellipsoid spherification parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +R_A=<value>
+
+   A sphere with the same surface area as the ellipsoid.
+
+.. option:: +R_V=<value>
+
+   A sphere with the same volume as the ellipsoid.
+
+.. option:: +R_a=<value>
+
+   A sphere with :math:`R = (a + b)/2` (arithmetic mean).
+
+.. option:: +R_g=<value>
+
+   A sphere with :math:`R = \sqrt{ab}` (geometric mean).
+
+.. option:: +R_h=<value>
+
+   A sphere with :math:`R = 2ab/(a+b)` (harmonic mean).
+
+.. option:: +R_lat_a=<phi>
+
+   A sphere with :math:`R` being the arithmetic mean of the corresponding
+   ellipsoid at latitude :math:`\phi`.
+
+.. option:: +R_lat_g=<phi>
+
+   A sphere with :math:`R` being the geometric mean of the corresponding
+   ellipsoid at latitude :math:`\phi`.
+
+If :option:`+R` is given as size parameter, any shape and spherification
+parameters given are ignored.
+
+.. _ellipsoid_definitions:
+
+Built-in ellipsoid definitions
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The ``ellps=xxx`` parameter provides both size and shape for a number of
+built-in ellipsoid definitions.
+
+    ============   =================================    ============================
+    ellps          Parameters                           Datum name
+    ============   =================================    ============================
+    GRS80          a=6378137.0      rf=298.257222101    GRS 1980(IUGG, 1980)
+    airy           a=6377563.396    b=6356256.910       Airy 1830
+    bessel         a=6377397.155    rf=299.1528128      Bessel 1841
+    clrk66         a=6378206.4      b=6356583.8         Clarke 1866
+    intl           a=6378388.0      rf=297.             International 1909 (Hayford)
+    WGS60          a=6378165.0      rf=298.3            WGS 60
+    WGS66          a=6378145.0      rf=298.25           WGS 66
+    WGS72          a=6378135.0      rf=298.26           WGS 72
+    WGS84          a=6378137.0      rf=298.257223563    WGS 84
+    sphere         a=6370997.0      b=6370997.0         Normal Sphere (r=6370997)
+    ============   =================================    ============================
+
+If size and shape are given as ``ellps=xxx``, later shape and size parameters
+are are taken into account as modifiers for the built-in ellipsoid definition.
+
+While this may seem strange, it is in accordance with historical PROJ
+behavior. It can e.g. be used to define coordinates on the ellipsoid
+scaled to unit semimajor axis by specifying ``+ellps=xxx +a=1``
+
+.. _ellipsoid_transformation_examples:
+
+Transformation examples
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Spherical earth with radius 7000km:
+
+::
+
+    proj=laton R=7000000
+
+Using the GRS80 ellipsoid:
+
+::
+
+    proj=laton ellps=GRS80
+
+Expressing ellipsoid by semi-major axis and reverse flattening (:math:`1/f`):
+
+::
+
+    proj=laton a=6378137.0 rf=298.25
+
+Spherical earth based on volume of ellipsoid
+
+::
+
+    proj=laton a=6378137.0 rf=298.25 +R_V
+
diff --git a/_sources/usage/environmentvars.rst.txt b/_sources/usage/environmentvars.rst.txt
new file mode 100644
index 00000000..0439d918
--- /dev/null
+++ b/_sources/usage/environmentvars.rst.txt
@@ -0,0 +1,96 @@
+.. _environmentvars:
+
+================================================================================
+Environment variables
+================================================================================
+
+PROJ can be controlled by setting environment variables. Most users will
+have a use for the :envvar:`PROJ_LIB`.
+
+On UNIX systems environment variables can be set for a shell-session with::
+
+    $ export VAR="some variable"
+
+or it can be set for just one command line call::
+
+    $ VAR="some variable" ./cmd
+
+Environment variables on UNIX are usually removed with the ``unset`` command::
+
+    $ unset VAR
+
+On windows systems environment variables can be set in the command line with::
+
+    > set VAR="some variable"
+
+``VAR`` will be available for the entire session, unless it is unset. This is
+done by setting the variable with no content::
+
+    > set VAR=
+
+.. envvar:: PROJ_LIB
+
+    The location of PROJ :doc:`resource files<../resource_files>`.
+
+    Starting with PROJ 6, multiple directories can be specified. On Unix, they
+    should be separated by the colon (:) character. on Windows, by the semi-colon (;)
+    character.
+
+    PROJ is hardcoded to look for resource files
+    in other locations as well, amongst those are the
+    installation directory (usually ``share/proj`` under the PROJ
+    installation root) and the current folder.
+
+    You can also set the location of the resource files using
+    :func:`proj_context_set_search_paths` in the :file:`proj.h` API header.
+
+.. versionchanged:: 6.1.0
+
+    Starting with PROJ version 6.1.0, the paths set by
+    :func:`proj_context_set_search_paths` will have priority over the
+    :envvar:`PROJ_LIB` to allow for multiple versions of PROJ
+    resource files on your system without conflicting.
+
+
+.. envvar:: PROJ_AUX_DB
+
+    .. versionadded:: 8.1.0
+
+    To set the path to one or several auxiliary SQLite3 databases of structure
+    identical to the main :file:`proj.db` database and that can contain additional
+    object (CRS, transformation, ...) definitions. If several paths are
+    provided, they must be separated by the colon (:) character on Unix, and
+    on Windows, by the semi-colon (;) character.
+
+
+.. envvar:: PROJ_DEBUG
+
+    Set the debug level of PROJ. The default debug level is zero, which results
+    in no debug output when using PROJ. A number from 1-3, with 3 being the most
+    verbose setting.
+
+.. envvar:: PROJ_NETWORK
+
+    .. versionadded:: 7.0.0
+
+    If set to ON, enable the capability to use remote grids stored on CDN
+    (Content Delivery Network) storage, when grids are not available locally.
+    Alternatively, the :c:func:`proj_context_set_enable_network` function can
+    be used.
+
+.. envvar:: PROJ_NETWORK_ENDPOINT
+
+    .. versionadded:: 7.0.0
+
+    Define the endpoint of the CDN storage. Normally defined through the
+    :file:`proj.ini` configuration file locale in :envvar:`PROJ_LIB`.
+    Alternatively, the :c:func:`proj_context_set_url_endpoint` function can
+    be used.
+
+.. envvar:: PROJ_CURL_CA_BUNDLE
+
+    .. versionadded:: 7.2.0
+
+    Define a custom path to the CA Bundle file. This can be useful if `curl`
+    and :envvar:`PROJ_NETWORK` are enabled. Alternatively, the 
+    :c:func:`proj_curl_set_ca_bundle_path` function can be used.
diff --git a/_sources/usage/index.rst.txt b/_sources/usage/index.rst.txt
new file mode 100644
index 00000000..4bb75121
--- /dev/null
+++ b/_sources/usage/index.rst.txt
@@ -0,0 +1,21 @@
+.. _usage:
+
+================================================================================
+Using PROJ
+================================================================================
+
+The main purpose of PROJ is to transform coordinates from one coordinate
+reference system to another. This can be achieved either with the included
+command line applications or the C API that is a part of the software package.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   quickstart
+   projections
+   transformation
+   ellipsoids
+   environmentvars
+   differences
+   network
diff --git a/_sources/usage/network.rst.txt b/_sources/usage/network.rst.txt
new file mode 100644
index 00000000..37a32d34
--- /dev/null
+++ b/_sources/usage/network.rst.txt
@@ -0,0 +1,107 @@
+.. _network:
+
+================================================================================
+Network capabilities
+================================================================================
+
+.. versionadded:: 7.0
+
+PROJ 7.0 has introduced, per :ref:`rfc4`, the capability to work with grid files
+that are not installed on the local machine where PROJ is executed.
+
+This enables to transparently download the parts of grids that are needed to
+perform a coordinate transformation.
+
+.. _cdn_grids:
+
+CDN of GeoTIFF grids
+--------------------
+
+Files are accessed by default through a CDN (Content Delivery Network),
+accessible through https://cdn.proj.org, that contains :ref:`geodetictiffgrids`
+datasets which are mirrored and managed by the
+https://github.com/OSGeo/PROJ-data/ GitHub project.
+Files in the CDN are designed to be used by PROJ 7 or later, but any software
+project wishing to use the CDN for shifting support are encouraged to
+participate in the project and leverage the CDN. 
+
+How to enable network capabilities ?
+------------------------------------
+
+This capability assumes that PROJ has been build against `libcurl`, and that
+the user authorizes network access.
+
+Authorizing network access can be done in multiple ways:
+
+  - enabling / uncommenting the ``network = on`` line of :ref:`proj-ini`
+  - defining the :envvar:`PROJ_NETWORK` environment variable to ON
+  - or using the :cpp:func:`proj_context_set_enable_network` with a
+    ``enabled = TRUE`` value.
+
+.. note::
+
+    Instead of using the `libcurl` implementation, an application using the PROJ
+    API can supply its own network implementation through C function callbacks
+    with :cpp:func:`proj_context_set_network_callbacks`. Enabling network use
+    must still be done with one of the above mentioned method.
+
+Setting endpoint
+----------------
+
+When this is enabled, and a grid is not found in the various locations where
+:ref:`resource files are looked for <resource_file_paths>`, PROJ will then
+attempt at loading the file from a remote server, which defaults to
+https://cdn.proj.org in :ref:`proj-ini`. This location can be changed with
+the :envvar:`PROJ_NETWORK_ENDPOINT` environment variable or with
+:cpp:func:`proj_context_set_url_endpoint`.
+
+Caching
+-------
+
+To avoid repeated access to network, a local cache of downloaded chunks of grids
+is implemented as SQLite3 database, :file:`cache.db`, stored in the
+:ref:`PROJ user writable directory <user_writable_directory>`.
+
+This local caching is enabled by default (can be changed in :ref:`proj-ini` or
+with :cpp:func:`proj_grid_cache_set_enable`). The default maximum size of the
+cache is 300 MB, which is more than half of the total size of grids available,
+at time of writing. This size can also be customized in :ref:`proj-ini` or
+with :cpp:func:`proj_grid_cache_set_max_size`
+
+Download API
+------------
+
+When on-demand loading of grid is not desirable, the PROJ API also offers the
+capability to download whole grids in the
+:ref:`PROJ user writable directory <user_writable_directory>` by using the
+:cpp:func:`proj_is_download_needed` and :cpp:func:`proj_download_file` functions.
+
+Download utility
+----------------
+
+:ref:`projsync` is a tool for downloading resource files.
+
+
+Mirroring
+---------
+
+If you are able, you are encouraged to mirror the grids via AWS S3 command line:
+
+::
+
+    aws s3 sync s3://cdn.proj.org .
+
+If direct S3 access is not possible, you can also use wget to locally mirror the
+data:
+
+::
+
+    wget --mirror https://cdn.proj.org/
+
+Acknowledgments
+---------------
+
+The s3://cdn.proj.org bucket is hosted by the
+`Amazon Public Datasets program <https://aws.amazon.com/opendata/public-datasets/>`_.
+CDN services are provided by the AWS Public Dataset team via
+`CloudFront <https://aws.amazon.com/cloudfront/>`_
diff --git a/_sources/usage/projections.rst.txt b/_sources/usage/projections.rst.txt
new file mode 100644
index 00000000..1f2e504f
--- /dev/null
+++ b/_sources/usage/projections.rst.txt
@@ -0,0 +1,163 @@
+.. _projections_intro:
+
+================================================================================
+Cartographic projection
+================================================================================
+
+The foundation of PROJ is the large number of
+:doc:`projections<../operations/projections/index>` available in the library. This section
+is devoted to the generic parameters that can be used on any projection in the
+PROJ library.
+
+Below is a list of PROJ parameters which can be applied to most coordinate
+system definitions. This table does not attempt to describe the parameters
+particular to particular projection types. These can be found on the pages
+documenting the individual :doc:`projections<../operations/projections/index>`.
+
+    ==========   ================================================================
+    Parameter    Description
+    ==========   ================================================================
+    +a           Semimajor radius of the ellipsoid axis
+    +axis        Axis orientation
+    +b           Semiminor radius of the ellipsoid axis
+    +ellps       Ellipsoid name (see ``proj -le``)
+    +k           Scaling factor (deprecated)
+    +k_0         Scaling factor
+    +lat_0       Latitude of origin
+    +lon_0       Central meridian
+    +lon_wrap    Center longitude to use for wrapping (see below)
+    +over        Allow longitude output outside -180 to 180 range, disables
+                 wrapping (see below)
+    +pm          Alternate prime meridian (typically a city name, see below)
+    +proj        Projection name (see ``proj -l``)
+    +units       meters, US survey feet, etc.
+    +vunits      vertical units.
+    +x_0         False easting
+    +y_0         False northing
+    ==========   ================================================================
+
+In the sections below most of the parameters are explained in details.
+
+Units
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Horizontal units can be specified using the ``+units`` keyword with a symbolic
+name for a unit (i.e. ``us-ft``).  Alternatively the translation to meters can be
+specified with the ``+to_meter`` keyword (i.e. 0.304800609601219 for US feet).  The
+``-lu`` argument to :program:`cs2cs` or :program:`proj` can be used to list
+symbolic unit names. The default unit for projected coordinates is the meter.
+A few special projections deviate from this behavior, most notably the
+latlong pseudo-projection that returns degrees.
+
+Vertical (Z) units can be specified using the ``+vunits`` keyword with a
+symbolic name for a unit (i.e. ``us-ft``).  Alternatively the translation to
+meters can be specified with the ``+vto_meter`` keyword (i.e. 0.304800609601219
+for US feet).  The ``-lu`` argument to :program:`cs2cs` or :program:`proj` can
+be used to list symbolic unit names.  If no vertical units are specified, the
+vertical units will default to be the same as the horizontal coordinates.
+
+.. note::
+    :program:`proj` does not handle vertical units at all and hence the
+    ``+vto_meter`` argument will be ignored.
+
+Scaling of output units can be done by applying the ``+k_0`` argument. The
+returned coordinates are scaled by the value assigned with the ``+k_0``
+parameter.
+
+False Easting/Northing
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Virtually all coordinate systems allow for the presence of a false easting
+(``+x_0``) and northing (``+y_0``).  Note that these values are always expressed in
+meters even if the coordinate system is some other units.  Some coordinate
+systems (such as UTM) have implicit false easting and northing values.
+
+Longitude Wrapping
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+By default PROJ wraps output longitudes in the range -180 to 180.  The ``+over``
+switch can be used to disable the default wrapping which is done at a low level
+in ``pj_inv()``.  This is particularly useful with projections like the
+:doc:`equidistant cylindrical<../operations/projections/eqc>`
+where it would be desirable for X values past -20000000 (roughly) to continue
+past -180 instead of wrapping to +180.
+
+The ``+lon_wrap`` option can be used to provide an alternative means of doing
+longitude wrapping within ``pj_transform()``.  The argument to this option is a
+center longitude.  So ``+lon_wrap=180`` means wrap longitudes in the range 0 to
+360.  Note that ``+over`` does **not** disable ``+lon_wrap``.
+
+Prime Meridian
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+A prime meridian may be declared indicating the offset between the prime
+meridian of the declared coordinate system and that of greenwich.  A prime
+meridian is declared using the "pm" parameter, and may be assigned a symbolic
+name, or the longitude of the alternative prime meridian relative to greenwich.
+
+Currently prime meridian declarations are only utilized by the
+``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls.
+Consequently the user utility :program:`cs2cs` does honour prime meridians but
+the :program:`proj` user utility ignores them.
+
+The following predeclared prime meridian names are supported.  These can be
+listed using with ``cs2cs -lm``.
+
+ ===========     ================
+ Meridian        Longitude
+ ===========     ================
+   greenwich     0dE
+      lisbon     9d07'54.862"W
+       paris     2d20'14.025"E
+      bogota     74d04'51.3"E
+      madrid     3d41'16.48"W
+        rome     12d27'8.4"E
+        bern     7d26'22.5"E
+     jakarta     106d48'27.79"E
+       ferro     17d40'W
+    brussels     4d22'4.71"E
+   stockholm     18d3'29.8"E
+      athens     23d42'58.815"E
+        oslo     10d43'22.5"E
+ ===========     ================
+
+Example of use.  The location ``long=0``, ``lat=0`` in the greenwich based lat/long
+coordinates is translated to lat/long coordinates with Madrid as the prime
+meridian.
+
+::
+
+    cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid
+    0 0
+    3d41'16.48"E    0dN 0.000
+
+
+Axis orientation
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Starting in PROJ 4.8.0, the +axis argument can be used to control the axis
+orientation of the coordinate system.  The default orientation is "easting,
+northing, up" but directions can be flipped, or axes flipped using combinations
+of the axes in the +axis switch.  The values are:
+
+* "e" - Easting
+* "w" - Westing
+* "n" - Northing
+* "s" - Southing
+* "u" - Up
+* "d" - Down
+
+They can be combined in +axis in forms like:
+
+* ``+axis=enu`` - the default easting, northing, elevation.
+* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic
+  coordinates, or south orientated transverse mercator.
+* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems
+  have "west positive" coordinate systems
+
+.. note::
+
+    The ``+axis`` argument does not work with the :program:`proj` command line
+    utility.
+
+
diff --git a/_sources/usage/quickstart.rst.txt b/_sources/usage/quickstart.rst.txt
new file mode 100644
index 00000000..85e7aa95
--- /dev/null
+++ b/_sources/usage/quickstart.rst.txt
@@ -0,0 +1,69 @@
+.. _quickstart:
+
+================================================================================
+Quick start
+================================================================================
+
+Coordinate transformations are defined by, what in PROJ terminology is
+known as, "proj-strings". A proj-string describes any transformation regardless of
+how simple or complicated it might be. The simplest case is projection of geodetic
+coordinates. This section focuses on the simpler cases and introduces the basic
+anatomy of the proj-string. The complex cases are discussed in
+:doc:`transformation`.
+
+A proj-strings holds the parameters of a given coordinate transformation, e.g.
+
+::
+
+    +proj=merc +lat_ts=56.5 +ellps=GRS80
+
+I.e. a proj-string consists of a projection specifier, ``+proj``, a number of
+parameters that applies to the projection and, if needed, a description of a
+datum shift. In the example above geodetic coordinates are transformed to
+projected space with the :doc:`Mercator projection<../operations/projections/merc>` with
+the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every
+projection in PROJ is identified by a shorthand such as ``merc`` in the above
+example.
+
+By using the  above projection definition as parameters for the command line
+utility :program:`proj` we can convert the geodetic coordinates to projected space:
+
+::
+
+    $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+
+If called as above :program:`proj` will be in interactive mode, letting you
+type the input data manually and getting a response presented on screen.
+:program:`proj` works as any UNIX filter though, which means that you can also
+pipe data to the utility, for instance by using the :program:`echo` command:
+
+::
+
+    $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+    3399483.80      752085.60
+
+
+PROJ also comes bundled with the :program:`cs2cs` utility which is used to
+transform from one coordinate reference system to another. Say we want to
+convert the above Mercator coordinates to UTM, we can do that with
+:program:`cs2cs`:
+
+::
+
+    $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32
+    6103992.36      1924052.47 0.00
+
+Notice the ``+to`` parameter that separates the source and destination
+projection definitions.
+
+If you happen to know the EPSG identifiers for the two coordinates reference
+systems you are transforming between you can use those with :program:`cs2cs`:
+
+::
+
+   $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832
+   231950.54      1920310.71 0.00
+
+In the above example we transform geodetic coordinates in the WGS84 reference
+frame to UTM zone 32N coordinates in the ETRS89 reference frame.
+UTM coordinates 
diff --git a/_sources/usage/transformation.rst.txt b/_sources/usage/transformation.rst.txt
new file mode 100644
index 00000000..785ca65e
--- /dev/null
+++ b/_sources/usage/transformation.rst.txt
@@ -0,0 +1,346 @@
+.. _transformation:
+
+================================================================================
+Geodetic transformation
+================================================================================
+
+PROJ can do everything from the most simple projection to very complex
+transformations across many reference frames. While originally developed as a
+tool for cartographic projections, PROJ has over time evolved into a powerful
+generic coordinate transformation engine that makes it possible to do both
+large scale cartographic projections as well as coordinate transformation at a
+geodetic high precision level. This chapter delves into the details of how
+geodetic transformations of varying complexity can be performed.
+
+In PROJ, two frameworks for geodetic transformations exists, the
+*PROJ 4.x/5.x* / :program:`cs2cs` / :c:func:`pj_transform`
+framework and the *transformation pipelines* framework. The first is the original,
+and limited, framework for doing geodetic transforms in PROJ The latter is a
+newer addition that aims to be a more complete transformation framework. Both are
+described in the sections below. Large portions of the text are based on
+:cite:`EversKnudsen2017`.
+
+Before describing the details of the two frameworks, let us first remark that
+most cases of geodetic transformations can be expressed as a series of elementary
+operations, the output of one operation being the input of the next. E.g. when
+going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the
+simplest case, go through 5 steps:
+
+1. Back-project the UTM coordinates to geographic coordinates
+2. Convert the geographic coordinates to 3D cartesian geocentric coordinates
+3. Apply a Helmert transformation from ED50 to ETRS89
+4. Convert back from cartesian to geographic coordinates
+5. Finally project the geographic coordinates to UTM zone 32 planar coordinates.
+
+
+Transformation pipelines
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The homology between the above steps and a Unix shell style pipeline is evident.
+It is there the main architectural inspiration behind the transformation pipeline
+framework. The pipeline framework is realized by utilizing a special "projection",
+that takes as its user supplied arguments, a series of elementary operations,
+which it strings together in order to implement the full transformation needed.
+Additionally, a number of elementary geodetic operations, including Helmert
+transformations, general high order polynomial shifts and the Molodensky
+transformation are available as part of the pipeline framework.
+In anticipation of upcoming support for full time-varying transformations, we
+also introduce a 4D spatiotemporal data type, and a programming interface
+(API) for handling this.
+
+The Molodensky transformation converts directly from geodetic coordinates
+in one datum, to geodetic coordinates in another datum, while the (typically more
+accurate) Helmert transformation converts from 3D cartesian to 3D cartesian
+coordinates. So when using the Helmert transformation one typically needs to do an
+initial conversion from geodetic to cartesian coordinates, and a final conversion
+the other way round, to arrive at the desired result. Fortunately, this three-step
+compound transformation has the attractive characteristic that each step depends
+only on the output of the immediately preceding step. Hence, we can build a
+geodetic-to-geodetic Helmert transformation by tying together the outputs and inputs
+of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style.
+The pipeline driver, makes this kind of chained transformations possible.
+The implementation is compact, consisting of just one pseudo-projection, called
+``pipeline``, which takes as its arguments strings of elementary projections
+(note: "projection" is the, slightly misleading, PROJ term used for any kind of
+transformation).
+The pipeline pseudo projection is supplemented by a number of elementary
+transformations, all in all providing a framework for building high accuracy
+solutions for a wide spectrum of geodetic tasks.
+
+
+As a first example, let us take a look at the iconic
+*geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in
+the introduction). In PROJ it can be implemented as
+
+::
+
+    proj=pipeline
+    step proj=cart ellps=intl
+    step proj=helmert convention=coordinate_frame
+         x=-81.0703  y=-89.3603  z=-115.7526
+        rx=-0.48488 ry=-0.02436 rz=-0.41321  s=-0.540645
+    step proj=cart inv ellps=GRS80
+
+The pipeline can be expanded at both ends to accommodate whatever coordinate type
+is needed for input and output: In the example below, we transform from the
+deprecated Danish System 45, a 2D system with some tension in the original defining
+network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial
+transformation (the init=./s45b... step, s45b.pol is a file containing the
+polynomial coefficients), taking the S45 coordinates to a technical coordinate
+system (TC32), defined to represent "UTM zone 32 coordinates, as they would look if
+the Helmert transformation between ED50 and ETRS89 was perfect". The TC32
+coordinates are then converted back to geodetic(ED50) coordinates, using an
+inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89),
+using the relevant Helmert transformation, and back to geodetic(ETRS89), before
+finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step
+pipeline, implementing a transformation with centimeter level accuracy from a
+deprecated system with decimeter level tensions.
+
+::
+
+    proj=pipeline
+    step init=./s45b.pol:s45b_tc32
+    step proj=utm inv ellps=intl zone=32
+    step proj=cart ellps=intl
+    step proj=helmert convention=coordinate_frame
+          x=-81.0703  y=-89.3603  z=-115.7526
+         rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645
+    step proj=cart inv ellps=GRS80
+    step proj=utm ellps=GRS80 zone=33
+
+With the pipeline framework spatiotemporal transformation is possible. This is
+possible by leveraging the time dimension in PROJ that enables 4D coordinates
+(three spatial components and one temporal component) to be passed through a
+transformation pipeline. In the example below a transformation from ITRF93 to
+ITRF2000 is defined. The temporal component is given as GPS weeks in the input
+data, but the 14-parameter Helmert transform expects temporal units in decimalyears.
+Hence the first step in the pipeline is the unitconvert pseudo-projection that makes
+sure the correct units are passed along to the Helmert transform.
+Most parameters of the Helmert transform are taken from :cite:`Altamimi2002`,
+except the epoch which is the epoch of the transformation.
+The last step in the pipeline is converting the
+coordinate timestamps back to GPS weeks.
+
+::
+
+    proj=pipeline
+    step proj=unitconvert t_in=gps_week t_out=decimalyear
+    step proj=helmert convention=coordinate_frame
+         x=0.0127 y=0.0065 z=-0.0209 s=0.00195
+         rx=0.00039 ry=-0.00080 rz=0.00114
+         dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001
+         drx=0.00011 dry=0.00019 drz=-0.00007
+         t_epoch=1988.0
+    step proj=unitconvert t_in=decimalyear t_out=gps_week
+
+
+PROJ 4.x/5.x paradigm
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+.. _cs2cs_specific_options:
+
+    ============   ==============================================================
+    Parameter      Description
+    ============   ==============================================================
+    +datum         Datum name (see ``proj -ld``)
+    +geoidgrids    Filename of GTX grid file to use for vertical datum transforms
+    +nadgrids      Filename of NTv2 grid file to use for datum transforms
+    +towgs84       3 or 7 term datum transform parameters
+    +to_meter      Multiplier to convert map units to 1.0m
+    +vto_meter     Vertical conversion to meters
+    ============   ==============================================================
+
+.. warning::
+    This section documents the behavior of PROJ 4.x and 5.x. In PROJ 6.x,
+    :program:`cs2cs` has been reworked to use :c:func:`proj_create_crs_to_crs` internally,
+    with *late binding* capabilities, and thus is no longer constrained to using
+    WGS84 as a pivot (also called as *early binding* method).
+    When :program:`cs2cs` of PROJ 6 is used with PROJ.4 expanded strings to describe the CRS,
+    including ``+towgs84``, ``+nadgrids`` and ``+geoidgrids``, it will generally give
+    the same results as earlier PROJ versions. When used with AUTHORITY:CODE
+    CRS descriptions, it may return different results.
+
+The *cs2cs* framework in PROJ 4 and 5 delivers a subset of the geodetic transformations available
+with the *pipeline* framework. Coordinate transformations done in this framework
+were transformed in a two-step process with WGS84 as a pivot datum. That is, the
+input coordinates are transformed to WGS84 geodetic coordinates and then transformed
+from WGS84 coordinates to the specified output coordinate reference system, by
+utilizing either the Helmert transform, datum shift grids or a combination of both.
+Datum shifts can be described in a proj-string with the parameters ``+towgs84``,
+``+nadgrids`` and ``+geoidgrids``.
+An inverse transform exists for all three and is applied if
+specified in the input proj-string. The most common is ``+towgs84``, which is used to
+define a 3- or 7-parameter Helmert shift from the input reference frame to WGS84.
+Exactly which realization of WGS84 is not specified, hence a fair amount of
+uncertainty is introduced in this step of the transformation. With the +nadgrids
+parameter a non-linear planar correction derived from interpolation in a
+correction grid can be applied. Originally this was implemented as a means to
+transform coordinates between the North American datums NAD27 and NAD83, but
+corrections can be applied for any datum for which a correction grid exists. The
+inverse transform for the horizontal grid shift is "dumb", in the sense that the
+correction grid is applied verbatim without taking into account that the inverse
+operation is non-linear. Similar to the horizontal grid correction, ``+geoidgrids``
+can be used to perform grid corrections in the vertical component.
+Both grid correction methods allow inclusion of more than one grid in the same
+transformation
+
+In contrast to the *transformation pipeline* framework, transformations with the
+*cs2cs* framework in PROJ 4 and 5 were expressed as two separate proj-strings. One proj-string *to*
+WGS84 and one *from* WGS84. Together they form the mapping from the source
+coordinate reference system to the destination coordinate reference system.
+When used with the :program:`cs2cs` the source and destination CRS's are separated by the
+special ``+to`` parameter.
+
+The following example demonstrates converting from the Greek GGRS87 datum
+to WGS84 with the ``+towgs84`` parameter.
+
+::
+
+    cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62
+        +to +proj=latlong +datum=WGS84
+    20 35
+    20d0'5.467"E    35d0'9.575"N 0.000
+
+With PROJ 6, you can simply use the following:
+
+.. note:: With PROJ 6, the order of coordinates for EPSG geographic coordinate
+          reference systems is latitude first, longitude second.
+
+::
+
+    cs2cs "GGRS87" "WGS 84"
+    35 20
+    35d0'9.575"N    20d0'5.467"E 0.000
+
+    cs2cs EPSG:4121 EPSG:4326
+    35 20
+    35d0'9.575"N    20d0'5.467"E 0.000
+
+The EPSG database provides this example for transforming from WGS72 to WGS84
+using an approximated 7 parameter transformation.
+
+::
+
+    cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \
+        +to +proj=latlong +datum=WGS84
+    4 55
+    4d0'0.554"E     55d0'0.09"N 0.000
+
+With PROJ 6, you can simply use the following (note the reversed order for
+latitude and longitude)
+
+::
+
+    cs2cs "WGS 72" "WGS 84"
+    55 4
+    55d0'0.09"N 4d0'0.554"E 0.000
+
+    cs2cs EPSG:4322 EPSG:4326
+    55 4
+    55d0'0.09"N 4d0'0.554"E 0.000
+
+
+Grid Based Datum Adjustments
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+In many places (notably North America and Australia) national geodetic
+organizations provide grid shift files for converting between different datums,
+such as NAD27 to NAD83.  These grid shift files include a shift to be applied
+at each grid location. Actually grid shifts are normally computed based on an
+interpolation between the containing four grid points.
+
+PROJ supports use of grid files for shifting between various reference frames.
+The grid shift table formats are CTable, NTv1 (the old Canadian format), and NTv2
+(:file:`.gsb` - the new Canadian and Australian format).
+
+The text in this section is based on the *cs2cs* framework. Gridshifting is off
+course also possible with the *pipeline* framework. The major difference between the
+two is that the *cs2cs* framework is limited to grid mappings to WGS84, whereas with
+*transformation pipelines* it is possible to perform grid shifts between any two
+reference frames, as long as a grid exists.
+
+Use of grid shifts with :program:`cs2cs` is specified using the ``+nadgrids``
+keyword in a coordinate system definition. For example:
+
+::
+
+    % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 50
+    EOF
+    111d0'2.952"W   50d0'0.111"N 0.000
+
+In this case the :file:`/usr/local/share/proj/ntv1_can.dat` grid shift file was
+loaded, and used to get a grid shift value for the selected point.
+
+It is possible to list multiple grid shift files, in which case each will be
+tried in turn till one is found that contains the point being transformed.
+
+::
+
+    cs2cs +proj=latlong +ellps=clrk66 \
+              +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 44
+    EOF
+    111d0'2.788"W   43d59'59.725"N 0.000
+
+
+Skipping Missing Grids
+................................................................................
+
+The special prefix ``@`` may be prefixed to a grid to make it optional.  If it
+not found, the search will continue to the next grid.  Normally any grid not
+found will cause an error.  For instance, the following would use the
+:file:`ntv2_0.gsb` file if available, otherwise it would
+fallback to using the :file:`ntv1_can.dat` file.
+
+::
+
+    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 50
+    EOF
+    111d0'3.006"W   50d0'0.103"N 0.000
+
+The null Grid
+................................................................................
+
+A special :file:`null` grid shift file is distributed with PROJ.
+This file provides a zero shift for the whole world.  It may be
+listed at the end of a nadgrids file list if you want a zero shift to be
+applied to points outside the valid region of all the other grids.  Normally if
+no grid is found that contains the point to be transformed an error will occur.
+
+::
+
+    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 45
+    EOF
+    111d0'3.006"W   50d0'0.103"N 0.000
+
+    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 44
+    -111 55
+    EOF
+    111d0'2.788"W   43d59'59.725"N 0.000
+    111dW   55dN 0.000
+
+For more information see the chapter on :ref:`transformation_grids`.
+
+Caveats
+................................................................................
+
+* Where grids overlap (such as conus and :file:`ntv1_can.dat` for instance) the first
+  found for a point will be used regardless of whether it is appropriate or
+  not.  So, for instance, ``+nadgrids=ntv1_can.dat``,conus would result in
+  the Canadian data being used for some areas in the northern United States
+  even though the conus data is the approved data to use for the area.
+  Careful selection of files and file order is necessary.  In some cases
+  border spanning datasets may need to be pre-segmented into Canadian and
+  American points so they can be properly grid shifted
+* Additional detail on the grid shift being applied can be found by setting
+  the PROJ_DEBUG environment variable to a value.  This will result in output
+  to stderr on what grid is used to shift points, the bounds of the various
+  grids loaded and so forth