Merge pull request #577 from OSGeo/docs-release-4.10.0

Docs for the upcoming release

12 files changed, 1609 insertions, 23 deletions

diff --git a/docs/source/development/bindings.rst b/docs/source/development/bindings.rst
index a1c2a9e0..3fac1869 100644
--- a/docs/source/development/bindings.rst
+++ b/docs/source/development/bindings.rst
@@ -4,40 +4,40 @@
 Language bindings
 ********************************************************************************
 
-Proj.4 bindings are available for a number of different development platforms.
+PROJ bindings are available for a number of different development platforms.
 
 Python
 ======
 `pyproj <http://pypi.python.org/pypi/pyproj>`_:
-Python interface (wrapper for proj.4)
+Python interface (wrapper for PROJ)
 
 
 Ruby
 =======
 
 `proj4rb <http://proj4rb.rubyforge.org>`_:
-Bindings for proj.4 in ruby
+Bindings for PROJ in ruby
 
 TCL
 ========
 `proj4tcl <http://wiki.tcl.tk/41270>`_:
-Bindings for proj.4 in tcl (critcl source)
+Bindings for PROJ in tcl (critcl source)
 
 MySQL
 =====
 
 `fProj4 <http://sourceforge.net/projects/mysqlscientific/files/fPROJ4/>`_:
-Bindings for proj.4 in MySQL
+Bindings for PROJ in MySQL
 
 
 Excel
 ========
 
 `proj.xll <https://github.com/jbuonagurio/proj.xll>`_:
-Excel add-in for proj.4 map projections
+Excel add-in for PROJ map projections
 
 Visual Basic
 ==================
 
-`PROJ.4 VB Wrappers <http://ftp.dfg.ca.gov/Public/BDB/Tools/proj4/proj_api.zip>`_:
+`PROJ VB Wrappers <http://ftp.dfg.ca.gov/Public/BDB/Tools/proj4/proj_api.zip>`_:
 By Eric G. Miller.
diff --git a/docs/source/development/cmake.rst b/docs/source/development/cmake.rst
index 1429ae88..5a8ce624 100644
--- a/docs/source/development/cmake.rst
+++ b/docs/source/development/cmake.rst
@@ -1,10 +1,10 @@
 .. _cmake:
 
 ********************************************************************************
-Using Proj.4 in CMake projects
+Using PROJ in CMake projects
 ********************************************************************************
 
-The recommended way to use the Proj.4 library in a CMake project is to
+The recommended way to use the PROJ library in a CMake project is to
 link to the imported library target ``${PROJ4_LIBRARIES}`` provided by
 the CMake configuration which comes with the library. Typical usage is:
 
diff --git a/docs/source/development/errorhandling.rst b/docs/source/development/errorhandling.rst
new file mode 100644
index 00000000..58199e3f
--- /dev/null
+++ b/docs/source/development/errorhandling.rst
@@ -0,0 +1,7 @@
+.. _errorhandling:
+
+================================================================================
+Error handling
+================================================================================
+
+
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
index 712bbdfe..3f8a7bf6 100644
--- a/docs/source/development/index.rst
+++ b/docs/source/development/index.rst
@@ -5,13 +5,17 @@ Development
 ================================================================================
 
 These pages are primarily focused towards developers either contributing to the
-proj.4 project or using the library in their own software.
+PROJ project or using the library in their own software.
 
 
 .. toctree::
    :maxdepth: 1
 
-   api
+   quickstart
+   transformations
+   errorhandling
    threads
-   bindings
+   reference/index
    cmake
