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

Docs for the upcoming release

4 files changed, 1550 insertions, 0 deletions

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/reference/deprecated.rst b/docs/source/development/reference/deprecated.rst
new file mode 100644
index 00000000..19f43b41
--- /dev/null
+++ b/docs/source/development/reference/deprecated.rst
@@ -0,0 +1,270 @@
+.. _api:
+
+********************************************************************************
+Deprecated API
+********************************************************************************
+
+.. contents:: Contents
+   :depth: 3
+   :backlinks: none
+
+Introduction
+------------
+
+Procedure ``pj_init()`` selects and initializes a cartographic
+projection with its argument control parameters. ``argc`` is the number
+of elements in the array of control strings argv that each contain
+individual cartographic control keyword assignments (+ proj arguments).
+The list must contain at least the proj=projection and Earth’s radius or
+elliptical parameters. If the initialization of the projection is
+successful a valid address is returned otherwise a NULL value.
+
+The ``pj_init_plus()`` function operates similarly to ``pj_init()`` but
+takes a single string containing the definition, with each parameter
+prefixed with a plus sign. For example
+``+proj=utm +zone=11 +ellps=WGS84``.
+
+Once initialization is performed either forward or inverse projections
+can be performed with the returned value of ``pj_init()`` used as the
+argument proj. The argument structure projUV values u and v contain
+respective longitude and latitude or x and y. Latitude and longitude are
+in radians. If a projection operation fails, both elements of projUV are
+set to ``HUGE_VAL`` (defined in ``math.h``).
+
+Note: all projections have a forward mode, but some do not have an
+inverse projection. If the projection does not have an inverse the
+projPJ structure element inv will be ``NULL``.
+
+The ``pj_transform`` function may be used to transform points between
+the two provided coordinate systems. In addition to converting between
+cartographic projection coordinates and geographic coordinates, this
+function also takes care of datum shifts if possible between the source
+and destination coordinate system. Unlike ``pj_fwd()`` and ``pj_inv()``
+it is also allowable for the coordinate system definitions
+``(projPJ *)`` to be geographic coordinate systems (defined as
+``+proj=latlong``).
+The x, y and z arrays contain the input values of the points, and are replaced with the output values.
+The function returns zero on success, or the error number (also in ``pj_errno``)
+on failure.
+
+Memory associated with the projection may be freed with ``pj_free()``.
+
+Example
+-------
+
+The following program reads latitude and longitude values in decimal
+degrees, performs Mercator projection with a Clarke 1866 ellipsoid and a
+33° latitude of true scale and prints the projected cartesian values in
+meters:
+
+.. code::
+
+    #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")) )
+            exit(1);
+         if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) )
+            exit(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);
+         }
+         exit(0);
+    }
+
+
+For this program, an input of ``-16 20.25`` would give a result of
+``-1495284.21 1920596.79``.
+
+API Functions
+-------------
+
+pj_transform
+============
+
+::
+
+    int pj_transform( projPJ srcdefn,
+                      projPJ dstdefn,
+                      long point_count,
+                      int point_offset,
+                      double *x,
+                      double *y,
+                      double *z );
+
+
+Transform the x/y/z points from the source coordinate system to the
+destination coordinate system.
+
+``srcdefn``: source (input) coordinate system.
+
+``dstdefn``: destination (output) coordinate system.
+
+``point_count``: the number of points to be processed (the size of the
+x/y/z arrays).
+
+``point_offset``: the step size from value to value (measured in
+doubles) within the x/y/z arrays - normally 1 for a packed array. May be
+used to operate on xyz interleaved point arrays.
+
+``x``/``y``/``z``: The array of X, Y and Z coordinate values passed as
+input, and modified in place for output. The Z may optionally be NULL.
+
+``return``: The return is zero on success, or a PROJ.4 error code.
+
+The ``pj_transform()`` function transforms the passed in list of points
+from the source coordinate system to the destination coordinate system.
+Note that geographic locations need to be passed in radians, not decimal
+degrees, and will be returned similarly. The ``z`` array may be passed
+as NULL if Z values are not available.
+
+If there is an overall failure, an error code will be returned from the
+function. If individual points fail to transform - for instance due to
+being over the horizon - then those x/y/z values will be set to
+``HUGE_VAL`` on return. Input values that are ``HUGE_VAL`` will not be
+transformed.
+
+
+pj_init_plus
+============
+
+::
+
+   projPJ pj_init_plus(const char *definition);
+
+This function converts a string representation of a coordinate system
+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:`transformation` notes for additional detail.
+
+Coordinate system objects allocated with ``pj_init_plus()`` should be
+deallocated with ``pj_free()``.
+
+
+pj_free
+=======
+
+::
+
+    void pj_free( projPJ pj );
+
+Frees all resources associated with pj.
+
+
+pj_is_latlong
+=============
+
+::
+
+    int pj_is_latlong( projPJ pj );
+
+Returns TRUE if the passed coordinate system is geographic
+(``proj=latlong``).
+
+
+pj_is_geocent
+=============
+
+::
+
+    int pj_is_geocent( projPJ pj );``
+
+Returns TRUE if the coordinate system is geocentric (``proj=geocent``).
+
+pj_get_def
+==========
+
+::
+
+    char *pj_get_def( projPJ pj, int options);``
+
+Returns the PROJ.4 initialization string suitable for use with
+``pj_init_plus()`` that would produce this coordinate system, but with
+the definition expanded as much as possible (for instance ``+init=`` and
+``+datum=`` definitions).
+
+pj_latlong_from_proj
+====================
+
+::
+
+    projPJ pj_latlong_from_proj( projPJ pj_in );``
+
+Returns a new coordinate system definition which is the geographic
+coordinate (lat/long) system underlying ``pj_in``.
+
+pj_set_finder
+==============
+
+::
+
+    void pj_set_finder( const char *(*new_finder)(const char *) );``
+
+Install a custom function for finding init and grid shift files.
+
+pj_set_searchpath
+=================
+
+::
+
+    void pj_set_searchpath ( int count, const char **path );``
+
+Set a list of directories to search for init and grid shift files.
+
+
+pj_deallocate_grids
+===================
+
+::
+
+    void pj_deallocate_grids( void );``
+
+Frees all resources associated with loaded and cached datum shift grids.
+
+
+pj_strerrno
+===========
+
+::
+
+    char *pj_strerrno( int );``
+
+Returns the error text associated with the passed in error code.
+
+pj_get_errno_ref
+================
+
+::
+
+    int *pj_get_errno_ref( void );``
+
+Returns a pointer to the global pj\_errno error variable.
+
+pj_get_release
+==============
+
+::
+
+    const char *pj_get_release( void );``
+
+Returns an internal string describing the release version.
+
+Obsolete Functions
+~~~~~~~~~~~~~~~~~~
+
+``XY pj_fwd( LP lp, PJ *P );``
+
+``LP pj_inv( XY xy, PJ *P );``
+
+``projPJ pj_init(int argc, char **argv);``
+
+.. _more info: pj_transform
+
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