+   bindings
+   migration
diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst
new file mode 100644
index 00000000..eb509bcf
--- /dev/null
+++ b/docs/source/development/migration.rst
@@ -0,0 +1,193 @@
+.. _API_migration:
+
+================================================================================
+Version 4 to 5 API Migration
+================================================================================
+
+This is a transition guide for developers wanting to migrate their code to use
+PROJ version 5.
+
+
+Background
+###############################################################################
+
+Before we go on, a bit of background is needed. The new API takes a different
+view of the world than the old because it is needed in order to obtain high
+accuracy transformations. The old API is constructed in such a way that any transformation
+between two coordinate reference systems *must* pass through the ill-defined
+WGS84 reference frame, using it as a hub. The new API does away with this limitation to
+transformations in PROJ. It is still possible to do that type of transformations
+but in many cases there will be a better alternative.
+
+The world view represented by the old API is always sufficient if all you care about is
+meter level accuracy - and in many cases it will provide much higher accuracy
+than that. But the view that “WGS84 is the *true* foundation of the world, and
+everything else can be transformed natively to and from WGS84” is inherently flawed.
+
+First and foremost because any time WGS84 is mentioned, you should ask yourself
+“Which of the six WGS84 realizations are we talking about here?”.
+
+Second, because for many (especially legacy) systems, it may not be straightforward
+to transform to WGS84 (or actually ITRF-something, ETRS-something or NAD-something
+which appear to be the practical meaning of the term WGS84 in everyday PROJ related
+work), while centimeter-level accurate transformations may exist between pairs of
+older systems.
+
+The concept of a hub reference frame (“datum”) is not inherently bad, but in many
+cases you need to handle and select that datum with more care than the old API allows.
+The primary aim of the new API is to allow just that. And to do that, you must realize
+that the world is inherently 4 dimensional. You may in many cases assume one or more of
+the coordinates to be constant, but basically, to obtain geodetic accuracy transformations,
+you need to work in 4 dimensions.
+
+Now, having described the background for introducing the new API, let's try to show
+how to use it. First note that in order to go from system A to system B, the old API
+starts by doing an **inverse** transformation from system A to WGS84, then does a
+**forward** transformation from WGS84 to system B.
+
+With ``cs2cs`` being the command line interface to the old API, and ``cct`` being the same
+for the new, this example of doing the same thing in both world views will should give
+an idea of the differences:
+
+::
+
+    $ echo 300000 6100000 | cs2cs +proj=utm +zone=33 +ellps=GRS80 +to +proj=utm +zone=32 +ellps=GRS80
+    683687.87       6099299.66 0.00
+
+
+    $ echo 300000 6100000 0 0 | cct +proj=pipeline +step +inv +proj=utm +zone=33 +ellps=GRS80 +step +proj=utm +zone=32 +ellps=GRS80
+    683687.8667   6099299.6624    0.0000    0.0000
+
+Lookout for the ``+inv`` in the first ``+step``, indicating an inverse transform.
+
+
+Code example
+###############################################################################
+
+The difference between the old and new API is shown here with a few examples. Below
+we implement the same program with the two different API's. The program reads
+input latitude and longitude from the command line and convert them to
+projected coordinates with the Mercator projection.
+
+We start by writing the program for PROJ v. 4:
+
+.. code-block:: C
+
+    #include <proj_api.h>
+
+    main(int argc, char **argv) {
+        projPJ pj_merc, pj_latlong;
+        double x, y;
+
+        if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) )
+            return 1;
+        if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) )
+            return 1;
+
+        while (scanf("%lf %lf", &x, &y) == 2) {
+            x *= DEG_TO_RAD;
+            y *= DEG_TO_RAD;
+            p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL );
+            printf("%.2f\t%.2f\n", x, y);
+        }
+
+        return 0;
+    }
+
+The same program implemented using PROJ v. 5:
+
+.. code-block:: C
+
+    #include <proj.h>
+
+    main(int argc, char **argv) {
+        PJ *P;
+        PJ_COORD c;
+
+        P = proj_create(PJ_DEFAULT_CTX, "+proj=merc +ellps=clrk66 +lat_ts=33");
+        if (P==0)
+            return 1;
+
+        while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) {
+            c.lp.lam = proj_todeg(c.lp.lam);
+            c.lp.phi = proj_todeg(c.lp.phi);
+            c = proj_trans(P, PJ_FWD, c);
+            printf("%.2f\t%.2f\n", c.xy.x, c.xy.y);
+        }
+
+    }
+
+Looking at the two different programs, there's a few immediate
+differences that catches the eye. First off, the included header file describing
+the API has changed from ``proj_api.h`` to simply ``proj.h``. All functions in ``proj.h``
+belongs to the ``proj_`` namespace.
+
+With the new API also comes new datatypes. E.g. the transformation object ``projPJ``
+which has been changed to a pointer of type ``PJ``. This is done to highlight the
+actual nature of the object, instead of hiding it away behind a typedef. New data
+types for handling coordinates have also been introduced. In the above example we
+use the ``PJ_COORD``, which is a union of various types. The benefit of this is that
+it is possible to use the various structs in the union to communicate what state
+the data is in at different points in the program. For instance as in the above
+example where the coordinate is read from STDIN as a geodetic coordinate,
+communicated to the reader of the code by using the ``c.lp`` struct.
+After it has been projected we print it to STDOUT by accessing the individual
+elements in ``c.xy`` to illustrate that the coordinate is now in projected space.
+Data types are prefixed with `PJ_`.
+
+The final, and perhaps biggest, change is that the fundamental concept of
+transformations in PROJ are now handled in a single transformation object (``PJ``)
+and not by stating the source and destination systems as previously. It is of
+course still possible to do just that, but the transformation object now
+captures the whole transformation from source to destination in one. In the
+example with the old API the source system is described as
+``+proj=latlon +ellps=clrk66`` and the destination system is described as
+``+proj=merc +ellps=clrk66 +lat_ts=33``. Since the Mercator projection accepts
+geodetic coordinates as its input, the description of the source in this case
+is superflous. We use that to our advantage in the new API and simply state
+the destination. This is simple at a glance, but is actually a big conceptual
+change. We are now focused on the path between two systems instead of what the
+source and destination systems are.
+
+Function mapping from old to new API
+###############################################################################
+
++---------------------------------------+---------------------------------------+
+| **Old API functions**                 | **New API functions**                 |
++---------------------------------------+---------------------------------------+
+| pj_fwd                                | proj_trans                            |
++---------------------------------------+---------------------------------------+
+| pj_inv                                | proj_trans                            |
++---------------------------------------+---------------------------------------+
+| pj_fwd3                               | proj_trans                            |
++---------------------------------------+---------------------------------------+
+| pj_inv3                               | proj_trans                            |
++---------------------------------------+---------------------------------------+
+| pj_transform                          | proj_trans_array or proj_trans_generic|
++---------------------------------------+---------------------------------------+
+| pj_init                               | proj_create                           |
++---------------------------------------+---------------------------------------+
+| pj_init_plus                          | proj_create                           |
++---------------------------------------+---------------------------------------+
+| pj_free                               | proj_destroy                          |
++---------------------------------------+---------------------------------------+
+| pj_is_latlong                         | proj_angular_output                   |
++---------------------------------------+---------------------------------------+
+| pj_is_geocent                         | proj_angular_outout                   |
++---------------------------------------+---------------------------------------+
+| pj_get_def                            | proj_pj_info                          |
++---------------------------------------+---------------------------------------+
+| pj_latlong_from_proj                  | *No equivalent*                       |
++---------------------------------------+---------------------------------------+
+| pj_set_finder                         | *No equivalent*                       |
++---------------------------------------+---------------------------------------+
+| pj_set_searchpath                     | *No equivalent*                       |
++---------------------------------------+---------------------------------------+
+| pj_deallocate_grids                   | *No equivalent*                       |
++---------------------------------------+---------------------------------------+
+| pj_strerrno                           | *No equivalent*                       |
++---------------------------------------+---------------------------------------+
+| pj_get_errno_ref                      | proj_errno                            |
++---------------------------------------+---------------------------------------+
+| pj_get_release                        | proj_info                             |
++---------------------------------------+---------------------------------------+
diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst
new file mode 100644
index 00000000..960cddbf
--- /dev/null
+++ b/docs/source/development/quickstart.rst
@@ -0,0 +1,100 @@
+.. _dev_quickstart:
+
+================================================================================
+Quick start
+================================================================================
+
+This is a short introduction to the PROJ API. In the following section we
+create a simple program that transforms a geodetic coordinate to UTM and back
+again. The program is explained a few lines at a time. The complete program can
+be seen at the end of the section.
+
+See the following sections for more in-depth descriptions of different parts of
+the PROJ API or consult the :doc:`API reference <reference/index>` for specifics.
+
+Before the PROJ API can be used it is necessary to include the ``proj.h`` header
+file. Here ``stdio.h`` is also included so we can print some text to the screen:
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 39-40
+
+Let's declare a few variables that'll be used later in the program. Each variable
+will be discussed below.
+See the :doc:`reference for more info on data types <reference/datatypes>`.
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 43-45
+  :dedent: 4
+
+For use in multi-threaded programs the ``PJ_CONTEXT`` threading-context is used.
+In this particular example it is not needed, but for the sake of completeness
+it created here. The section on :doc:`threads <threads>` discusses
+this in detail.
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 48
+  :dedent: 4
+
+Next we create the ``PJ`` transformation object ``P`` with the function
+``proj_create``. ``proj_create`` takes the threading context ``C`` created above,
+and a proj-string that defines the desired transformation. Here we transform
+from geodetic coordinate to UTM zone 32N.
+It is recommended to create one threading-context per thread used by the program.
+This ensures that all ``PJ`` objects created in the same context will be sharing
+resources such as error-numbers and loaded grids.
+In case the creation of the ``PJ`` object fails an error message is displayed and
+the program returns. See :doc:`errorhandling` for further
+details.
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 50-52
+  :dedent: 4
+
+PROJ uses it's own data structures for handling coordinates. Here we use a
+``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note
+that the input values are converted to radians with ``proj_torad``. This is
+necessary since PROJ is using radians internally. See :doc:`transformations`
+for further details.
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 56
+  :dedent: 4
+
+The coordinate defined above is transformed with ``proj_trans_coord``. For this
+a ``PJ`` object, a transformation direction (either forward or inverse) and the
+coordinate is needed. The transformed coordinate is returned in ``b``.
+Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made.
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 59-60
+  :dedent: 4
+
+The inverse transformation (UTM to geodetic) is done similar to above,
+this time using ``PJ_INV`` as the direction.
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 61-62
+  :dedent: 4
+
+Before ending the program the allocated memory needs to be released again:
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :lines: 65-66
+  :dedent: 4
+
+
+A complete compilable version of the above can be seen here:
+
+.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c
+  :language: c
+  :linenos:
+  :lines: 39-
+
diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst
new file mode 100644
index 00000000..7f2c4b41
--- /dev/null
+++ b/docs/source/development/reference/datatypes.rst
@@ -0,0 +1,746 @@
+.. _datatypes:
+
+================================================================================
+Data types
+================================================================================
+
+This section describes the numerous data types in use in PROJ.4. As a rule
+of thumb PROJ.4 data types are prefixed with ``PJ_``, or in one particular case,
+is simply called :c:type:`PJ`. A few notable exceptions can be traced
+back to the very early days of PROJ.4 when the ``PJ_`` prefix was not
+consistenly used.
+
+Transformation objects
+--------------------------------------------------------------------------------
+
+.. c:type:: PJ
+
+    Object containing everything related to a given projection or transformation.
+    As a user of the PROJ.4 library you are only exposed to pointers to this
+    object and the contents is hidden behind the public API. :c:type:`PJ` objects
+    are created with :c:func:`proj_create` and destroyed with
+    :c:func:`proj_destroy`.
+
+.. c:type:: PJ_DIRECTION
+
+    Enumeration that is used to convey in which direction a given transformation
+    should be performed. Used in transformation function call as described in
+    the section on :ref:`transformation functions <coord_trans_functions>`.
+
+    Forward transformations are defined with the :c:
+
+    .. code-block:: C
+
+        typedef enum proj_direction {
+            PJ_FWD   =  1,   /* Forward    */
+            PJ_IDENT =  0,   /* Do nothing */
+            PJ_INV   = -1    /* Inverse    */
+        } PJ_DIRECTION;
+
+    .. c:member:: PJ_FWD
+
+        Perform transformation in the forward direction.
+
+    .. c:member:: PJ_IDENT
+
+        Identity. Do nothing.
+
+    .. c:member:: PJ_INV
+
+        Perform transformation in the inverse direction.
+
+.. c:type:: PJ_CONTEXT
+
+    Context objects enable safe multi-threaded usage of PROJ.4. Each :c:type:`PJ`
+    object is connected to a context (if not specified, the default context is
+    used). All operations within a context should be performed in the same thread.
+    :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create`
+    and destroyed with :c:func:`proj_context_destroy`.
+
+
+.. c:type:: PJ_AREA
+
+    Opaque object describing an area in which a transformation is performed.
+
+    .. note:: This object is not fully implemented yet. It is to be used with
+              :c:func:`proj_create_crs_to_crs` to select the best transformation
+              between the two input coordinate reference systems.
+
+2 dimensional coordinates
+--------------------------------------------------------------------------------
+
+Various 2-dimensional coordinate data types.
+
+.. c:type:: PJ_LP
+
+    Geodetic coordinate, latitude and longitude. Usually in radians.
+
+    .. code-block:: C
+
+        typedef struct { double lam, phi; } PJ_LP;
+
+    .. c:member:: double PJ_LP.lam
+
+        Longitude. Lambda.
+
+    .. c:member:: double PJ_LP.phi
+
+        Latitude. Phi.
+
+
+.. c:type:: PJ_XY
+
+    2-dimensional cartesian coordinate.
+
+    .. code-block:: C
+
+        typedef struct { double x, y; } PJ_XY;
+
+
+    .. c:member:: double PJ_XY.x
+
+        Easting.
+
+    .. c:member:: double PJ_XY.y
+
+        Northing.
+
+
+.. c:type:: PJ_UV
+
+    2-dimensional generic coordinate. Usually used when contents can be either
+    a :c:type:`PJ_XY` or :c:type:`PJ_LP`.
+
+    .. code-block:: C
+
+        typedef struct {double u, v; } PJ_UV;
+
+
+    .. c:member:: double PJ_UV.u
+
+        Longitude or easting, depending on use.
+
+    .. c:member:: double PJ_UV.v
+
+        Latitude or northing, depending on use.
+
+
+3 dimensional coordinates
+--------------------------------------------------------------------------------
+
+The following data types are the 3-dimensional equivalents to the data
+types above.
+
+.. c:type:: PJ_LPZ
+
+    3-dimensional version of :c:type:`PJ_LP`. Holds longitude, latitude and
+    a vertical component.
+
+    .. code-block:: C
+
+        typedef struct { double lam, phi, z; } PJ_LPZ;
+
+    .. c:member:: double PJ_LPZ.lam
+
+        Longitude. Lambda.
+
+    .. c:member:: double PJ_LPZ.phi
+
+        Latitude. Phi.
+
+    .. c:member:: double PJ_LPZ.z
+
+        Vertical component.
+
+
+.. c:type:: PJ_XYZ
+
+    Cartesian coordinate in 3 dimensions. Extension  of :c:type:`PJ_XY`.
+
+    .. code-block:: C
+
+        typedef struct { double x, y, z; } PJ_XYZ;
+
+    .. c:member:: double PJ_XYZ.x
+
+        Easting or the X component of a 3D cartesian system.
+
+    .. c:member:: double PJ_XYZ.y
+
+        Northing or the Y component of a 3D cartesian system.
+
+    .. c:member:: double PJ_XYZ.z
+
+        Vertical component or the Z component of a 3D cartesian system.
+
+
+.. c:type:: PJ_UVW
+
+    3-dimensional extension of :c:type:`PJ_UV`.
+
+    .. code-block:: C
+
+        typedef struct {double u, v, w; } PJ_UVW;
+
+    .. c:member:: double PJ_UVW.u
+
+        Longitude or easting, depending on use.
+
+    .. c:member:: double PJ_UVW.v
+
+        Latitude or northing, depending on use.
+
+    .. c:member:: double PJ_UVW.w
+
+        Vertical component.
+
+
+Spatiotemporal coordinate types
+--------------------------------------------------------------------------------
+
+The following data types are extensions of the triplets above into the time
+domain.
+
+
+.. c:type:: PJ_LPZT
+
+    Spatiotemporal version of :c:type:`PJ_LPZ`.
+
+    .. code-block:: C
+
+        typedef struct {
+            double lam;
+            double phi;
+            double z;
+            double t;
+        } PJ_LPZT;
+
+
+    .. c:member:: double PJ_LPZT.lam
+
+        Longitude.
+
+    .. c:member:: double PJ_LPZT.phi
+
+        Latitude
+
+    .. c:member:: double PJ_LPZT.z
+
+        Vertical component.
+
+    .. c:member:: double PJ_LPZT.t
+
+        Time component.
+
+.. c:type:: PJ_XYZT
+
+    Generic spatiotemporal coordinate. Usefull for e.g. cartesian coordinates with
+    an attached time-stamp.
+
+    .. code-block:: C
+
+        typedef struct {
+            double x;
+            double y;
+            double z;
+            double t;
+        } PJ_XYZT;
+
+
+    .. c:member:: double PJ_XYZT.x
+
+        Easting or the X component of a 3D cartesian system.
+
+    .. c:member:: double PJ_XYZT.y
+
+        Northing or the Y component of a 3D cartesian system.
+
+    .. c:member:: double PJ_XYZT.z
+
+        Vertical or the Z component of a 3D cartesian system.
+
+    .. c:member:: double PJ_XYZT.t
+
+        Time component.
+
+
+.. c:type:: PJ_UVWT
+
+    Spatiotemporal version of :c:type:`PJ_UVW`.
+
+    .. code-block:: C
+
+        typedef struct { double u, v, w, t; } PJ_UVWT;
+
+    .. c:member:: double PJ_UVWT.e
+
+        First horizontal component.
+
+    .. c:member:: double PJ_UVWT.n
+
+        Second horizontal component.
+
+    .. c:member:: double PJ_UVWT.w
+
+        Vertical component.
+
+    .. c:member:: double PJ_UVWT.t
+
+        Temporal component.
+
+
+Ancillary types for geodetic computations
+--------------------------------------------------------------------------------
+
+
+.. c:type:: PJ_OPK
+
+    Rotations, for instance three euler angles.
+
+    .. code-block:: C
+
+        typedef struct { double o, p, k; } PJ_OPK;
+
+    .. c:member:: double PJ_OPK.o
+
+        First rotation angle, omega.
+
+    .. c:member:: double PJ_OPK.p
+
+        Second rotation angle, phi.
+
+    .. c:member:: double PJ_OPK.k
+
+        Third rotation angle, kappa.
+
+
+Complex coordinate types
+--------------------------------------------------------------------------------
+
+
+.. c:type:: PJ_COORD
+
+    General purpose coordinate union type, applicable in two, three and four dimensions.
+    This is the default coordinate datatype used in PROJ.
+
+    .. code-block:: C
+
+        typedef union {
+            double v[4];
+            PJ_XYZT xyzt;
+            PJ_UVWT uvwt;
+            PJ_LPZT lpzt;
+            PJ_XYZ  xyz;
+            PJ_UVW  uvw;
+            PJ_LPZ  lpz;
+            PJ_XY   xy;
+            PJ_UV   uv;
+            PJ_LP   lp;
+        } PJ_COORD ;
+
+    .. c:member:: double v[4]
+
+        Generic four-dimensional vector.
+
+    .. c:member:: PJ_XYZT PJ_COORD.xyzt
+
+        Spatiotemporal cartesian coordinate.
+
+    .. c:member:: PJ_UVWT PJ_COORD.uvwt
+
+        Spatiotemporal generic coordinate.
+
+    .. c:member:: PJ_LPZT PJ_COORD.lpzt
+
+        Longitude, latitude, vertical and time components.
+
+    .. c:member:: PJ_XYZ PJ_COORD.xyz
+
+        3-dimensional cartesian coordinate.
+
+    .. c:member:: PJ_UVW PJ_COORD.uvw
+
+        3-dimensional generic coordinate.
+
+    .. c:member:: PJ_LPZ PJ_COORD.lpz
+
+        Longitude, latitude and vertical component.
+
+    .. c:member:: PJ_XY PJ_COORD.xy
+
+        2-dimensional cartesian coordinate.
+
+    .. c:member:: PJ_UV PJ_COORD.uv
+
+        2-dimensional generic coordinate.
+
+    .. c:member:: PJ_LP PJ_COORD.lp
+
+        Longitude and latitude.
+
+
+Projection derivatives
+-------------------------------------------------------------------------------
+
+.. c:type:: PJ_FACTORS
+
+    Various cartographic properties, such as scale factors, angular distortion
+    and meridian convergence. Calculated with :c:func:`proj_factors`.
+
+    .. code-block:: C
+
+        typedef struct {
+            double meridional_scale;
+            double parallel_scale;
+            double areal_scale;
+
+            double angular_distortion;
+            double meridian_parallel_angle;
+            double meridian_convergence;
+
+            double tissot_semimajor;
+            double tissot_semiminor;
+
+            double dx_dlam;
+            double dx_dphi;
+            double dy_dlam;
+            double dy_dphi;
+        } PJ_FACTORS;
+
+    .. c:member:: double PJ_FACTORS.meridional_scale
+
+        Meridional scale at coordinate :math:`\left(\lambda,\phi\right)`.
+
+    .. c:member:: double PJ_FACTORS.parallel_scale
+
+        Parallel scale at coordinate :math:`\left(\lambda,\phi\right)`.
+
+    .. c:member:: double PJ_FACTORS.areal_scale
+
+        Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`.
+
+    .. c:member:: double PJ_FACTORS.angular_distortion
+
+        Angular distortion at coordinate :math:`\left(\lambda,\phi\right)`.
+
+    .. c:member:: double PJ_FACTORS.meridian_parallel_angle
+
+         Meridian/parallel angle, :math:`\theta^\prime`, at coordinate :math:`\left(\lambda,\phi\right)`.
+
+     .. c:member:: double PJ_FACTORS.meridian_convergence
+
+        Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`.
+        Sometimes also described as *grid declination*.
+
+
+    .. c:member:: double PJ_FACTORS.tissot_semimajor
+
+        Maximum scale factor.
+
+    .. c:member:: double PJ_FACTORS.tissot_semiminor
+
+        Minimum scale factor.
+
+
+    .. c:member:: double PJ_FACTORS.dx_dlam
+
+        Partial derivative :math:`\frac{\partial x}{\partial \lambda}` of coordinate
+        :math:`\left(\lambda,\phi\right)`.
+
+    .. c:member:: double PJ_FACTORS.dy_dlam
+
+        Partial derivative :math:`\frac{\partial y}{\partial \lambda}` of coordinate
+        :math:`\left(\lambda,\phi\right)`.
+
+    .. c:member:: double PJ_FACTORS.dx_dphi
+
+        Partial derivative :math:`\frac{\partial x}{\partial \phi}` of coordinate
+        :math:`\left(\lambda,\phi\right)`.
+
+    .. c:member:: double PJ_FACTORS.dy_dphi
+
+        Partial derivative :math:`\frac{\partial y}{\partial \phi}` of coordinate
+        :math:`\left(\lambda,\phi\right)`.
+
+List structures
+-------------------------------------------------------------------------------
+
+.. c:type:: PJ_OPERATIONS
+
+    Description a PROJ.4 operation
+
+    .. code-block:: C
+
+        struct PJ_OPERATIONS {
+            char    *id;                 /* operation keyword */
+            PJ *(*proj)(PJ *);           /* operation  entry point */
+            char    * const *descr;      /* description text */
+        };
+
+    .. c:member:: char *id
+
+        Operation keyword.
+
+    .. c:member:: PJ *(*op)(PJ *)
+
+        Operation entry point.
+
+    .. c:member:: char * const *
+
+        Description of operation.
+
+
+.. c:type:: PJ_ELLPS
+
+    Description of ellipsoids defined in PROJ.4
+
+    .. code-block:: C
+
+        struct PJ_ELLPS {
+            char    *id;
+            char    *major;
+            char    *ell;
+            char    *name;
+        };
+
+    .. c:member:: char *id
+
+        Keyword name of the ellipsoid.
+
+    .. c:member:: char *major
+
+        Semi-major axis of the ellipsoid, or radius in case of a sphere.
+
+    .. c:member:: char *ell
+
+        Elliptical parameter, e.g. `rf=298.257` or `b=6356772.2`.
+
+    .. c:member:: char *name
+
+        Name of the ellipsoid
+
+.. c:type:: PJ_UNITS
+
+    Distance units defined in PROJ.
+
+    .. code-block:: C
+
+        struct PJ_UNITS {
+            char    *id;           /* units keyword */
+            char    *to_meter;     /* multiply by value to get meters */
+            char    *name;         /* comments */
+            double   factor;       /* to_meter factor in actual numbers */
+        };
+
+    .. c:member:: char *id
+
+        Keyword for the unit.
+
+    .. c:member:: char *to_meter
+
+        Text representation of the factor that converts a given unit to meters
+
+    .. c:member:: char *name
+
+        Name of the unit.
+
+    .. c:member:: double factor
+
+        Conversion factor that converts the unit to meters.
+
+.. c:type:: PJ_PRIME_MERIDIANS
+
+    Prime meridians defined in PROJ.
+
+    .. code-block:: C
+
+        struct PJ_PRIME_MERIDIANS {
+            char    *id;
+            char    *defn;
+        };
+
+    .. c:member:: char *id
+
+        Keyword for the prime meridian
+
+    .. c:member:: char *def
+
+        Offset from Greenwich in DMS format.
+
+Info structures
+-------------------------------------------------------------------------------
+
+.. c:type:: PJ_INFO
+
+    Struct holding information about the current instance of PROJ. Struct is
+    populated by :c:func:`proj_info`.
+
+    .. code-block:: C
+
+        typedef struct {
+            int           major;
+            int           minor;
+            int           patch;
+            const char   *release;
+            const char   *version;
+            const char   *searchpath;
+        } PJ_INFO;
+
+    .. c:member:: const char *PJ_INFO.release
+
+        Release info. Version number and release date,
+        e.g. "Rel. 4.9.3, 15 August 2016".
+
+    .. c:member:: const char *PJ_INFO.version
+
+        Text representation of the full version number,
+        e.g. "4.9.3".
+
+    .. c:member:: int PJ_INFO.major
+
+        Major version number.
+
+    .. c:member:: int PJ_INFO.minor
+
+        Minor version number.
+
+    .. c:member:: int PJ_INFO.patch
+
+        Patch level of release.
+
+    .. c:member:: const char PJ_INFO.searchpath
+
+        Search path for PROJ. List of directories separated by
+        semicolons (Windows) or colons (non-Windows), e.g.
+        "C:\\Users\\doctorwho;C:\\OSGeo4W64\\share\\proj".
+        Grids and init files are looked for in directories in the search path.
+
+.. c:type:: PJ_PROJ_INFO
+
+    Struct holding information about a :c:type:`PJ` object. Populated by
+    :c:func:`proj_pj_info`. The :c:type:`PJ_PROJ_INFO` object provides a
+    view into the internals of a :c:type:`PJ`, so once the :c:type:`PJ`
+    is destroyed or otherwise becomes invalid, so does the
+    :c:type:`PJ_PROJ_INFO`
+
+    .. code-block:: C
+
+        typedef struct {
+            const char  *id;
+            const char  *description;
+            const char  *definition;
+            int          has_inverse;
+            double       accuracy;
+        } PJ_PROJ_INFO;
+
+    .. c:member:: const char *PJ_PROJ_INFO.id
+
+        Short ID of the operation the :c:type:`PJ` object is based on, that is,
+        what comes afther the ``+proj=`` in a proj-string, e.g. "*merc*".
+
+    .. c:member:: const char *PJ_PROJ_INFO.description
+
+        Long describes of the operation the :c:type:`PJ` object is based on,
+        e.g. "*Mercator    Cyl, Sph&Ell   lat_ts=*".
+
+    .. c:member:: const char *PJ_PROJ_INFO.definition
+
+        The proj-string that was used to create the :c:type:`PJ` object with,
+        e.g. "*+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84*".
+
+    .. c:member:: int PJ_PROJ_INFO.has_inverse
+
+        1 if an inverse mapping of the defined operation exists, otherwise 0.
+
+    .. c:member:: double PJ_PROJ_INFO.accuracy
+
+        Expected accuracy of the transformation. -1 if unknown.
+
+.. c:type:: PJ_GRID_INFO
+
+    Struct holding information about a specific grid in the search path of
+    PROJ. Populated with the function :c:func:`proj_grid_info`.
+
+    .. code-block:: C
+
+        typedef struct {
+            char        gridname[32];
+            char        filename[260];
+            char        format[8];
+            LP          lowerleft;
+            LP          upperright;
+            int         n_lon, n_lat;
+            double      cs_lon, cs_lat;
+        } PJ_GRID_INFO;
+
+    .. c:member:: char PJ_GRID_INFO.gridname[32]
+
+        Name of grid, e.g. "*BETA2007.gsb*".
+
+    .. c:member:: char PJ_GRID_INFO
+
+        Full path of grid file, e.g. *"C:\\OSGeo4W64\\share\\proj\\BETA2007.gsb"*
+
+    .. c:member:: char PJ_GRID_INFO.format[8]
+
+        File format of grid file, e.g. "*ntv2*"
+
+    .. c:member:: LP PJ_GRID_INFO.lowerleft
+
+        Geodetic coordinate of lower left corner of grid.
+
+    .. c:member:: LP PJ_GRID_INFO.upperright
+
+        Geodetic coordinate of upper right corner of grid.
+
+    .. c:member:: int PJ_GRID_INFO.n_lon
+
+        Number of grid cells in the longitudinal direction.
+
+    .. c:member:: int PJ_GRID_INFO.n_lat
+
+        Number of grid cells in the latitudianl direction.
+
+    .. c:member:: double PJ_GRID_INFO.cs_lon
+
+        Cell size in the longitudinal direction. In radians.
+
+    .. c:member:: double PJ_GRID_INFO.cs_lat
+
+        Cell size in the latitudinal direction. In radians.
+
+
+.. c:type:: PJ_INIT_INFO
+
+    Struct holding information about a specific init file in the search path of
+    PROJ. Populated with the function :c:func:`proj_init_info`.
+
+    .. code-block:: C
+
+        typedef struct {
+            char        name[32];
+            char        filename[260];
+            char        version[32];
+            char        origin[32];
+            char        lastupdate[16];
+        } PJ_INIT_INFO;
+
+    .. c:member:: char PJ_INIT_INFO.name[32]
+
+        Name of init file, e.g. "*epsg*".
+
+    .. c:member:: char PJ_INIT_INFO.filename[260]
+
+        Full path of init file, e.g. "*C:\\OSGeo4W64\\share\\proj\\epsg*"
+
+    .. c:member:: char PJ_INIT_INFO.version[32]
+
+        Version number of init-file, e.g. "*9.0.0*"
+
+    .. c:member:: char PJ_INIT_INFO.origin[32]
+
+        Originating entity of the init file, e.g. "*EPSG*"
+
+    .. c:member:: char PJ_INIT_INFO.lastupdate
+
+        Date of last update of the init-file.
diff --git a/docs/source/development/api.rst b/docs/source/development/reference/deprecated.rst
index 98cd2e1d..19f43b41 100644
--- a/docs/source/development/api.rst
+++ b/docs/source/development/reference/deprecated.rst
@@ -1,7 +1,7 @@
 .. _api:
 
 ********************************************************************************
-API
+Deprecated API
 ********************************************************************************
 
 .. contents:: Contents
@@ -143,7 +143,7 @@ definition into a projPJ object suitable for use with other API
 functions. On failure the function will return NULL and set pj_errno.
 The definition should be of the general form
 ``+proj=tmerc +lon_0 +datum=WGS84``. Refer to PROJ.4 documentation and
-the :ref:`parameters` notes for additional detail.
+the :ref:`transformation` notes for additional detail.
 
 Coordinate system objects allocated with ``pj_init_plus()`` should be
 deallocated with ``pj_free()``.
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
new file mode 100644
index 00000000..38ddbde3
--- /dev/null
+++ b/docs/source/development/reference/functions.rst
@@ -0,0 +1,522 @@
+.. _functions:
+
+================================================================================
+Functions
+================================================================================
+
+Threading contexts
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function:: PJ_CONTEXT* proj_context_create(void)
+
+    Create a new threading-context.
+
+    :returns: :c:type:`PJ_CONTEXT*`
+
+.. c:function:: void proj_context_destroy(PJ_CONTEXT *ctx)
+
+    Deallacote a threading-context.
+
+    :param PJ_CONTEXT* ctx: Threading context.
+
+Transformation setup
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition)
+
+    Create a transformation object from a proj-string.
+
+    Example call:
+
+    .. code-block:: C
+
+        PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel");
+
+    The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
+
+    :param PJ_CONTEXT* ctx: Threading context.
+    :param `definition`: Proj-string of the desired transformation.
+    :type `definition`: const char*
+
+
+.. c:function:: PJ* proj_create_argv(PJ_CONTEXT *ctx, int argc, char **argv)
+
+    Create transformation object with argc/argv-style initialization. For this
+    application each parameter in the defining proj-string is an entry in :c:data:`argv`.
+
+    Example call:
+
+    .. code-block:: C
+
+        char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"};
+        PJ* P = proj_create_argv(0, 3, args);
+
+    The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
+
+    :param PJ_CONTEXT* ctx: Threading context
+    :param int argc: Count of arguments in :c:data:`argv`
+    :param char** argv: Vector of strings with proj-string parameters, e.g. ``+proj=merc``
+    :returns: :c:type:`PJ*`
+
+.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to, PJ_AREA *area)
+
+    Create a transformation object that is a pipeline between two known
+    coordinate reference systems.
+
+    :c:data:`srid_from` and :c:data:`srid_to` should be the value part of a ``+init=...`` parameter
+    set, i.e. "epsg:25833" or "IGNF:AMST63". Any projection definition that
+    can be found in a init-file in :envvar:`PROJ_LIB` is a valid input to this function.
+
+    For now the function mimics the cs2cs app: An input and an output CRS is
+    given and coordinates are transformed via a hub datum (WGS84). This
+    transformation strategy is referred to as "early-binding" by the EPSG. The
+    function can be extended to support "late-binding" transformations in the
+    future without affecting users of the function. When the function is extended
+    to the late-binding approach the :c:data:`area` argument will be used. For
+    now it is just a place-holder for a future improved implementation.
+
+    Example call:
+
+    .. code-block:: C
+
+        PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0);
+
+    The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
+
+    :param PJ_CONTEXT* ctx: Threading context.
+    :param `srid_from`: Source SRID.
+    :type `srid_from`: const char*
+    :param `srid_to`: Destination SRID.
+    :type `srid_to`: const char*
+    :param `area`: Descriptor of the desired area for the transformation.
+    :type `area`: PJ_AREA
+    :returns: :c:type:`PJ*`
+
+.. c:function:: PJ* proj_destroy(PJ *P)
+
+    Deallocate a :c:type:`PJ` transformation object.
+
+    :param PJ* P:
+    :returns: :c:type:`PJ*`
+
+.. _coord_trans_functions:
+
+Coordinate transformation
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+
+.. c:function:: PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord)
+
+    Transform a single :c:type:`PJ_COORD` coordinate.
+
+    :param PJ* P:
+    :param `direction`: Transformation direction.
+    :type `direction`: PJ_DIRECTION
+    :param PJ_COORD coord: Coordinate that will be transformed.
+    :returns: :c:type:`PJ_COORD`
+
+
+.. c:function:: size_t proj_trans_generic(PJ *P, PJ_DIRECTION direction, \
+                                          double *x, size_t sx, size_t nx, double *y, \
+                                          size_t sy, size_t ny, double *z, size_t sz, size_t nz, \
+                                          double *t, size_t st, size_t nt)
+
+    Transform a series of coordinates, where the individual coordinate dimension
+    may be represented by an array that is either
+
+        1. fully populated
+        2. a null pointer and/or a length of zero, which will be treated as a
+           fully populated array of zeroes
+        3. of length one, i.e. a constant, which will be treated as a fully
+           populated array of that constant value
+
+    The strides, :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`,
+    represent the step length, in bytes, between
+    consecutive elements of the corresponding array. This makes it possible for
+    :c:func:`proj_transform` to handle transformation of a large class of application
+    specific data structures, without necessarily understanding the data structure
+    format, as in:
+
+    .. code-block:: C
+
+        typedef struct {
+            double x, y;
+            int quality_level;
+            char surveyor_name[134];
+        } XYQS;
+
+        XYQS survey[345];
+        double height = 23.45;
+        size_t stride = sizeof (XYQS);
+
+        ...
+
+        proj_trans_generic (
+            P, PJ_INV, sizeof(XYQS),
+            &(survey[0].x), stride, 345,  /*  We have 345 eastings  */
+            &(survey[0].y), stride, 345,  /*  ...and 345 northings. */
+            &height, 1,                   /*  The height is the constant  23.45 m */
+            0, 0                          /*  and the time is the constant 0.00 s */
+        );
+
+    This is similar to the inner workings of the deprecated pj_transform function, but the
+    stride functionality has been generalized to work for any size of basic unit,
+    not just a fixed number of doubles.
+
+    In most cases, the stride will be identical for x, y, z, and t, since they will
+    typically be either individual arrays (stride = sizeof(double)), or strided
+    views into an array of application specific data structures (stride = sizeof (...)).
+
+    But in order to support cases where :c:data:`x`, :c:data:`y`, :c:data:`z`,
+    and :c:data:`t` come from heterogeneous sources, individual strides,
+    :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, are used.
+
+    .. note:: Since :c:func:`proj_transform` does its work *in place*, this means that even the
+              supposedly constants (i.e. length 1 arrays) will return from the call in altered
+              state. Hence, remember to reinitialize between repeated calls.
+
+    :param PJ* P: Transformation object
+    :param `direction`: Transformation direction
+    :type `PJ_DIRECTION`:
+    :param double* x: Array of x-coordinates
+    :param double* y: Array of y-coordinates
+    :param double* z: Array of z-coordinates
+    :param double* t: Array of t-coordinates
+    :param size_t sx: Step lenght, in bytes, between consecutive elements of the corresponding array
+    :param size_t nx: Number of elements in the corresponding array
+    :param size_t sy: Step lenght, in bytes, between consecutive elements of the corresponding array
+    :param size_t nv: Number of elements in the corresponding array
+    :param size_t sz: Step lenght, in bytes, between consecutive elements of the corresponding array
+    :param size_t nz: Number of elements in the corresponding array
+    :param size_t st: Step lenght, in bytes, between consecutive elements of the corresponding array
+    :param size_t nt: Number of elements in the corresponding array
+    :returns: Number of transformations succesfully completed
+
+
+
+.. c:function:: size_t proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord)
+
+    Batch transform an array of :c:type:`PJ_COORD`.
+
+    :param PJ* P:
+    :param `direction`: Transformation direction
+    :type `direction`: PJ_DIRECTION
+    :param size_t n: Number of cordinates in :c:data:`coord`
+    :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number
+
+
+Error reporting
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function:: int proj_errno(PJ *P)
+
+    Get a reading of the current error-state of :c:data:`P`. An non-zero error
+    codes indicates an error either with the transformation setup or during a
+    transformation.
+
+    :param: PJ* P: Transformation object.
+
+    :returns: :c:type:`int`
+
+.. c:function:: void proj_errno_set(PJ *P, int err)
+
+Change the error-state of :c:data:`P` to `err`.
+
+    :param PJ* P: Transformation object.
+    :param int err: Error number.
+
+.. c:function:: int proj_errno_reset(PJ *P)
+
+    Clears the error number in :c:data:`P`, and bubbles it up to the context.
+
+    Example:
+
+    .. code-block:: C
+
+        void foo (PJ *P) {
+            int last_errno = proj_errno_reset (P);
+
+            do_something_with_P (P);
+
+            /* failure - keep latest error status */
+            if (proj_errno(P))
+                return;
+            /* success - restore previous error status */
+            proj_errno_restore (P, last_errno);
+            return;
+        }
+
+    :param: PJ* P: Transformation object.
+
+    :returns: :c:type:`int` Returns the previous value of the errno, for convenient reset/restore operations.
+
+.. c:function:: void proj_errno_restore(PJ *P, int err)
+
+    Reduce some mental impedance in the canonical reset/restore use case:
+    Basically, :c:func:`proj_errno_restore()` is a synonym for
+    :c:func:`proj_errno_set()`, but the use cases are very different:
+    *set* indicate an error to higher level user code, *restore* passes previously
+    set error indicators in case of no errors at this level.
+
+    Hence, although the inner working is identical, we provide both options,
+    to avoid some rather confusing real world code.
+
+    See usage example under :c:func:`proj_errno_reset`
+
+    :param PJ* P: Transformation object.
+    :param int err: Error code.
+
+
+
+Info functions
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function:: PJ_INFO proj_info(void)
+
+    Get information about the current instance of the PROJ library.
+
+    :returns: :c:type:`PJ_INFO`
+
+.. c:function:: PJ_PROJ_INFO proj_pj_info(const PJ *P)
+
+    Get information about a specific transformation object, :c:data:`P`.
+
+    :param `P`: Transformation object
+    :type `P`: const PJ*
+    :returns: :c:type:`PJ_PROJ_INFO`
+
+.. c:function:: PJ_GRID_INFO proj_grid_info(const char *gridname)
+
+    Get information about a specific grid.
+
+    :param `gridname`: Gridname in the PROJ searchpath
+    :type `gridname`: const char*
+    :returns: :c:type:`PJ_GRID_INFO`
+
+.. c:function:: PJ_INIT_INFO proj_init_info(const char *initname)
+
+    Get information about a specific init file.
+
+    :param `initname`: Init file in the PROJ searchpath
+    :type `initname`: const char*
+    :returns: :c:type:`PJ_INIT_INFO`
+
+Lists
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function::  const PJ_OPERATIONS* proj_list_operations(void)
+
+    Get a pointer to an array of all operations in PROJ. The last entry
+    of the returned array is a NULL-entry. The array is statically allocated
+    and does not need to be freed after use.
+
+    Print a list of all operations in PROJ:
+
+    .. code-block:: C
+
+        PJ_OPERATIONS *ops;
+        for (ops = proj_list_operations(); ops->id; ++ops)
+            printf("%s\n", ops->id);
+
+
+    :returns: :c:type:`PJ_OPERATIONS*`
+
+.. c:function:: const PJ_ELLPS* proj_list_ellps(void)
+
+    Get a pointer to an array of ellipsoids defined in PROJ. The last entry
+    of the returned array is a NULL-entry. The array is statically allocated
+    and does not need to be freed after use.
+
+    :returns: :c:type:`PJ_ELLPS*`
+
+.. c:function:: const PJ_UNITS* proj_list_units(void)
+
+    Get a pointer to an array of distance units defined in PROJ. The last
+    entry of the returned array is a NULL-entry. The array is statically
+    allocated and does not need to be freed after use.
+
+    :returns: :c:type:`PJ_UNITS*`
+
+.. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void)
+
+    Get a pointer to an array of prime meridians defined in PROJ. The last
+    entry of the returned array is a NULL-entry. The array is statically
+    allocated and does not need to be freed after use.
+
+    :returns: :c:type:`PJ_PRIME_MERIDIANS*`
+
+Distances
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b)
+
+    Calculate geodesic distance between two points in geodetic coordinates.
+
+    :param PJ* P: Transformation object
+    :param PJ_COORD a: Coordinate of first point
+    :param PJ_COORD b: Coordinate of second point
+    :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
+
+.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b)
+
+    Calculate geodesic distance between two points in geodetic coordinates.
+
+    :param PJ* P: Transformation object
+    :param PJ_COORD a: Coordinate of first point
+    :param PJ_COORD b: Coordinate of second point
+    :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
+
+.. c:function:: double proj_xy_dist(PJ_COORD a, PJ_COORD b)
+
+    Calculate 2-dimensional euclidean between two projected coordinates.
+
+    :param PJ_COORD a: First coordinate
+    :param PJ_COORD b: Second coordinate
+    :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
+
+.. c:function:: double proj_xyz_dist(PJ_COORD a, PJ_COORD b)
+
+    Calculate 3-dimensional euclidean between two projected coordinates.
+
+    :param PJ_COORD a: First coordinate
+    :param PJ_COORD b: Second coordinate
+    :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
+
+
+Various
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t)
+
+    Initializer for the :c:type:`PJ_COORD` union. The function is
+    shorthand for the otherwise convoluted assignment.
+    Equivalent to
+
+    .. code-block:: C
+
+        PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}};
+
+    or
+
+    .. code-block:: C
+
+        PJ_COORD c;
+        // Assign using the PJ_XYZT struct in the union
+        c.xyzt.x = 10.0;
+        c.xyzt.y = 20.0;
+        c.xyzt.z = 30.0;
+        c.xyzt.t = 40.0;
+
+    Since :c:type:`PJ_COORD` is a union of structs, the above assignment can
+    also be expressed in terms of the other types in the union, e.g.
+    :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`.
+
+
+    :param double x: 1st component in a :c:type:`PJ_COORD`
+    :param double y: 2nd component in a :c:type:`PJ_COORD`
+    :param double z: 3rd component in a :c:type:`PJ_COORD`
+    :param double t: 4th component in a :c:type:`PJ_COORD`
+    :returns: :c:type:`PJ_COORD`
+
+
+.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coo)
+
+    Measure internal consistency of a given transformation. The function
+    performs :c:data:`n` round trip transformations starting in either
+    the forward or reverse :c:data:`direction`. Returns the euclidean
+    distance of the starting point :c:data:`coo` and the resulting
+    coordinate after :c:data:`n` iterations back and forth.
+
+    :param PJ* P:
+    :type `P`: const PJ*
+    :param `direction`: Starting direction of transformation
+    :type `direction`: PJ_DIRECTION
+    :param int n: Number of roundtrip transformations
+    :param PJ_OBS obs: Input coordinate
+    :returns: :c:type:`double` Distance between original coordinate and the \
+              resulting coordinate after :c:data:`n` transformation iterations.
+
+.. c:function:: PJ_FACTORS proj_factors(PJ *P, PJ_COORD lp)
+
+    Calculate various cartographic properties, such as scale factors, angular
+    distortion and meridian convergence. Depending on the underlying projection
+    values will be calculated either numerically (default) or analytically.
+
+    The function also calculates the partial derivatives of the given
+    coordinate.
+
+    :param `P`: Transformation object
+    :type `P`: const PJ*
+    :param `lp`: Geodetic coordinate
+    :type `lp`: const PJ_COORD
+    :returns: :c:type:`PJ_FACTORS`
+
+.. c:function:: double proj_torad(double angle_in_degrees)
+
+    Convert degrees to radians.
+
+    :param double angle_in_degrees: Degrees
+    :returns: :c:type:`double` Radians
+
+.. c:function:: double proj_todeg(double angle_in_radians)
+
+    Convert radians to degrees
+
+    :param double angle_in_radians: Radians
+    :returns: :c:type:`double` Degrees
+
+.. c:function:: double proj_dmstor(const char *is, char **rs)
+
+    Convert string of degrees, minutes and seconds to radians.
+    Works similarly to the C standard library function :c:func:`strtod`.
+
+    :param `is`: Value to be converted to radians
+    :type `is`: const  char*
+    :param `rs`: Reference to an already allocated char*, whose value is \
+                 set by the function to the next character in :c:data:`is` \
+                 after the numerical value.
+
+.. c:function:: char *proj_rtodms(char *s, double r, int pos, int neg)
+
+    Convert radians to string representation of degrees, minutes and seconds.
+
+    :param char* s: Buffer that holds the output string
+    :param double r: Value to convert to dms-representation
+    :param int pos: Character denoting positive direction, typically `'N'` or `'E'`.
+    :param int neg: Character denoting negative direction, typically `'S'` or `'W'`.
+    :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`)
+
+
+.. c:function:: PJ_COORD proj_geocentric_latitude(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo)
+
+    Convert from geographical latitude to geocentric latitude.
+
+    :param `P`: Transformation object
+    :type `P`: const PJ*
+    :param `direction`: Starting direction of transformation
+    :type `direction`: PJ_DIRECTION
+    :param `coo`: Coordinate
+    :type `coo`: PJ_COORD
+    :returns: :c:type:`PJ_COORD` Converted coordinate
+
+
+.. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir)
+
+    Check if a operation expects angular input.
+
+    :param `P`: Transformation object
+    :type `P`: const PJ*
+    :param `direction`: Starting direction of transformation
+    :type `direction`: PJ_DIRECTION
+    :returns: :c:type:`int` 1 if angular input is expected, otherwise 0
+
+.. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir)
+
+   Check if an operation returns angular output.
+
+    :param `P`: Transformation object
+    :type `P`: const PJ*
+    :param `direction`: Starting direction of transformation
+    :type `direction`: PJ_DIRECTION
+    :returns: :c:type:`int` 1 if angular output is returned, otherwise 0
+
diff --git a/docs/source/development/reference/index.rst b/docs/source/development/reference/index.rst
new file mode 100644
index 00000000..9e92384c
--- /dev/null
+++ b/docs/source/development/reference/index.rst
@@ -0,0 +1,12 @@
+.. _reference:
+
+================================================================================
+Reference
+================================================================================
+
+.. toctree::
+   :maxdepth: 1
+
+   datatypes
+   functions
+   deprecated
diff --git a/docs/source/development/threads.rst b/docs/source/development/threads.rst
index 33072408..674f4bd1 100644
--- a/docs/source/development/threads.rst
+++ b/docs/source/development/threads.rst
@@ -4,12 +4,7 @@
 Threads
 ================================================================================
 
-.. contents:: Contents
-   :depth: 3
-   :backlinks: none
-
-
-This page is about efforts to make PROJ.4 thread safe.
+This page is about efforts to make PROJ thread safe.
 
 Key Thread Safety Issues
 --------------------------------------------------------------------------------
@@ -19,14 +14,14 @@ Key Thread Safety Issues
   introduction of the projCtx execution context.
 * the datum shift using grid files uses globally shared lists of loaded grid
   information. Access to this has been made safe in 4.7.0 with the introduction
-  of a proj.4 mutex used to protect access to these memory structures (see
+  of a PROJ mutex used to protect access to these memory structures (see
   pj_mutex.c).
 
 projCtx
 --------------------------------------------------------------------------------
 
 Primarily in order to avoid having pj_errno as a global variable, a "thread
-context" structure has been introduced into a variation of the PROJ.4 API for
+context" structure has been introduced into a variation of the PROJ API for
 the 4.8.0 release.  The pj_init() and pj_init_plus() functions now have context
 variations called pj_init_ctx() and pj_init_plus_ctx() which take a projections
 context.
@@ -73,7 +68,7 @@ src/multistresstest.c
 --------------------------------------------------------------------------------
 
 A small multi-threaded test program has been written (src/multistresstest.c)
-for testing multithreaded use of PROJ.4.  It performs a series of reprojections
+for testing multithreaded use of PROJ.  It performs a series of reprojections
 to setup a table expected results, and then it does them many times in several
 threads to confirm that the results are consistent.  At this time this program
 is not part of the builds but it can be built on linux like:
diff --git a/docs/source/development/transformations.rst b/docs/source/development/transformations.rst
new file mode 100644
index 00000000..b03ce368
--- /dev/null
+++ b/docs/source/development/transformations.rst
@@ -0,0 +1,7 @@
+.. _dev_transformations:
+
+================================================================================
+Transformations
+================================================================================
+
+