317 files changed, 3735 insertions, 580 deletions

diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
new file mode 100644
index 00000000..b82d2881
--- /dev/null
+++ b/docs/source/_static/theme_overrides.css
@@ -0,0 +1,57 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
+
+/* Align equation numbers to the right of the equation, not above */
+div.math {
+    position: relative;
+    padding-right: 2.5em;
+}
+.eqno {
+    height: 100%;
+    position: absolute;
+    right: 0;
+    padding-left: 5px;
+    padding-bottom: 5px;
+}
+.eqno:before {
+    /* Force vertical alignment of number */
+    display: inline-block;
+    height: 100%;
+    vertical-align: middle;
+    content: "";
+}
+.eqno .headerlink {
+    display: none;
+    visibility: hidden;
+    font-size: 14px;
+    padding-left: .3em;
+}
+.eqno:hover .headerlink {
+    display: inline-block;
+    visibility: hidden;
+    margin-right: -1.05em;
+}
+.eqno .headerlink:after {
+    visibility: visible;
+    content: "\f0c1";
+    font-family: FontAwesome;
+    display: inline-block;
+    margin-left: -.9em;
+}
+/* Make responsive */
+.MathJax_Display {
+    max-width: 100%;
+    overflow-x: auto;
+    overflow-y: hidden;
+}
diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst
deleted file mode 100644
index 1baaf1c5..00000000
--- a/docs/source/apps/index.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-.. _apps:
-
-================================================================================
-Applications
-================================================================================
-
-The  proj  program  is  limited  to   converting
-between  geographic  and  projection coordinates
-within one datum.
-
-The cs2cs program operates similarly, but allows
-translation  between any pair of definable coor-
-dinate  systems,  including  support  for  datum
-translation.
-
-The geod program provides the ability to compute
-geodesic (Great Circle) computations.
-
-
-
-.. toctree::
-   :maxdepth: 1
-
-   proj
-   cs2cs
-   geod
-
diff --git a/docs/source/conf.py b/docs/source/conf.py
index cbd02f10..af9d24da 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# proj.4 documentation build configuration file, created by
+# PROJ.4 documentation build configuration file, created by
 # sphinx-quickstart on Wed Feb 24 10:47:15 2016.
 #
 # This file is execfile()d with the current directory set to its
@@ -14,6 +14,7 @@
 
 import sys
 import os
+import datetime
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -47,8 +48,9 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'proj.4'
-copyright = u'1986?-2016'
+project = u'PROJ.4'
+now = datetime.datetime.now()
+copyright = u'1983-{0}'.format(now.year)
 author = u'Gerald Evenden, Frank Warmerdam, and others'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -56,9 +58,9 @@ author = u'Gerald Evenden, Frank Warmerdam, and others'
 # built documents.
 #
 # The short X.Y version.
-version = u'4.9.3'
+version = u'5.0.0'
 # The full version, including alpha/beta/rc tags.
-release = u'4.9.3'
+release = u'5.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -140,7 +142,13 @@ html_theme_options = {}
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['_static']
+
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+    ],
+}
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -230,7 +238,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'proj4.tex', u'proj.4 Documentation',
+    (master_doc, 'proj4.tex', u'PROJ.4 Documentation',
      u'Gerald Evenden', 'manual'),
 ]
 
@@ -260,7 +268,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'proj4', u'proj.4 Documentation',
+    (master_doc, 'proj4', u'PROJ.4 Documentation',
      [author], 1)
 ]
 
@@ -274,7 +282,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'proj4', u'proj.4 Documentation',
+    (master_doc, 'proj4', u'PROJ.4 Documentation',
      author, 'proj4', 'One line description of project.',
      'Miscellaneous'),
 ]
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
new file mode 100644
index 00000000..e7f9101e
--- /dev/null
+++ b/docs/source/contributing.rst
@@ -0,0 +1,242 @@
+.. _contributing:
+
+===========================
+Contributing
+===========================
+
+PROJ.4 has a wide and varied user base. Some are highly skilled
+geodesists with a deep knowledge of map projections and reference
+systems, some are GIS software developers and others are GIS users. All
+users, regardless of the profession or skill level, has the ability to
+contribute to PROJ.4. Here's a few suggestion on how:
+
+-  Help PROJ.4-users that is less experienced than yourself.
+-  Write a bug report
+-  Request a new feature
+-  Write documentation for your favorite map projection
+-  Fix a bug
+-  Implement a new feature
+
+In the following sections you can find some guidelines on how to
+contribute. As PROJ.4 is managed on GitHub most contributions require
+that you have a GitHub account. Familiarity with
+`issues <https://guides.github.com/features/issues/>`__ and the `GitHub
+Flow <https://guides.github.com/introduction/flow/>`__ is an advantage.
+
+Help a fellow PROJ.4 user
+-------------------------
+
+The main forum for support for PROJ.4 is the mailing list. You can
+subscribe to the mailing list
+`here <http://lists.maptools.org/mailman/listinfo/proj>`__ and read the
+archive `here <http://lists.maptools.org/pipermail/proj/>`__.
+
+If you have questions about the usage of PROJ.4 the mailing list is also
+the place to go. Please *do not* use the GitHub issue tracker as a
+support forum. Your question is much more likely to be answered on the
+mailing list, as many more people follow that than the issue tracker.
+
+Adding bug reports
+------------------
+
+Bug reports are handled in the `issue
+tracker <https://github.com/OSGeo/proj.4/issues>`__ on PROJ.4's home on
+GitHub. Writing a good bug report is not easy. But fixing a poorly
+documented bug is not easy either, so please put in the effort it takes
+to create a thorough bug report.
+
+A good bug report includes at least:
+
+-  A title that quickly explains the problem
+-  A description of the problem and how it can be reproduced
+-  Version of PROJ.4 being used
+-  Version numbers of any other relevant software being used, e.g.
+   operating system
+-  A description of what already has been done to solve the problem
+
+The more information that is given up front, the more likely it is that
+a developer will find interest in solving the problem. You will probably
+get follow-up questions after submitting a bug report. Please answer
+them in a timely manner if you have an interest in getting the issue
+solved.
+
+Finally, please only submit bug reports that are actually related to
+PROJ.4. If the issue materializes in software that uses PROJ.4 it is
+likely a problem with that particular software. Make sure that it
+actually is a PROJ.4 problem before you submit an issue. If you can
+reproduce the problem only by using tools from PROJ.4 it is definitely a
+problem with PROJ.4.
+
+Feature requests
+----------------
+
+Got an idea for a new feature in PROJ.4? Submit a thorough description
+of the new feature in the `issue
+tracker <https://github.com/OSGeo/proj.4/issues>`__. Please include any
+technical documents that can help the developer make the new feature a
+reality. An example of this could be a publicly available academic paper
+that describes a new projection. Also, including a numerical test case
+will make it much easier to verify that an implementation of your
+requested feature actually works as you expect.
+
+Note that not all feature requests are accepted.
+
+Write documentation
+-------------------
+
+PROJ.4 is in dire need of better documentation. Any contributiions of
+documentation are greatly appreaciated. The PROJ.4 documentation is
+available on `proj4.org <ttp://proj4.org>`__. The website is generated
+with `Sphinx <http://www.sphinx-doc.org/en/stable/>`__. Contributions to
+the documentation should be made as `Pull
+Requests <https://github.com/OSGeo/proj.4/pulls>`__ on GitHub.
+
+If you intend to document one of PROJ.4's supported projections please
+use the `Mercator projection <http://proj4.org/projections/merc.html>`__
+as a template.
+
+Code contributions
+------------------
+
+Code contributions can be either bug fixes or new features. The process
+is the same for both, so they will be discussed together in this
+section.
+
+Making Changes
+~~~~~~~~~~~~~~
+
+-  Create a topic branch from where you want to base your work.
+-  You usually should base your topic branch off of the master branch.
+-  To quickly create a topic branch: ``git checkout -b my-topic-branch``
+-  Make commits of logical units.
+-  Check for unnecessary whitespace with ``git diff --check`` before
+   committing.
+-  Make sure your commit messages are in the `proper
+   format <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`__.
+-  Make sure you have added the necessary tests for your changes.
+-  Make sure that all tests pass
+
+Submitting Changes
+~~~~~~~~~~~~~~~~~~
+
+-  Push your changes to a topic branch in your fork of the repository.
+-  Submit a pull request to the PROJ.4 repository in the OSGeo
+   organization.
+-  If your pull request fixes/references an issue, include that issue
+   number in the pull request. For example:
+
+::
+
+    Wiz the bang
+
+    Fixes #123.
+
+-  PROJ.4 developers will look at your patch and take an appropriate
+   action.
+
+Coding conventions
+~~~~~~~~~~~~~~~~~~
+
+Programming language
+^^^^^^^^^^^^^^^^^^^^
+
+PROJ.4 is developed strictly in ANSI C 89.
+
+Coding style
+^^^^^^^^^^^^
+
+We don't enforce any particular coding style, but please try to keep it
+as simple as possible. If improving existing code, please try to conform
+with the style of the locally surrounding code.
+
+Whitespace
+^^^^^^^^^^
+
+Throughout the PROJ.4 code base you will see differing whitespace use.
+The general rule is to keep whitespace in whatever form it is in the
+file you are currently editing. If the file has a mix of tabs and space
+please convert the tabs to space in a separate commit before making any
+other changes. This makes it a lot easier to see the changes in diffs
+when evaulating the changed code. New files should use spaces as
+whitespace.
+
+File names
+^^^^^^^^^^
+
+Files in which projections are implemented are prefixed with an
+upper-case ``PJ_`` and most other files are prefixed with lower-case
+``pj_``. Some file deviate from this pattern, most of them dates back to
+the very early releases of PROJ.4. New contributions should follow the
+pj-prefix pattern. Unless there are obvious reasons not to.
+
+Legalese
+~~~~~~~~
+
+Commiters are the front line gatekeepers to keep the code base clear of
+improperly contributed code. It is important to the PROJ.4 users,
+developers and the OSGeo foundation to avoid contributing any code to
+the project without it being clearly licensed under the project license.
+
+Generally speaking the key issues are that those providing code to be
+included in the repository understand that the code will be released
+under the MIT/X license, and that the person providing the code has the
+right to contribute the code. For the commiter themselves understanding
+about the license is hopefully clear. For other contributors, the
+commiter should verify the understanding unless the commiter is very
+comfortable that the contributor understands the license (for instance
+frequent contributors).
+
+If the contribution was developed on behalf of an employer (on work
+time, as part of a work project, etc) then it is important that an
+appropriate representative of the employer understand that the code will
+be contributed under the MIT/X license. The arrangement should be
+cleared with an authorized supervisor/manager, etc.
+
+The code should be developed by the contributor, or the code should be
+from a source which can be rightfully contributed such as from the
+public domain, or from an open source project under a compatible
+license.
+
+All unusual situations need to be discussed and/or documented.
+
+Commiters should adhere to the following guidelines, and may be
+personally legally liable for improperly contributing code to the source
+repository:
+
+-  Make sure the contributor (and possibly employer) is aware of the
+   contribution terms.
+-  Code coming from a source other than the contributor (such as adapted
+   from another project) should be clearly marked as to the original
+   source, copyright holders, license terms and so forth. This
+   information can be in the file headers, but should also be added to
+   the project licensing file if not exactly matching normal project
+   licensing (COPYING).
+-  Existing copyright headers and license text should never be stripped
+   from a file. If a copyright holder wishes to give up copyright they
+   must do so in writing to the foundation before copyright messages are
+   removed. If license terms are changed it has to be by agreement
+   (written in email is ok) of the copyright holders.
+-  Code with licenses requiring credit, or disclosure to users should be
+   added to COPYING.
+-  When substantial contributions are added to a file (such as
+   substantial patches) the author/contributor should be added to the
+   list of copyright holders for the file.
+-  If there is uncertainty about whether a change is proper to
+   contribute to the code base, please seek more information from the
+   project steering committee, or the foundation legal counsel.
+
+Additional Resources
+--------------------
+
+-  `General GitHub documentation <http://help.github.com/>`__
+-  `GitHub pull request
+   documentation <https://help.github.com/articles/about-pull-requests/>`__
+
+Acknowledgements
+----------------
+
+The *code contribution* section of this CONTRIBUTING file is inspired by
+`PDAL's <https://github.com/PDAL/PDAL/blob/master/CONTRIBUTING.md>`__
+and the *legalese* section is modified from `GDAL contributer
+guidelines <https://trac.osgeo.org/gdal/wiki/rfc3_commiters>`__
+
diff --git a/docs/source/development/bindings.rst b/docs/source/development/bindings.rst
index a1c2a9e0..80babcb2 100644
--- a/docs/source/development/bindings.rst
+++ b/docs/source/development/bindings.rst
@@ -4,37 +4,37 @@
 Language bindings
 ********************************************************************************
 
-Proj.4 bindings are available for a number of different development platforms.
+PROJ.4 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.4)
 
 
 Ruby
 =======
 
 `proj4rb <http://proj4rb.rubyforge.org>`_:
-Bindings for proj.4 in ruby
+Bindings for PROJ.4 in ruby
 
 TCL
 ========
 `proj4tcl <http://wiki.tcl.tk/41270>`_:
-Bindings for proj.4 in tcl (critcl source)
+Bindings for PROJ.4 in tcl (critcl source)
 
 MySQL
 =====
 
 `fProj4 <http://sourceforge.net/projects/mysqlscientific/files/fPROJ4/>`_:
-Bindings for proj.4 in MySQL
+Bindings for PROJ.4 in MySQL
 
 
 Excel
 ========
 
 `proj.xll <https://github.com/jbuonagurio/proj.xll>`_:
-Excel add-in for proj.4 map projections
+Excel add-in for PROJ.4 map projections
 
 Visual Basic
 ==================
diff --git a/docs/source/projections/airy.rst b/docs/source/development/errorhandling.rst
index 307af3e3..58199e3f 100644
--- a/docs/source/projections/airy.rst
+++ b/docs/source/development/errorhandling.rst
@@ -1,10 +1,7 @@
-.. _airy:
+.. _errorhandling:
 
-********************************************************************************
-Airy
-********************************************************************************
+================================================================================
+Error handling
+================================================================================
 
-.. image:: ./images/airy.png
-   :scale: 50%
-   :alt:   Airy  
 
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
index 712bbdfe..743224a6 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.4 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..d9014a36
--- /dev/null
+++ b/docs/source/development/migration.rst
@@ -0,0 +1,137 @@
+.. _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.
+
+The difference between the old and new API is best shown with 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 progran 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..7137d85a
--- /dev/null
+++ b/docs/source/development/quickstart.rst
@@ -0,0 +1,100 @@
+.. _dev_quickstart:
+
+================================================================================
+Quick start
+================================================================================
+
+This is a short introduction to the PROJ.4 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.4 API or consult the :doc:`API reference <reference/index>` for specifics.
+
+Before the PROJ.4 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.4 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.4 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..89a9306e
--- /dev/null
+++ b/docs/source/development/reference/datatypes.rst
@@ -0,0 +1,719 @@
+.. _datatypes:
+
+================================================================================
+Data types
+================================================================================
+
+This section describe the multiplude of 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 your are only exposed to pointers to this
+    object and the contents are hidden in 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 enables 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.lam
+
+        Easting.
+
+    .. c:member:: double PJ_XY.phi
+
+        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
+    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.
+
+    .. c:member:: double PJ_XYZ.y
+
+        Northing.
+
+    .. c:member:: double PJ_XYZ.z
+
+        Vertical component.
+
+
+.. 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.
+
+    .. c:member:: double PJ_XYZT.y
+
+        Northing.
+
+    .. c:member:: double PJ_XYZT.z
+
+        Vertical component.
+
+    .. 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 usefull 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`. Depending
+    on the underlying projection, values can be calculated either numerically
+    or analytically.
+
+    .. 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;
+        } 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 error.
+
+    .. c:member:: double PJ_FACTORS.tissot_semiminor
+
+        Minimum scale error.
+
+
+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 {
+            char        release[64];
+            char        version[64];
+            int         major;
+            int         minor;
+            int         patch;
+            char        searchpath[512];
+        } PJ_INFO;
+
+    .. c:member:: char PJ_INFO.release[64]
+
+        Release info. Version number and release date,
+        e.g. "Rel. 4.9.3, 15 August 2016".
+
+    .. c:member:: char PJ_INFO.version[64]
+
+        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:: char PJ_INFO.searchpath[512]
+
+        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`.
+
+    .. code-block:: C
+
+        typedef struct {
+            char        id[16];
+            char        description[128];
+            char        definition[512];
+            int         has_inverse;
+            double      accuracy;
+        } PJ_PROJ_INFO;
+
+    .. c:member:: char PJ_PROJ_INFO.id[16]
+
+        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:: char PJ_PROJ_INFO.description[128]
+
+        Long describes of the operation the :c:type:`PJ` object is based on,
+        e.g. "*Mercator    Cyl, Sph&Ell   lat_ts=*".
+
+    .. c:member:: char PJ_PROJ_INFO.definition[512]
+
+        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 5b915edf..c748d461 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..8770f99b
--- /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 geographical 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..a557fa07 100644
--- a/docs/source/development/threads.rst
+++ b/docs/source/development/threads.rst
@@ -4,11 +4,6 @@
 Threads
 ================================================================================
 
-.. contents:: Contents
-   :depth: 3
-   :backlinks: none
-
-
 This page is about efforts to make PROJ.4 thread safe.
 
 Key Thread Safety Issues
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
+================================================================================
+
+
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index 14ceda85..8afdb35d 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -212,7 +212,7 @@ Similar issues apply with many other datasets distributed with projections
 based on a spherical earth model - such as many NASA datasets.  This coordinate
 system is now known by the EPSG code 3857 and has in the past been known as
 EPSG:3785 and EPSG:900913.  When using this coordinate system with GDAL/OGR it
-is helpful to include the +wktext so the exact proj.4 string will be preserved
+is helpful to include the +wktext so the exact PROJ.4 string will be preserved
 in the WKT representation (otherwise key parameters like `+nadgrids=@null` will
 be dropped):
 
@@ -302,7 +302,7 @@ Output of above command:
 
     0 0.7853981633974483 0.00 41.94
 
-What options does proj.4 allow for the shape of the Earth (geodesy)?
+What options does PROJ.4 allow for the shape of the Earth (geodesy)?
 --------------------------------------------------------------------------------
 
 See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c
@@ -315,7 +315,7 @@ What if I want a spherical Earth?
 Use ``+ellps=sphere``.  See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c
 for the radius used in this case.
 
-How do I change the radius of the Earth?  How do I use proj.4 for work on Mars?
+How do I change the radius of the Earth?  How do I use PROJ.4 for work on Mars?
 --------------------------------------------------------------------------------
 
 You can supply explicit values for the semi minor and semi major axes instead
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index 3495d814..21dd0f34 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -1,4 +1,4 @@
-.. _glossary::
+.. _glossary:
 
 ================================================================================
 Glossary
diff --git a/docs/source/grids.rst b/docs/source/grids.rst
index 99bcfdc1..4c0bc577 100644
--- a/docs/source/grids.rst
+++ b/docs/source/grids.rst
@@ -11,6 +11,11 @@ Grids
 
 Grid files are important for shifting and transforming between datums
 
+PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections and
+the GTX file format for vertical corrections. Details about the formats can be
+found in the GDAL documentation. GDAL reads and writes all formats. Using GDAL
+for construction of new grids is recommended.
+
 US, Canadian, French and New Zealand
 --------------------------------------------------------------------------------
 
@@ -86,6 +91,8 @@ Hungary
 `Hungarian grid <https://github.com/OSGeoLabBp/eov2etrs/>`__ ETRS89 - HD72/EOV (epsg:23700), both horizontal and elevation grids
 
 
+.. _nonfreegrids:
+
 Non-Free Grids
 --------------------------------------------------------------------------------
 
@@ -166,6 +173,3 @@ Netherlands
 ................................................................................
 
 `Dutch grid <https://www.kadaster.nl/web/Themas/Registraties/Rijksdriehoeksmeting/Transformatie-van-coordinaten.htm>`__ (Registration required before download)
-
-
-
diff --git a/docs/source/index.rst b/docs/source/index.rst
index b6f15cae..324d52fc 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,13 +1,13 @@
 .. _home:
 
 ******************************************************************************
-proj.4
+PROJ.4
 ******************************************************************************
 
-proj.4 is a standard UNIX filter function which converts geographic longitude
+PROJ.4 is a standard UNIX filter function which converts geographic longitude
 and latitude coordinates into cartesian coordinates (and vice versa), and it is
 a C API for software developers to include coordinate transformation in their
-own software. proj.4 is maintained on `GitHub <http://github.com/OSGeo/proj.4/>`_.
+own software. PROJ.4 is maintained on `GitHub <http://github.com/OSGeo/proj.4/>`_.
 
 
 =============  ================================================================
@@ -34,15 +34,14 @@ Documentation
 .. toctree::
    :maxdepth: 1
 
-   download
-   faq
-   apps/index
-   projections/index
-   parameters
+   usage/index
    geodesic
    grids
    htpd
    development/index
+   faq
+   contributing
+   download
    glossary
    license
    references
@@ -50,7 +49,7 @@ Documentation
 Mailing List
 ================================================================================
 
-The Proj.4 mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj
+The PROJ.4 mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj
 
 Indices and tables
 ==================
diff --git a/docs/source/parameters.rst b/docs/source/parameters.rst
deleted file mode 100644
index e4623b9a..00000000
--- a/docs/source/parameters.rst
+++ /dev/null
@@ -1,459 +0,0 @@
-.. _parameters:
-
-================================================================================
-Parameters
-================================================================================
-
-:Date: 01/28/2016
-
-.. contents:: Contents
-   :depth: 3
-   :backlinks: none
-
-
-This document attempts to describe a variety of the PROJ.4 parameters which can
-be applied to all, or many coordinate system definitions.  This document does
-not attempt to describe the parameters particular to particular projection
-types.  Some of these can be found in the GeoTIFF `Projections Transform List
-<http://www.remotesensing.org/geotiff/proj_list/>`__.  The definitive
-documentation for most parameters is Gerald's original documentation available
-from the main PROJ.4 page.
-
-Parameter list
---------------------------------------------------------------------------------
-
-Common parameters:
-
-(this PROJ.4 distribution including `cs2cs` and datum support)
-
-::
-
-    +a         Semimajor radius of the ellipsoid axis
-    +alpha     ? Used with Oblique Mercator and possibly a few others
-    +axis      Axis orientation (new in 4.8.0)
-    +b         Semiminor radius of the ellipsoid axis
-    +datum     Datum name (see `proj -ld`)
-    +ellps     Ellipsoid name (see `proj -le`)
-    +k         Scaling factor (old name)
-    +k_0       Scaling factor (new name)
-    +lat_0     Latitude of origin
-    +lat_1     Latitude of first standard parallel
-    +lat_2     Latitude of second standard parallel
-    +lat_ts    Latitude of true scale
-    +lon_0     Central meridian
-    +lonc      ? Longitude used with Oblique Mercator and possibly a few others
-    +lon_wrap  Center longitude to use for wrapping (see below)
-    +nadgrids  Filename of NTv2 grid file to use for datum transforms (see below)
-    +no_defs   Don't use the /usr/share/proj/proj_def.dat defaults file
-    +over      Allow longitude output outside -180 to 180 range, disables wrapping (see below)
-    +pm        Alternate prime meridian (typically a city name, see below)
-    +proj      Projection name (see `proj -l`)
-    +south     Denotes southern hemisphere UTM zone
-    +to_meter  Multiplier to convert map units to 1.0m
-    +towgs84   3 or 7 term datum transform parameters (see below)
-    +units     meters, US survey feet, etc.
-    +vto_meter vertical conversion to meters.
-    +vunits    vertical units.
-    +x_0       False easting
-    +y_0       False northing
-    +zone      UTM zone
-
-Extended list provided by Gerald Evenden "grepped out of the RCS directory".
-
-(libproj4 by G.E.; no datum support)
-
-::
-
-    +a         Semimajor radius of the ellipsoid axis
-    +alpha     ? Used with Oblique Mercator and possibly a few others
-    +azi
-    +b         Semiminor radius of the ellipsoid axis
-    +belgium
-    +beta
-    +czech
-    +e         Eccentricity of the ellipsoid = sqrt(1 - b^2/a^2) = sqrt( f*(2-f) )
-    +ellps     Ellipsoid name (see `proj -le`)
-    +es        Eccentricity of the ellipsoid squared
-    +f         Flattening of the ellipsoid = 1-sqrt(1-e^2) (often presented as an inverse, e.g. 1/298)
-    +geoc
-    +guam
-    +h
-    +k         Scaling factor (old name)
-    +K
-    +k_0       Scaling factor (new name)
-    +lat_0     Latitude of origin
-    +lat_1     Latitude of first standard parallel
-    +lat_2     Latitude of second standard parallel
-    +lat_b
-    +lat_t
-    +lat_ts    Latitude of true scale
-    +lon_0     Central meridian
-    +lon_1
-    +lon_2
-    +lonc      ? Longitude used with Oblique Mercator and possibly a few others
-    +lsat
-    +m
-    +M
-    +n
-    +no_cut
-    +no_off    No offset. If present, do not offset origin to center of projection. Only used in Oblique Mercator projection.
-    +no_uoff   Backwards compatible version of +no_off.
-    +no_rot
-    +ns
-    +o_alpha
-    +o_lat_1
-    +o_lat_2
-    +o_lat_c
-    +o_lat_p
-    +o_lon_1
-    +o_lon_2
-    +o_lon_c
-    +o_lon_p
-    +o_proj
-    +over
-    +p
-    +path
-    +proj      Projection name (see `proj -l`)
-    +q
-    +R
-    +R_a
-    +R_A       Compute radius such that the area of the sphere is the same as the area of the ellipsoid
-    +rf        Reciprocal of the ellipsoid flattening term (e.g. 298)
-    +R_g
-    +R_h
-    +R_lat_a
-    +R_lat_g
-    +rot
-    +R_V
-    +s
-    +south     Denotes southern hemisphere UTM zone
-    +sym
-    +t
-    +theta
-    +tilt
-    +to_meter  Multiplier to convert map units to 1.0m
-    +units     meters, US survey feet, etc.
-    +vopt
-    +W
-    +westo
-    +x_0       False easting
-    +y_0       False northing
-    +zone      UTM zone
-
-See GE's `libproj4
-manual <http://members.verizon.net/~gerald.evenden/proj4/manual.pdf>`__ for
-further details (`copy in wayback machine <http://web.archive.org/web/20080807155507/http://members.verizon.net/~gerald.evenden/proj4/manual.pdf>`__).
-
-Further details for projection at http://www.remotesensing.org/geotiff/proj_list/
-
-Units
---------------------------------------------------------------------------------
-
-Horizontal units can be specified using the +units= keyword with a symbolic
-name for a unit (ie. us-ft).  Alternatively the translation to meters can be
-specified with the +to_meter keyword (ie. 0.304800609601219 for US feet).  The
-``-lu`` argument to cs2cs or proj can be used to list symbolic unit names.
-The default unit for projected coordinates is the meter.
-A few special projections deviate from this behaviour, most notably the
-latlong pseudo-projection that returns degrees.
-
-
-Vertical Units
---------------------------------------------------------------------------------
-
-Vertical (Z) units can be specified using the ``+vunits=`` keyword with a
-symbolic name for a unit (ie. ``us-ft``).  Alternatively the translation to
-meters can be specified with the ``+vto_meter`` keyword (ie. 0.304800609601219
-for US feet).  The ``-lu`` argument to cs2cs or proj can be used to list symbolic
-unit names.  If no vertical units are specified, the vertical units will
-default to be the same as the horizontal coordinates.
-
-Note that vertical unit transformations are only supported in pj_transform()
-and programs built on that such as cs2cs.  The low level projections functions
-pj_fwd() and pj_inv() and programs using them directly such as proj do not
-handle vertical units at all.
-
-False Easting/Northing
---------------------------------------------------------------------------------
-
-Virtually all coordinate systems allow for the presence of a false easting
-(``+x_0``) and northing (``+y_0``).  Note that these values are always expressed in
-meters even if the coordinate system is some other units.  Some coordinate
-systems (such as UTM) have implicit false easting and northing values.
-
-lon_wrap, over - Longitude Wrapping
---------------------------------------------------------------------------------
-
-By default PROJ.4 wraps output longitudes in the range -180 to 180.  The +over
-switch can be used to disable the default wrapping which is done at a low level
-- in ``pj_inv()``.  This is particularly useful with projections like eqc where
-it would desirable for X values past -20000000 (roughly) to continue past
--180 instead of wrapping to +180.
-
-The ``+lon_wrap`` option can be used to provide an alternative means of doing
-longitude wrapping within ``pj_transform()``.  The argument to this option is a
-center longitude.  So ``+lon_wrap=180`` means wrap longitudes in the range 0 to
-360.  Note that ``+over`` does **not** disable ``+lon_wrap``.
-
-pm - Prime Meridian
---------------------------------------------------------------------------------
-
-A prime meridian may be declared indicating the offset between the prime
-meridian of the declared coordinate system and that of greenwich.  A prime
-meridian is clared using the "pm" parameter, and may be assigned a symbolic
-name, or the longitude of the alternative prime meridian relative to greenwich.
-
-Currently prime meridian declarations are only utilized by the
-``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls.
-Consequently the user utility ``cs2cs`` does honour prime meridians but the
-proj user utility ignores them.
-
-The following predeclared prime meridian names are supported.  These can be
-listed using the cs2cs argument -lm.
-
-::
-
-   greenwich 0dE
-      lisbon 9d07'54.862"W
-       paris 2d20'14.025"E
-      bogota 74d04'51.3"E
-      madrid 3d41'16.48"W
-        rome 12d27'8.4"E
-        bern 7d26'22.5"E
-     jakarta 106d48'27.79"E
-       ferro 17d40'W
-    brussels 4d22'4.71"E
-   stockholm 18d3'29.8"E
-      athens 23d42'58.815"E
-        oslo 10d43'22.5"E
-
-Example of use.  The location ``long=0``, ``lat=0`` in the greenwich based lat/long
-coordinates is translated to lat/long coordinates with Madrid as the prime
-meridian.
-
-::
-
-    cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid
-    0 0                           <i>(input)</i>
-    3d41'16.48"E    0dN 0.000     <i>(output)</i>
-
-towgs84 - Datum transformation to WGS84
---------------------------------------------------------------------------------
-
-Datum shifts can be approximated by 3 parameter spatial translations (in
-geocentric space), or 7 parameter shifts (translation + rotation + scaling).
-The parameters to describe this can be described using the towgs84 parameter.
-
-In the three parameter case, the three arguments are the translations to the
-geocentric location in meters.
-
-For instance, the following demonstrates converting from the Greek GGRS87 datum
-to WGS84.
-
-::
-
-    cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62
-        +to +proj=latlong +datum=WGS84
-    20 35
-    20d0'5.467"E    35d0'9.575"N 8.570
-
-The EPSG database provides this example for transforming from WGS72 to WGS84
-using an approximated 7 parameter transformation.
-
-::
-
-    cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \
-        +to +proj=latlong +datum=WGS84
-    4 55
-    4d0'0.554"E     55d0'0.09"N 3.223
-
-The seven parameter case uses ``delta_x``, ``delta_y``, ``delta_z``, ``Rx -
-rotation X``, ``Ry - rotation Y``, ``Rz - rotation Z``, ``M_BF - Scaling``.
-The three translation parameters are in meters as in the three parameter case.
-The rotational parameters are in seconds of arc.  The scaling is apparently the
-scale change in parts per million.
-
-A more complete discussion of the 3 and 7 parameter transformations can be
-found in the EPSG database (trf_method's 9603 and 9606).  Within PROJ.4 the
-following calculations are used to apply the ``towgs84`` transformation (going
-to WGS84).  The x, y and z coordinates are in geocentric coordinates.
-
-Three parameter transformation (simple offsets):
-
-::
-
-  x[io] = x[io] + defn->datum_params[0];
-  y[io] = y[io] + defn->datum_params[1];
-  z[io] = z[io] + defn->datum_params[2];
-
-Seven parameter transformation (translation, rotation and scaling):
-
-::
-
-    #define Dx_BF (defn->datum_params[0])
-    #define Dy_BF (defn->datum_params[1])
-    #define Dz_BF (defn->datum_params[2])
-    #define Rx_BF (defn->datum_params[3])
-    #define Ry_BF (defn->datum_params[4])
-    #define Rz_BF (defn->datum_params[5])
-    #define M_BF  (defn->datum_params[6])
-
-    x_out = M_BF*(       x[io] - Rz_BF*y[io] + Ry_BF*z[io]) + Dx_BF;
-    y_out = M_BF*( Rz_BF*x[io] +       y[io] - Rx_BF*z[io]) + Dy_BF;
-    z_out = M_BF*(-Ry_BF*x[io] + Rx_BF*y[io] +       z[io]) + Dz_BF;
-
-Note that EPSG method 9607 (coordinate frame rotation) coefficients can be
-converted to EPSG method 9606 (position vector 7-parameter) supported by PROJ.4
-by reversing the sign of the rotation vectors.  The methods are otherwise the
-same.
-
-nadgrids - Grid Based Datum Adjustments
---------------------------------------------------------------------------------
-
-In many places (notably North America and Austrialia) national geodetic
-organizations provide grid shift files for converting between different datums,
-such as NAD27 to NAD83.  These grid shift files include a shift to be applied
-at each grid location. Actually grid shifts are normally computed based on an
-interpolation between the containing four grid points.
-
-PROJ.4 currently supports use of grid shift files for shifting between datums
-and WGS84 under some circumstances.  The grid shift table formats are ctable
-(the binary format produced by the PROJ.4 ``nad2bin`` program), NTv1 (the old
-Canadian format), and NTv2 (``.gsb`` - the new Canadian and Australian format).
-
-Use of grid shifts is specified using the ``nadgrids`` keyword in a coordinate
-system definition.  For example:
-
-
-::
-
-    % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \
-        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
-    -111 50
-    EOF
-    111d0'2.952"W   50d0'0.111"N 0.000
-
-In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was
-loaded, and used to get a grid shift value for the selected point.
-
-It is possible to list multiple grid shift files, in which case each will be
-tried in turn till one is found that contains the point being transformed.
-
-::
-
-    cs2cs +proj=latlong +ellps=clrk66 \
-              +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \
-        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
-    -111 44
-    EOF
-    111d0'2.788"W   43d59'59.725"N 0.000
-
-Skipping Missing Grids
-................................................................................
-
-The special prefix ``@`` may be prefixed to a grid to make it optional.  If it
-not found, the search will continue to the next grid.  Normally any grid not
-found will cause an error.  For instance, the following would use the
-``ntv2_0.gsb`` file if available (see [[NonFreeGrids]]), otherwise it would
-fallback to using the ``ntv1_can.dat`` file.
-
-::
-
-    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \
-        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
-    -111 50
-    EOF
-    111d0'3.006"W   50d0'0.103"N 0.000
-
-The null Grid
-................................................................................
-
-A special ``null`` grid shift file is shift with releases after 4.4.6 (not
-inclusive).  This file provides a zero shift for the whole world.  It may be
-listed at the end of a nadgrids file list if you want a zero shift to be
-applied to points outside the valid region of all the other grids.  Normally if
-no grid is found that contains the point to be transformed an error will occur.
-
-::
-
-    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
-        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
-    -111 45
-    EOF
-    111d0'3.006"W   50d0'0.103"N 0.000
-
-    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
-        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
-    -111 44
-    -111 55
-    EOF
-    111d0'2.788"W   43d59'59.725"N 0.000
-    111dW   55dN 0.000
-
-Downloading and Installing Grids
-................................................................................
-
-The source distribution of PROJ.4 contains only the ntv1_can.dat file.  To get
-the set of US grid shift files it is necessary to download an additional
-distribution of files from the PROJ.4 site, such as
-ftp://ftp.remotesensing.org/pub/proj/proj-nad27-1.1.tar.gz.  Overlay it on the
-PROJ.4 source distribution, and re-configure, compile and install.  The
-distributed ASCII .lla files are converted into binary (platform specific)
-files that are installed.  On windows using the nmake /f makefile.vc nadshift
-command in the proj\src directory to build and install these files.
-
-It appears we can't redistribute the Canadian NTv2 grid shift file freely,
-though it is better than the NTv1 file.  However, end users can download it for
-free from the `NRCan web site
-<http://www.geod.nrcan.gc.ca/tools-outils/ntv2_e.php>`__.  After downloading
-it, just dump it in the data directory with the other installed data files
-(usually `/usr/local/share/proj`). See [[NonFreeGrids]] for details.
-
-Caveats
-................................................................................
-
-* Where grids overlap (such as conus and ntv1_can.dat for instance) the first
-  found for a point will be used regardless of whether it is appropriate or
-  not.  So, for instance, ```+nadgrids=ntv1_can.dat```,conus would result in
-  the Canadian data being used for some areas in the northern United States
-  even though the conus data is the approved data to use for the area.
-  Careful selection of files and file order is necessary.  In some cases
-  border spanning datasets may need to be pre-segmented into Canadian and
-  American points so they can be properly grid shifted
-* There are additional grids for shifting between NAD83 and various HPGN
-  versions of the NAD83 datum.  Use of these haven't been tried recently so
-  you may encounter problems.  The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla
-  are examples of high precision grid shifts.  Take care!
-* Additional detail on the grid shift being applied can be found by setting
-  the PROJ_DEBUG environment variable to a value.  This will result in output
-  to stderr on what grid is used to shift points, the bounds of the various
-  grids loaded and so forth
-* PROJ.4 always assumes that grids contain a shift **to**  NAD83 (essentially
-  WGS84).  Other types of grids might or might not be usable
-
-Axis orientation
---------------------------------------------------------------------------------
-
-Starting in PROJ 4.8.0, the +axis argument can be used to control the axis
-orientation of the coordinate system.  The default orientation is "easting,
-northing, up" but directions can be flipped, or axes flipped using combinations
-of the axes in the +axis switch.  The values are:
-
-* "e" - Easting
-* "w" - Westing
-* "n" - Northing
-* "s" - Southing
-* "u" - Up
-* "d" - Down
-
-They can be combined in +axis in forms like:
-
-* ``+axis=enu`` - the default easting, northing, elevation.
-* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic
-  coordinates, or south orientated transverse mercator.
-* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems
-  have "west positive" coordinate systems
-
-Note that the ``+axis`` argument only applies to coordinate transformations done
-through ``pj_transform()`` (so it works with ``cs2cs``, but not with the proj
-commandline program).
diff --git a/docs/source/projections/aeqd.rst b/docs/source/projections/aeqd.rst
deleted file mode 100644
index 949cd8a0..00000000
--- a/docs/source/projections/aeqd.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-.. _aeqd:
-
-********************************************************************************
-Azimuthal Equidistant
-********************************************************************************
-
-.. image:: ./images/aeqd.png
-   :scale: 50%
-   :alt:   Azimuthal Equidistant  
-
diff --git a/docs/source/references.rst b/docs/source/references.rst
index e80e8caf..320e401b 100644
--- a/docs/source/references.rst
+++ b/docs/source/references.rst
@@ -4,6 +4,11 @@
 References
 ================================================================================
 
+.. [AltamimiEtAl2002] Altamimi, Z., P. Sillard, and C. Boucher (2002),
+    ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications,
+    J. Geophys. Res., 107(B10), 2214,
+    `doi:10.1029/2001JB000561 <http://www.agu.org/pubs/crossref/2002/2001JB000561.shtml>`__.
+
 
 .. [Bessel1825] F. W. Bessel, 1825,
    `The calculation of longitude and latitude from geodesic measurements
@@ -24,6 +29,10 @@ References
    <https://doi.org/10.1179/003962689791474267>`_,
    Survey Review **30**\ (232), 61–66.
 
+.. [Deakin2004] R.E. Deakin, 2004,
+    `The Standard and Abridged Molodensky Coordinate Transformation Formulae
+    <http://www.mygeodesy.id.au/documents/Molodensky%20V2.pdf>`__.
+
 .. [EberHewitt1979] L. E. Eber and R.P. Hewitt, 1979,
    `Conversion algorithms for the CALCOFI station grid
    <http://www.calcofi.org/publications/calcofireports/v20/Vol_20_Eber___Hewitt.pdf>`_,
@@ -39,6 +48,11 @@ References
    (Preliminary Draft)
    <https://github.com/OSGeo/proj.4/blob/master/docs/old/libproj.pdf>`_.
 
+.. [EversKnudsen2017] K. Evers and T. Knudsen, 2017,
+    `Transformation pipelines for PROJ.4
+    <http://www.fig.net/resources/proceedings/fig_proceedings/fig2017/papers/iss6b/ISS6B_evers_knudsen_9156.pdf>`__,
+    FIG Working Week 2017 Proceedings.
+
 .. [GeodesicBib] `A geodesic bibliography
    <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_.
 
@@ -46,6 +60,11 @@ References
    `Geodesics on an ellipsoid
    <https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid>`_.
 
+.. [Häkli2016] P. Häkli, M. Lidberg, L. Jivall, et al, 2016,
+   `The NKG2008 GPS Campaign - final transformation results and a new common Nordic reference frame
+   <https://doi.org/10.1515/jogs-2016-0001>`_,
+   Journal of Geodetic Science, 6(1).
+
 .. [Helmert1880] F. R. Helmert, 1880,
    `Mathematical and Physical Theories of Higher Geodesy, Vol 1
    <https://doi.org/10.5281/zenodo.32050>`_,
diff --git a/docs/source/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst
index ae8016fe..675379ef 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/usage/apps/cs2cs.rst
@@ -5,8 +5,6 @@ cs2cs
 ================================================================================
 
 
-.. Index:: cs2cs
-
 ``cs2cs`` performs transformation between the source and destination cartographic  coordinate  system
 on a set of input points.  The coordinate system transformation can include  translation  between
 projected  and geographic coordinates as well as the application of datum shifts.
diff --git a/docs/source/apps/geod.rst b/docs/source/usage/apps/geod.rst
index 49fa4925..1e009283 100644
--- a/docs/source/apps/geod.rst
+++ b/docs/source/usage/apps/geod.rst
@@ -4,9 +4,6 @@
 geod
 ================================================================================
 
-
-.. Index:: geod
-
 ``geod``  (direct)  and  ``invgeod`` (inverse) perform geodesic ("Great
 Circle") computations for determining latitude,  longitude  and
 back  azimuth  of  a terminus point given a initial point latitude,
@@ -157,7 +154,7 @@ which gives:
      45d31'0.003"N 123d40'59.985"W 75d39'13.094"
 
 .. note::
-    lack  of precision in the distance value compromises the
+    Lack  of precision in the distance value compromises the
     precision of the Portland location.
 
 Further reading
diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst
new file mode 100644
index 00000000..73c5c63c
--- /dev/null
+++ b/docs/source/usage/apps/index.rst
@@ -0,0 +1,20 @@
+.. _apps:
+
+================================================================================
+Applications
+================================================================================
+
+Bundled with PROJ.4 comes a set of small command line utilities. The
+``proj`` program is limited to converting between geographic and projection
+coordinates within one datum. The ``cs2cs`` program operates similarly, but
+allows translation between any pair of definable coordinate systems, including
+support for basic datum translation. The ``geod`` program provides the ability
+to do geodesic (great circle) computations.
+
+.. toctree::
+   :maxdepth: 1
+
+   proj
+   cs2cs
+   geod
+
diff --git a/docs/source/apps/proj.rst b/docs/source/usage/apps/proj.rst
index a06df383..424a0fef 100644
--- a/docs/source/apps/proj.rst
+++ b/docs/source/usage/apps/proj.rst
@@ -1,4 +1,4 @@
-:. _proj:
+.. _proj:
 
 ================================================================================
 proj
@@ -7,7 +7,7 @@ proj
 
 .. Index:: proj
 
-Proj and invproj perform respective forward  and inverse  transformation  of cartographic data to
+``proj`` and ``invproj`` perform respective forward  and inverse  transformation  of cartographic data to
 or from cartesian data  with  a  wide  range  of selectable projection functions.
 
 
diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst
new file mode 100644
index 00000000..38cb46de
--- /dev/null
+++ b/docs/source/usage/environmentvars.rst
@@ -0,0 +1,43 @@
+.. _environmentvars:
+
+================================================================================
+Environment variables
+================================================================================
+
+PROJ.4 can be crontrolled by setting environment variables. Most users will
+have a use for the :envvar:`PROJ_LIB`.
+
+On UNIX systems environment variables can be set for a shell-session with::
+
+    $ export VAR="some variable"
+
+or it can be set for just one command line call::
+
+    $ VAR="some variable" ./cmd
+
+Environment variables on UNIX are usually removed with the ``unset`` command::
+
+    $ unset VAR
+
+On windows systems environment variables can be set in the command line with::
+
+    > set VAR="some variable"
+
+```VAR`` will be available for the entire session, unless it is unset. This is
+done by setting the variable with no content::
+
+    > set VAR=
+
+.. envvar:: PROJ_LIB
+
+    The location of PROJ.4 :doc:`resource files<resource_files>`.
+    It is only possible to specify a single library in :envvar:`PROJ_LIB`; e.g. it
+    does not behave like PATH. PROJ.4 is hardcoded to look for resource files
+    in other locations as well, amongst those are the users home directory,
+    ``/usr/share/proj`` and the current folder.
+
+.. envvar:: PROJ_DEBUG
+
+    Set the debug level of PROJ.4. The default debug level is zero, which results
+    in no debug output when using PROJ.4. A number from 1-3, whit 3 being the most
+    verbose setting.
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
new file mode 100644
index 00000000..81ea4b6b
--- /dev/null
+++ b/docs/source/usage/index.rst
@@ -0,0 +1,22 @@
+.. _usage:
+
+================================================================================
+Using PROJ.4
+================================================================================
+
+The main purpose of PROJ.4 is to transform coordinates from one coordinate
+reference system to another. This can be achieved either with the included
+command line applications or the C API that is a part of the software package.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   quickstart
+   apps/index
+   projections
+   transformation
+   resource_files
+   environmentvars
+   operations/index
+
diff --git a/docs/source/usage/operations/conversions/axisswap.rst b/docs/source/usage/operations/conversions/axisswap.rst
new file mode 100644
index 00000000..ddaad075
--- /dev/null
+++ b/docs/source/usage/operations/conversions/axisswap.rst
@@ -0,0 +1,39 @@
+.. _axisswap:
+
+================================================================================
+Axis swap
+================================================================================
+
+Change the order and sign of 2,3 or 4 axes.
+
++--------------+---------------------------------------------------------------+
+| **Options**                                                                  |
++--------------+---------------------------------------------------------------+
+| `+order`     | Ordered comma-separated list of axis, e.g. `+order=2,1,3,4`   |
++--------------+---------------------------------------------------------------+
+
+
+Each of the possible four axes are numbered with 1-4, such that the first input axis
+is 1, the second is 2 and so on. The output ordering is controlled by a list of the
+input axes re-ordered to the new mapping.
+
+Examples
+################################################################################
+
+Reversing the order of the axes::
+
+    +proj=axisswap +order=4,3,2,1
+
+Swapping the first two axes (x and y)::
+
+    +proj=axisswap +order=2,1,3,4
+
+The direction, or sign, of an axis can be changed by adding a minus in
+front of the axis-number::
+
+    +proj=axisswap +order=1,-2,3,4
+
+It is only necessary to specify the axes that are affected by the swap
+operation::
+
+    +proj=axisswap +order=2,1
diff --git a/docs/source/usage/operations/conversions/cart.rst b/docs/source/usage/operations/conversions/cart.rst
new file mode 100644
index 00000000..0c3c7c23
--- /dev/null
+++ b/docs/source/usage/operations/conversions/cart.rst
@@ -0,0 +1,24 @@
+.. _cart:
+
+================================================================================
+Cartesian to geodetic conversion
+================================================================================
+
+Convert geodetic coordinates to cartesian coordinates.
+
++--------------+--------------------------------------------------------------------+
+| **Options**                                                                       |
++--------------+--------------------------------------------------------------------+
+| `+ellps`     |  Ellipsoid of the input coordinates. If used together with the     |
+|              |  ellipsoid parameters below, ``+ellps`` is overwritten.            |
++--------------+--------------------------------------------------------------------+
+| `+a`         | Semi-major radius of ellipsoid axis.                               |
++--------------+--------------------------------------------------------------------+
+| `+b`         | Semi-minor radius of ellipsoid axis.                               |
++--------------+--------------------------------------------------------------------+
+| `+es`        | Eccentricity of ellipsoid.                                         |
++--------------+--------------------------------------------------------------------+
+| `+f`         | Flattening of ellipsoid.                                           |
++--------------+--------------------------------------------------------------------+
+
+
diff --git a/docs/source/usage/operations/conversions/index.rst b/docs/source/usage/operations/conversions/index.rst
new file mode 100644
index 00000000..54324ec4
--- /dev/null
+++ b/docs/source/usage/operations/conversions/index.rst
@@ -0,0 +1,18 @@
+.. _conversions_list:
+
+================================================================================
+Conversions
+================================================================================
+
+Conversions are coordinate operations in which both coordinate reference systems
+are based on the same datum. In PROJ.4 projections are differentiated from
+conversions.
+
+.. toctree::
+   :maxdepth: 1
+
+   axisswap
+   cart
+   lonlat
+   latlon
+   unitconvert
diff --git a/docs/source/projections/latlon.rst b/docs/source/usage/operations/conversions/latlon.rst
index 6712fa7b..6712fa7b 100644
--- a/docs/source/projections/latlon.rst
+++ b/docs/source/usage/operations/conversions/latlon.rst
diff --git a/docs/source/projections/lonlat.rst b/docs/source/usage/operations/conversions/lonlat.rst
index 589cc813..589cc813 100644
--- a/docs/source/projections/lonlat.rst
+++ b/docs/source/usage/operations/conversions/lonlat.rst
diff --git a/docs/source/usage/operations/conversions/unitconvert.rst b/docs/source/usage/operations/conversions/unitconvert.rst
new file mode 100644
index 00000000..ad848207
--- /dev/null
+++ b/docs/source/usage/operations/conversions/unitconvert.rst
@@ -0,0 +1,112 @@
+.. _unitconvert:
+
+================================================================================
+Unit conversion
+================================================================================
+
+Convert between various distance and time units.
+
++--------------+--------------------------------------------------------------------+
+| **Options**                                                                       |
++--------------+--------------------------------------------------------------------+
+| `+xy_in`     | Input unit of the horizontal components.                           |
++--------------+--------------------------------------------------------------------+
+| `+xy_out`    | Output unit of the horizontal components.                          |
++--------------+--------------------------------------------------------------------+
+| `+z_in`      | Input unit of the vertical component.                              |
++--------------+--------------------------------------------------------------------+
+| `+z_out`     | Output unit of the vertical component.                             |
++--------------+--------------------------------------------------------------------+
+| `+t_in`      | Input unit of the time component.                                  |
++--------------+--------------------------------------------------------------------+
+| `+t_out`     | Output unit of the time component.                                 |
++--------------+--------------------------------------------------------------------+
+
+There are many examples of coordinate reference systems that are expressed in
+other units than the meter. There are also many cases where temporal data
+has to be translated to different units. The `unitconvert` operation takes care
+of that.
+
+Many North American systems are defined with coordinates in feet. For example
+in Vermont::
+
+    +proj=pipeline
+    +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k=0.999964286 +x_0=500000.00001016 +y_0=0
+    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+
+Often when working with GNNS data the timestamps are presented in GPS-weeks,
+but when the data transformed with the `helmert` operation timestamps are
+expected to be in units of decimalyears. This can be fixed with `unitconvert`::
+
+    +proj=pipeline
+    +step +proj=unitconvert +t_in=gpsweek +t_out=decimalyear
+    +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ...
+
+
+Distance units
+###############################################################################
+
+In the table below all distance units supported by PROJ.4 is listed.
+The same list can also be produced on the command line with `proj` or `cs2cs`,
+by adding the `-lu` flag when calling the utility.
+
++----------+---------------------------------+
+| Label    | Name                            |
++----------+---------------------------------+
+|     km   | Kilometer                       |
++----------+---------------------------------+
+|      m   | Meter                           |
++----------+---------------------------------+
+|     dm   | Decimeter                       |
++----------+---------------------------------+
+|     cm   | Centimeter                      |
++----------+---------------------------------+
+|     mm   | Millimeter                      |
++----------+---------------------------------+
+|    kmi   | International Nautical Mile     |
++----------+---------------------------------+
+|     in   | International Inch              |
++----------+---------------------------------+
+|     ft   | International Foot              |
++----------+---------------------------------+
+|     yd   | International Yard              |
++----------+---------------------------------+
+|     mi   | International Statute Mile      |
++----------+---------------------------------+
+|   fath   | International Fathom            |
++----------+---------------------------------+
+|     ch   | International Chain             |
++----------+---------------------------------+
+|   link   | International Link              |
++----------+---------------------------------+
+|  us-in   | U.S. Surveyor's Inch            |
++----------+---------------------------------+
+|  us-ft   | U.S. Surveyor's Foot            |
++----------+---------------------------------+
+|  us-yd   | U.S. Surveyor's Yard            |
++----------+---------------------------------+
+|  us-ch   | U.S. Surveyor's Chain           |
++----------+---------------------------------+
+|  us-mi   | U.S. Surveyor's Statute Mile    |
++----------+---------------------------------+
+| ind-yd   | Indian Yard                     |
++----------+---------------------------------+
+| ind-ft   | Indian Foot                     |
++----------+---------------------------------+
+| ind-ch   | Indian Chain                    |
++----------+---------------------------------+
+
+
+Time units
+###############################################################################
+
+In the table below all time units supported by PROJ.4 is listed.
+
++--------------+-----------------------------+
+| mjd          | Modfied Julian date         |
++--------------+-----------------------------+
+| decimalyear  | Decimal year                |
++--------------+-----------------------------+
+| gps_week     | GPS Week                    |
++--------------+-----------------------------+
+
diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst
new file mode 100644
index 00000000..d78f8947
--- /dev/null
+++ b/docs/source/usage/operations/index.rst
@@ -0,0 +1,22 @@
+.. _operations:
+
+================================================================================
+Coordinate operations
+================================================================================
+
+Coordinate operations in PROJ.4 are divided into three groups:
+Projections, conversions  and transformations.
+Projections are purely cartographic mappings of the sphere onto the plane.
+Technically projections are conversions (according to ISO standards), though in
+PROJ.4 projections are distinguished from conversions. Conversions are coordinate
+operations that do not exert a change in reference frame. Operations that do
+exert a change in reference frame are called transformations.
+
+.. toctree::
+   :maxdepth: 1
+
+   projections/index
+   conversions/index
+   transformations/index
+   pipeline
+
diff --git a/docs/source/usage/operations/pipeline.rst b/docs/source/usage/operations/pipeline.rst
new file mode 100644
index 00000000..18637712
--- /dev/null
+++ b/docs/source/usage/operations/pipeline.rst
@@ -0,0 +1,98 @@
+.. _pipeline:
+
+================================================================================
+The pipeline operator
+================================================================================
+
+Construct complex operations by daisy-chaining operations in a sequential pipeline.
+
++-----------------+--------------------------------------------------------------------+
+| **Input type**  | Any.                                                               |
++-----------------+--------------------------------------------------------------------+
+| **Output type** | Any.                                                               |
++-----------------+--------------------------------------------------------------------+
+| **Options**                                                                          |
++-----------------+--------------------------------------------------------------------+
+| `step`          | Separate each step in a pipeline.                                  |
++-----------------+--------------------------------------------------------------------+
+| `inv`           | Invert a step in a pipeline.                                       |
++-----------------+--------------------------------------------------------------------+
+
+.. note:: See the section on :ref:`transformation` for a more thorough introduction
+          to the concept of transformation pipelines in PROJ.
+
+
+With the pipeline operation it is possible to perform several operations after each
+other on the same input data. This feature makes it possible to create transformations
+that are made up of more than one operation, e.g. performing a datum shift and then
+applying a suitable map projection. Theoretically any transformation between two
+coordinate reference systems is possible to perform using the pipeline operation,
+provided that the necessary coordinate operations in each step is available in PROJ.
+
+A pipeline is made up of a number of steps, with each step being a coordinate operation
+in itself. By connecting these individual steps sequentially we end up with a concatenated
+coordinate operation. An example of this is a transformation from geodetic coordinates
+on the GRS80 ellipsoid to a projected system where the east-west and north-east axes has
+been swapped:
+
+::
+
+    +proj=pipeline +ellps=GRS80 +step +proj=merc +step +proj=axisswap +order=2,1
+
+Here the first step is applying the :ref:`merc` projection and the second step is
+applying the :ref:`axisswap` conversion. Note that the `+ellps=GRS80` is specified
+before the first occurence of `+step`. This means that the GRS80 ellipsoid is used
+in both steps, since any parameter stated before the first occurence of `+step` is
+treated as a global parameter and is transferred to each individual steps.
+
+
+Rules for pipelines
+-------------------------------------------------------------------------------
+
+**1. Pipelines must consist of at least one step.**
+
+::
+
+    +proj=pipeline
+
+Will result in an error.
+
+**2. Pipelines can only be nested if the nested pipeline is defined in an init-file.**
+
+::
+
+    +proj=pipeline
+    +step +proj=pipeline +step +proj=merc +step +proj=axisswap +order=2,1
+    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+
+Results in an error, while
+
+::
+
+    +proj=pipeline
+    +step +init=predefined_pipelines:projectandswap
+    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+
+does not.
+
+**3. Pipelines without a forward path can't be constructed.**
+
+::
+
+    +proj=pipeline +step +inv +proj=urm5
+
+Will result in an error since :ref:`urm5` does not have an inverse operation defined.
+
+**4. Parameters added before the first `+step` are global and will be applied to all steps.**
+
+In the following the GRS80 ellipsoid will be applied to all steps.
+
+::
+
+    +proj=pipeline +ellps=GRS80
+    +step +proj=cart
+    +step +proj=helmert +x=10 +y=3 +z=1
+    +step +proj=cart +inv
+    +step +proj=merc
+
+
diff --git a/docs/source/usage/operations/projections/aeqd.rst b/docs/source/usage/operations/projections/aeqd.rst
new file mode 100644
index 00000000..32165e49
--- /dev/null
+++ b/docs/source/usage/operations/projections/aeqd.rst
@@ -0,0 +1,22 @@
+.. _aeqd:
+
+********************************************************************************
+Azimuthal Equidistant
+********************************************************************************
++---------------------+----------------------------------------------------------+
+| **Classification**  | Azimuthal                                                |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical and elliptical projection |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Gerald I. Evenden                                        |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+guam`             |  Use Guam elliptical formulas. Defaults to false.        |
++---------------------+----------------------------------------------------------+
+
+
+.. image:: ./images/aeqd.png
+   :scale: 50%
+   :alt:   Azimuthal Equidistant
+
diff --git a/docs/source/usage/operations/projections/airy.rst b/docs/source/usage/operations/projections/airy.rst
new file mode 100644
index 00000000..d2730592
--- /dev/null
+++ b/docs/source/usage/operations/projections/airy.rst
@@ -0,0 +1,26 @@
+.. _airy:
+
+********************************************************************************
+Airy
+********************************************************************************
++---------------------+----------------------------------------------------------+
+| **Classification**  |                                                          |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward spherical projection                             |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global                                                   |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Gerald I. Evenden                                        |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+lat_b`            |                                                          |
++---------------------+----------------------------------------------------------+
+| `+no_cut`           | Do not cut at hemisphere limit                           |
++---------------------+----------------------------------------------------------+
+
+
+.. image:: ./images/airy.png
+   :scale: 50%
+   :alt:   Airy
+
diff --git a/docs/source/projections/aitoff.rst b/docs/source/usage/operations/projections/aitoff.rst
index 4d681468..4d681468 100644
--- a/docs/source/projections/aitoff.rst
+++ b/docs/source/usage/operations/projections/aitoff.rst
diff --git a/docs/source/projections/alsk.rst b/docs/source/usage/operations/projections/alsk.rst
index f7a7a0ef..f7a7a0ef 100644
--- a/docs/source/projections/alsk.rst
+++ b/docs/source/usage/operations/projections/alsk.rst
diff --git a/docs/source/projections/apian.rst b/docs/source/usage/operations/projections/apian.rst
index add501ea..add501ea 100644
--- a/docs/source/projections/apian.rst
+++ b/docs/source/usage/operations/projections/apian.rst
diff --git a/docs/source/projections/august.rst b/docs/source/usage/operations/projections/august.rst
index e2ad3516..e2ad3516 100644
--- a/docs/source/projections/august.rst
+++ b/docs/source/usage/operations/projections/august.rst
diff --git a/docs/source/projections/bacon.rst b/docs/source/usage/operations/projections/bacon.rst
index a87ea7d8..a87ea7d8 100644
--- a/docs/source/projections/bacon.rst
+++ b/docs/source/usage/operations/projections/bacon.rst
diff --git a/docs/source/projections/bipc.rst b/docs/source/usage/operations/projections/bipc.rst
index 7045f04a..7045f04a 100644
--- a/docs/source/projections/bipc.rst
+++ b/docs/source/usage/operations/projections/bipc.rst
diff --git a/docs/source/projections/boggs.rst b/docs/source/usage/operations/projections/boggs.rst
index 1dd7d19f..1dd7d19f 100644
--- a/docs/source/projections/boggs.rst
+++ b/docs/source/usage/operations/projections/boggs.rst
diff --git a/docs/source/projections/bonne.rst b/docs/source/usage/operations/projections/bonne.rst
index ef87d7c9..ef87d7c9 100644
--- a/docs/source/projections/bonne.rst
+++ b/docs/source/usage/operations/projections/bonne.rst
diff --git a/docs/source/projections/calcofi.rst b/docs/source/usage/operations/projections/calcofi.rst
index 3c1e5f7a..650416c1 100644
--- a/docs/source/projections/calcofi.rst
+++ b/docs/source/usage/operations/projections/calcofi.rst
@@ -22,7 +22,7 @@ California Cooperative Oceanic Fisheries Investigations program, known as CalCOF
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ../../images/calcofi.png
+.. image:: ../../../../images/calcofi.png
    :scale: 50%
    :align: center
    :alt:   Cal Coop Ocean Fish Invest Lines/Stations
diff --git a/docs/source/projections/cass.rst b/docs/source/usage/operations/projections/cass.rst
index 83f8c2ce..83f8c2ce 100644
--- a/docs/source/projections/cass.rst
+++ b/docs/source/usage/operations/projections/cass.rst
diff --git a/docs/source/projections/cc.rst b/docs/source/usage/operations/projections/cc.rst
index 5b30e6c6..5b30e6c6 100644
--- a/docs/source/projections/cc.rst
+++ b/docs/source/usage/operations/projections/cc.rst
diff --git a/docs/source/projections/ccon.rst b/docs/source/usage/operations/projections/ccon.rst
index 6197f061..8a858e38 100644
--- a/docs/source/projections/ccon.rst
+++ b/docs/source/usage/operations/projections/ccon.rst
@@ -4,22 +4,37 @@
 Central Conic
 ********************************************************************************
 
+This is central (centrographic) projection on cone tangent at ``lat_0`` latitude,
+identical with ``conic()`` projection from ``mapproj`` R package.
+
++---------------------+----------------------------------------------------------+
+| **Classification**  | Conic                                                    |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical projection                |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global, but best used near the standard parallel         |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Lukasz Komsta                                            |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+lat_1`            | Latitude of standard parallel.                           |
++---------------------+----------------------------------------------------------+
+
 .. image:: ./images/ccon.png
    :scale: 50%
-   :alt:   Central Conic 
+   :alt:   Central Conic
 
-This is central (centrographic) projection on cone tangent at ``lat_0`` latitude,
-identical with ``conic()`` projection from ``mapproj`` R package.
 
 Usage
 ########
 
 This simple projection is rarely used, as it is not equidistant, equal-area, nor
-conformal. 
+conformal.
 
 An example of usage (and the main reason to implement this projection in proj4)
-is the ATPOL geobotanical grid of Poland, developed in Institute of Botany, 
-Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]_. The grid was 
+is the ATPOL geobotanical grid of Poland, developed in Institute of Botany,
+Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]_. The grid was
 originally handwritten on paper maps and further copied by hand. The projection
 (together with strange Earth radius) was chosen by its creators as the compromise
 fit to existing maps during first software development in DOS era. Many years later
@@ -47,7 +62,7 @@ Forward projection
 
 .. math::
 
-   y = \cot \phi_0 - r \cos (\lambda\sin\phi_0) 
+   y = \cot \phi_0 - r \cos (\lambda\sin\phi_0)
 
 
 Inverse projection
@@ -110,9 +125,3 @@ and it should give the following results:
    3.707419E+04	6.768262E+05 0.000000E+00
    6.960534E+05	6.722946E+05 0.000000E+00
    3.300000E+05	3.500000E+05 0.000000E+00
-
-
-
-
-
-
diff --git a/docs/source/projections/cea.rst b/docs/source/usage/operations/projections/cea.rst
index 20ebc285..20ebc285 100644
--- a/docs/source/projections/cea.rst
+++ b/docs/source/usage/operations/projections/cea.rst
diff --git a/docs/source/projections/chamb.rst b/docs/source/usage/operations/projections/chamb.rst
index 2ec9bffe..2ec9bffe 100644
--- a/docs/source/projections/chamb.rst
+++ b/docs/source/usage/operations/projections/chamb.rst
diff --git a/docs/source/projections/collg.rst b/docs/source/usage/operations/projections/collg.rst
index aa16182a..aa16182a 100644
--- a/docs/source/projections/collg.rst
+++ b/docs/source/usage/operations/projections/collg.rst
diff --git a/docs/source/projections/crast.rst b/docs/source/usage/operations/projections/crast.rst
index 9d17f274..9d17f274 100644
--- a/docs/source/projections/crast.rst
+++ b/docs/source/usage/operations/projections/crast.rst
diff --git a/docs/source/projections/denoy.rst b/docs/source/usage/operations/projections/denoy.rst
index a885ab0e..a885ab0e 100644
--- a/docs/source/projections/denoy.rst
+++ b/docs/source/usage/operations/projections/denoy.rst
diff --git a/docs/source/projections/eck1.rst b/docs/source/usage/operations/projections/eck1.rst
index 841533ec..841533ec 100644
--- a/docs/source/projections/eck1.rst
+++ b/docs/source/usage/operations/projections/eck1.rst
diff --git a/docs/source/projections/eck2.rst b/docs/source/usage/operations/projections/eck2.rst
index b1bd3179..b1bd3179 100644
--- a/docs/source/projections/eck2.rst
+++ b/docs/source/usage/operations/projections/eck2.rst
diff --git a/docs/source/projections/eck3.rst b/docs/source/usage/operations/projections/eck3.rst
index ecacc32d..ecacc32d 100644
--- a/docs/source/projections/eck3.rst
+++ b/docs/source/usage/operations/projections/eck3.rst
diff --git a/docs/source/projections/eck4.rst b/docs/source/usage/operations/projections/eck4.rst
index 3fc6a9fd..3fc6a9fd 100644
--- a/docs/source/projections/eck4.rst
+++ b/docs/source/usage/operations/projections/eck4.rst
diff --git a/docs/source/projections/eck5.rst b/docs/source/usage/operations/projections/eck5.rst
index 1442d99d..1442d99d 100644
--- a/docs/source/projections/eck5.rst
+++ b/docs/source/usage/operations/projections/eck5.rst
diff --git a/docs/source/projections/eck6.rst b/docs/source/usage/operations/projections/eck6.rst
index caeaefa6..caeaefa6 100644
--- a/docs/source/projections/eck6.rst
+++ b/docs/source/usage/operations/projections/eck6.rst
diff --git a/docs/source/projections/eqc.rst b/docs/source/usage/operations/projections/eqc.rst
index be431977..be431977 100644
--- a/docs/source/projections/eqc.rst
+++ b/docs/source/usage/operations/projections/eqc.rst
diff --git a/docs/source/projections/eqdc.rst b/docs/source/usage/operations/projections/eqdc.rst
index 3ee5999d..3ee5999d 100644
--- a/docs/source/projections/eqdc.rst
+++ b/docs/source/usage/operations/projections/eqdc.rst
diff --git a/docs/source/projections/etmerc.rst b/docs/source/usage/operations/projections/etmerc.rst
index b7f89032..b7f89032 100644
--- a/docs/source/projections/etmerc.rst
+++ b/docs/source/usage/operations/projections/etmerc.rst
diff --git a/docs/source/projections/euler.rst b/docs/source/usage/operations/projections/euler.rst
index e495063f..e495063f 100644
--- a/docs/source/projections/euler.rst
+++ b/docs/source/usage/operations/projections/euler.rst
diff --git a/docs/source/projections/fahey.rst b/docs/source/usage/operations/projections/fahey.rst
index 2e09337f..2e09337f 100644
--- a/docs/source/projections/fahey.rst
+++ b/docs/source/usage/operations/projections/fahey.rst
diff --git a/docs/source/projections/fouc.rst b/docs/source/usage/operations/projections/fouc.rst
index 7467dcb1..7467dcb1 100644
--- a/docs/source/projections/fouc.rst
+++ b/docs/source/usage/operations/projections/fouc.rst
diff --git a/docs/source/projections/fouc_s.rst b/docs/source/usage/operations/projections/fouc_s.rst
index ac353adb..ac353adb 100644
--- a/docs/source/projections/fouc_s.rst
+++ b/docs/source/usage/operations/projections/fouc_s.rst
diff --git a/docs/source/projections/gall.rst b/docs/source/usage/operations/projections/gall.rst
index b9120d9f..b9120d9f 100644
--- a/docs/source/projections/gall.rst
+++ b/docs/source/usage/operations/projections/gall.rst
diff --git a/docs/source/projections/geos.rst b/docs/source/usage/operations/projections/geos.rst
index 2e309241..3b24e1f7 100644
--- a/docs/source/projections/geos.rst
+++ b/docs/source/usage/operations/projections/geos.rst
@@ -55,7 +55,7 @@ projection have a two-axis gimbal viewing geometry. This means that the differen
 scanning positions are obtained by rotating the gimbal along a N/S axis (or ``y``)
 and a E/W axis (or ``x``).
 
-.. image:: ../../images/geos_sweep.png
+.. image:: ../../../../images/geos_sweep.png
    :scale: 50%
    :alt:   Gimbal geometry
 
@@ -66,7 +66,7 @@ This example represents the scanning geometry of the Meteosat series satellite.
 However, the GOES satellite series use the opposite scanning geometry, with the
 E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle axis.
 
-The sweep argument is used to tell proj.4 which on which axis the outer-gimbal
+The sweep argument is used to tell PROJ.4 which on which axis the outer-gimbal
 is rotating. The possible values are x or y, y being the default. Thus, the
 scanning geometry of the Meteosat series satellite should take sweep as x, and
 GOES should take sweep as y.
diff --git a/docs/source/projections/gins8.rst b/docs/source/usage/operations/projections/gins8.rst
index f6adb092..f6adb092 100644
--- a/docs/source/projections/gins8.rst
+++ b/docs/source/usage/operations/projections/gins8.rst
diff --git a/docs/source/projections/gn_sinu.rst b/docs/source/usage/operations/projections/gn_sinu.rst
index c1017c27..c1017c27 100644
--- a/docs/source/projections/gn_sinu.rst
+++ b/docs/source/usage/operations/projections/gn_sinu.rst
diff --git a/docs/source/projections/gnom.rst b/docs/source/usage/operations/projections/gnom.rst
index 08d0db5f..08d0db5f 100644
--- a/docs/source/projections/gnom.rst
+++ b/docs/source/usage/operations/projections/gnom.rst
diff --git a/docs/source/projections/goode.rst b/docs/source/usage/operations/projections/goode.rst
index c4590bf2..c4590bf2 100644
--- a/docs/source/projections/goode.rst
+++ b/docs/source/usage/operations/projections/goode.rst
diff --git a/docs/source/projections/gs48.rst b/docs/source/usage/operations/projections/gs48.rst
index bdaa367c..bdaa367c 100644
--- a/docs/source/projections/gs48.rst
+++ b/docs/source/usage/operations/projections/gs48.rst
diff --git a/docs/source/projections/gs50.rst b/docs/source/usage/operations/projections/gs50.rst
index 0d4b7e81..0d4b7e81 100644
--- a/docs/source/projections/gs50.rst
+++ b/docs/source/usage/operations/projections/gs50.rst
diff --git a/docs/source/projections/gstmerc.rst b/docs/source/usage/operations/projections/gstmerc.rst
index fc587ab0..fc587ab0 100644
--- a/docs/source/projections/gstmerc.rst
+++ b/docs/source/usage/operations/projections/gstmerc.rst
diff --git a/docs/source/projections/hammer.rst b/docs/source/usage/operations/projections/hammer.rst
index e795b91b..e795b91b 100644
--- a/docs/source/projections/hammer.rst
+++ b/docs/source/usage/operations/projections/hammer.rst
diff --git a/docs/source/projections/hatano.rst b/docs/source/usage/operations/projections/hatano.rst
index 5d0c63b7..5d0c63b7 100644
--- a/docs/source/projections/hatano.rst
+++ b/docs/source/usage/operations/projections/hatano.rst
diff --git a/docs/source/projections/healpix.rst b/docs/source/usage/operations/projections/healpix.rst
index 885ea3ea..20815d76 100644
--- a/docs/source/projections/healpix.rst
+++ b/docs/source/usage/operations/projections/healpix.rst
@@ -17,7 +17,7 @@ HEALPix
 | `No special options for this projection`                                       |
 +---------------------+----------------------------------------------------------+
 
-.. image:: ../../images/healpix.png
+.. image:: ../../../../images/healpix.png
    :scale: 75%
    :alt:   HEALPix
 
diff --git a/docs/source/projections/igh.rst b/docs/source/usage/operations/projections/igh.rst
index d74e1362..d74e1362 100644
--- a/docs/source/projections/igh.rst
+++ b/docs/source/usage/operations/projections/igh.rst
diff --git a/docs/source/projections/images/aea.png b/docs/source/usage/operations/projections/images/aea.png
index 7fdd4ece..7fdd4ece 100644
--- a/docs/source/projections/images/aea.png
+++ b/docs/source/usage/operations/projections/images/aea.png
diff --git a/docs/source/projections/images/aeqd.png b/docs/source/usage/operations/projections/images/aeqd.png
index 8e45b2c0..8e45b2c0 100644
--- a/docs/source/projections/images/aeqd.png
+++ b/docs/source/usage/operations/projections/images/aeqd.png
diff --git a/docs/source/projections/images/airy.png b/docs/source/usage/operations/projections/images/airy.png
index a441e317..a441e317 100644
--- a/docs/source/projections/images/airy.png
+++ b/docs/source/usage/operations/projections/images/airy.png
diff --git a/docs/source/projections/images/aitoff.png b/docs/source/usage/operations/projections/images/aitoff.png
index 3449dcd5..3449dcd5 100644
--- a/docs/source/projections/images/aitoff.png
+++ b/docs/source/usage/operations/projections/images/aitoff.png
diff --git a/docs/source/projections/images/alsk.png b/docs/source/usage/operations/projections/images/alsk.png
index 6f6e2014..6f6e2014 100644
--- a/docs/source/projections/images/alsk.png
+++ b/docs/source/usage/operations/projections/images/alsk.png
diff --git a/docs/source/projections/images/apian.png b/docs/source/usage/operations/projections/images/apian.png
index 95857ae3..95857ae3 100644
--- a/docs/source/projections/images/apian.png
+++ b/docs/source/usage/operations/projections/images/apian.png
diff --git a/docs/source/projections/images/august.png b/docs/source/usage/operations/projections/images/august.png
index 9d9fece6..9d9fece6 100644
--- a/docs/source/projections/images/august.png
+++ b/docs/source/usage/operations/projections/images/august.png
diff --git a/docs/source/projections/images/bacon.png b/docs/source/usage/operations/projections/images/bacon.png
index 62deae63..62deae63 100644
--- a/docs/source/projections/images/bacon.png
+++ b/docs/source/usage/operations/projections/images/bacon.png
diff --git a/docs/source/projections/images/bipc.png b/docs/source/usage/operations/projections/images/bipc.png
index 7b8ab39c..7b8ab39c 100644
--- a/docs/source/projections/images/bipc.png
+++ b/docs/source/usage/operations/projections/images/bipc.png
diff --git a/docs/source/projections/images/boggs.png b/docs/source/usage/operations/projections/images/boggs.png
index 42dd4c13..42dd4c13 100644
--- a/docs/source/projections/images/boggs.png
+++ b/docs/source/usage/operations/projections/images/boggs.png
diff --git a/docs/source/projections/images/bonne.png b/docs/source/usage/operations/projections/images/bonne.png
index 12f93217..12f93217 100644
--- a/docs/source/projections/images/bonne.png
+++ b/docs/source/usage/operations/projections/images/bonne.png
diff --git a/docs/source/projections/images/calcofi.png b/docs/source/usage/operations/projections/images/calcofi.png
index 2fd405ac..2fd405ac 100644
--- a/docs/source/projections/images/calcofi.png
+++ b/docs/source/usage/operations/projections/images/calcofi.png
diff --git a/docs/source/projections/images/cass.png b/docs/source/usage/operations/projections/images/cass.png
index e44c46af..e44c46af 100644
--- a/docs/source/projections/images/cass.png
+++ b/docs/source/usage/operations/projections/images/cass.png
diff --git a/docs/source/projections/images/cc.png b/docs/source/usage/operations/projections/images/cc.png
index 3beaedfd..3beaedfd 100644
--- a/docs/source/projections/images/cc.png
+++ b/docs/source/usage/operations/projections/images/cc.png
diff --git a/docs/source/projections/images/ccon.png b/docs/source/usage/operations/projections/images/ccon.png
index ccc0ec9e..ccc0ec9e 100644
--- a/docs/source/projections/images/ccon.png
+++ b/docs/source/usage/operations/projections/images/ccon.png
diff --git a/docs/source/projections/images/cea.png b/docs/source/usage/operations/projections/images/cea.png
index eca2319d..eca2319d 100644
--- a/docs/source/projections/images/cea.png
+++ b/docs/source/usage/operations/projections/images/cea.png
diff --git a/docs/source/projections/images/chamb.png b/docs/source/usage/operations/projections/images/chamb.png
index a87e6c68..a87e6c68 100644
--- a/docs/source/projections/images/chamb.png
+++ b/docs/source/usage/operations/projections/images/chamb.png
diff --git a/docs/source/projections/images/collg.png b/docs/source/usage/operations/projections/images/collg.png
index 851201da..851201da 100644
--- a/docs/source/projections/images/collg.png
+++ b/docs/source/usage/operations/projections/images/collg.png
diff --git a/docs/source/projections/images/comill.png b/docs/source/usage/operations/projections/images/comill.png
index 725a0118..725a0118 100644
--- a/docs/source/projections/images/comill.png
+++ b/docs/source/usage/operations/projections/images/comill.png
diff --git a/docs/source/projections/images/crast.png b/docs/source/usage/operations/projections/images/crast.png
index abd4d32a..abd4d32a 100644
--- a/docs/source/projections/images/crast.png
+++ b/docs/source/usage/operations/projections/images/crast.png
diff --git a/docs/source/projections/images/denoy.png b/docs/source/usage/operations/projections/images/denoy.png
index 2871cf84..2871cf84 100644
--- a/docs/source/projections/images/denoy.png
+++ b/docs/source/usage/operations/projections/images/denoy.png
diff --git a/docs/source/projections/images/eck1.png b/docs/source/usage/operations/projections/images/eck1.png
index b892d39e..b892d39e 100644
--- a/docs/source/projections/images/eck1.png
+++ b/docs/source/usage/operations/projections/images/eck1.png
diff --git a/docs/source/projections/images/eck2.png b/docs/source/usage/operations/projections/images/eck2.png
index ff011598..ff011598 100644
--- a/docs/source/projections/images/eck2.png
+++ b/docs/source/usage/operations/projections/images/eck2.png
diff --git a/docs/source/projections/images/eck3.png b/docs/source/usage/operations/projections/images/eck3.png
index f828eed0..f828eed0 100644
--- a/docs/source/projections/images/eck3.png
+++ b/docs/source/usage/operations/projections/images/eck3.png
diff --git a/docs/source/projections/images/eck4.png b/docs/source/usage/operations/projections/images/eck4.png
index d7ff87bb..d7ff87bb 100644
--- a/docs/source/projections/images/eck4.png
+++ b/docs/source/usage/operations/projections/images/eck4.png
diff --git a/docs/source/projections/images/eck5.png b/docs/source/usage/operations/projections/images/eck5.png
index 3df303c6..3df303c6 100644
--- a/docs/source/projections/images/eck5.png
+++ b/docs/source/usage/operations/projections/images/eck5.png
diff --git a/docs/source/projections/images/eck6.png b/docs/source/usage/operations/projections/images/eck6.png
index d22f4956..d22f4956 100644
--- a/docs/source/projections/images/eck6.png
+++ b/docs/source/usage/operations/projections/images/eck6.png
diff --git a/docs/source/projections/images/eqc.png b/docs/source/usage/operations/projections/images/eqc.png
index b2d8ba23..b2d8ba23 100644
--- a/docs/source/projections/images/eqc.png
+++ b/docs/source/usage/operations/projections/images/eqc.png
diff --git a/docs/source/projections/images/eqdc.png b/docs/source/usage/operations/projections/images/eqdc.png
index f2330a8e..f2330a8e 100644
--- a/docs/source/projections/images/eqdc.png
+++ b/docs/source/usage/operations/projections/images/eqdc.png
diff --git a/docs/source/projections/images/etmerc.png b/docs/source/usage/operations/projections/images/etmerc.png
index 8e6bb39b..8e6bb39b 100644
--- a/docs/source/projections/images/etmerc.png
+++ b/docs/source/usage/operations/projections/images/etmerc.png
diff --git a/docs/source/projections/images/euler.png b/docs/source/usage/operations/projections/images/euler.png
index c9c6e4c8..c9c6e4c8 100644
--- a/docs/source/projections/images/euler.png
+++ b/docs/source/usage/operations/projections/images/euler.png
diff --git a/docs/source/projections/images/fahey.png b/docs/source/usage/operations/projections/images/fahey.png
index 8b870b8a..8b870b8a 100644
--- a/docs/source/projections/images/fahey.png
+++ b/docs/source/usage/operations/projections/images/fahey.png
diff --git a/docs/source/projections/images/fouc.png b/docs/source/usage/operations/projections/images/fouc.png
index 6d33216b..6d33216b 100644
--- a/docs/source/projections/images/fouc.png
+++ b/docs/source/usage/operations/projections/images/fouc.png
diff --git a/docs/source/projections/images/fouc_s.png b/docs/source/usage/operations/projections/images/fouc_s.png
index 401f5ee4..401f5ee4 100644
--- a/docs/source/projections/images/fouc_s.png
+++ b/docs/source/usage/operations/projections/images/fouc_s.png
diff --git a/docs/source/projections/images/gall.png b/docs/source/usage/operations/projections/images/gall.png
index 819b5d12..819b5d12 100644
--- a/docs/source/projections/images/gall.png
+++ b/docs/source/usage/operations/projections/images/gall.png
diff --git a/docs/source/projections/images/geos.png b/docs/source/usage/operations/projections/images/geos.png
index e44fa41b..e44fa41b 100644
--- a/docs/source/projections/images/geos.png
+++ b/docs/source/usage/operations/projections/images/geos.png
diff --git a/docs/source/projections/images/gins8.png b/docs/source/usage/operations/projections/images/gins8.png
index 12fbae93..12fbae93 100644
--- a/docs/source/projections/images/gins8.png
+++ b/docs/source/usage/operations/projections/images/gins8.png
diff --git a/docs/source/projections/images/gn_sinu.png b/docs/source/usage/operations/projections/images/gn_sinu.png
index f02e119e..f02e119e 100644
--- a/docs/source/projections/images/gn_sinu.png
+++ b/docs/source/usage/operations/projections/images/gn_sinu.png
diff --git a/docs/source/projections/images/gnom.png b/docs/source/usage/operations/projections/images/gnom.png
index c079d31a..c079d31a 100644
--- a/docs/source/projections/images/gnom.png
+++ b/docs/source/usage/operations/projections/images/gnom.png
diff --git a/docs/source/projections/images/goode.png b/docs/source/usage/operations/projections/images/goode.png
index 7001e8d2..7001e8d2 100644
--- a/docs/source/projections/images/goode.png
+++ b/docs/source/usage/operations/projections/images/goode.png
diff --git a/docs/source/projections/images/gs48.png b/docs/source/usage/operations/projections/images/gs48.png
index 574e368f..574e368f 100644
--- a/docs/source/projections/images/gs48.png
+++ b/docs/source/usage/operations/projections/images/gs48.png
diff --git a/docs/source/projections/images/gs50.png b/docs/source/usage/operations/projections/images/gs50.png
index 7244b160..7244b160 100644
--- a/docs/source/projections/images/gs50.png
+++ b/docs/source/usage/operations/projections/images/gs50.png
diff --git a/docs/source/projections/images/gstmerc.png b/docs/source/usage/operations/projections/images/gstmerc.png
index d553ea60..d553ea60 100644
--- a/docs/source/projections/images/gstmerc.png
+++ b/docs/source/usage/operations/projections/images/gstmerc.png
diff --git a/docs/source/projections/images/hammer.png b/docs/source/usage/operations/projections/images/hammer.png
index 83848479..83848479 100644
--- a/docs/source/projections/images/hammer.png
+++ b/docs/source/usage/operations/projections/images/hammer.png
diff --git a/docs/source/projections/images/hatano.png b/docs/source/usage/operations/projections/images/hatano.png
index b3f47377..b3f47377 100644
--- a/docs/source/projections/images/hatano.png
+++ b/docs/source/usage/operations/projections/images/hatano.png
diff --git a/docs/source/projections/images/healpix.png b/docs/source/usage/operations/projections/images/healpix.png
index c58a155c..c58a155c 100644
--- a/docs/source/projections/images/healpix.png
+++ b/docs/source/usage/operations/projections/images/healpix.png
diff --git a/docs/source/projections/images/igh.png b/docs/source/usage/operations/projections/images/igh.png
index 36336eec..36336eec 100644
--- a/docs/source/projections/images/igh.png
+++ b/docs/source/usage/operations/projections/images/igh.png
diff --git a/docs/source/projections/images/imw_p.png b/docs/source/usage/operations/projections/images/imw_p.png
index 74cfe81b..74cfe81b 100644
--- a/docs/source/projections/images/imw_p.png
+++ b/docs/source/usage/operations/projections/images/imw_p.png
diff --git a/docs/source/projections/images/isea.png b/docs/source/usage/operations/projections/images/isea.png
index 23cfbf74..23cfbf74 100644
--- a/docs/source/projections/images/isea.png
+++ b/docs/source/usage/operations/projections/images/isea.png
diff --git a/docs/source/projections/images/kav5.png b/docs/source/usage/operations/projections/images/kav5.png
index d5c45400..d5c45400 100644
--- a/docs/source/projections/images/kav5.png
+++ b/docs/source/usage/operations/projections/images/kav5.png
diff --git a/docs/source/projections/images/kav7.png b/docs/source/usage/operations/projections/images/kav7.png
index 50d7e6e6..50d7e6e6 100644
--- a/docs/source/projections/images/kav7.png
+++ b/docs/source/usage/operations/projections/images/kav7.png
diff --git a/docs/source/projections/images/krovak.png b/docs/source/usage/operations/projections/images/krovak.png
index d0d69547..d0d69547 100644
--- a/docs/source/projections/images/krovak.png
+++ b/docs/source/usage/operations/projections/images/krovak.png
diff --git a/docs/source/projections/images/labrd.png b/docs/source/usage/operations/projections/images/labrd.png
index e4a174c0..e4a174c0 100644
--- a/docs/source/projections/images/labrd.png
+++ b/docs/source/usage/operations/projections/images/labrd.png
diff --git a/docs/source/projections/images/laea.png b/docs/source/usage/operations/projections/images/laea.png
index f52c7c1f..f52c7c1f 100644
--- a/docs/source/projections/images/laea.png
+++ b/docs/source/usage/operations/projections/images/laea.png
diff --git a/docs/source/projections/images/lagrng.png b/docs/source/usage/operations/projections/images/lagrng.png
index e48210bb..e48210bb 100644
--- a/docs/source/projections/images/lagrng.png
+++ b/docs/source/usage/operations/projections/images/lagrng.png
diff --git a/docs/source/projections/images/larr.png b/docs/source/usage/operations/projections/images/larr.png
index 967b91d2..967b91d2 100644
--- a/docs/source/projections/images/larr.png
+++ b/docs/source/usage/operations/projections/images/larr.png
diff --git a/docs/source/projections/images/lask.png b/docs/source/usage/operations/projections/images/lask.png
index dff0e8fa..dff0e8fa 100644
--- a/docs/source/projections/images/lask.png
+++ b/docs/source/usage/operations/projections/images/lask.png
diff --git a/docs/source/projections/images/lcc.png b/docs/source/usage/operations/projections/images/lcc.png
index 4714b74e..4714b74e 100644
--- a/docs/source/projections/images/lcc.png
+++ b/docs/source/usage/operations/projections/images/lcc.png
diff --git a/docs/source/projections/images/lcca.png b/docs/source/usage/operations/projections/images/lcca.png
index 0c404670..0c404670 100644
--- a/docs/source/projections/images/lcca.png
+++ b/docs/source/usage/operations/projections/images/lcca.png
diff --git a/docs/source/projections/images/leac.png b/docs/source/usage/operations/projections/images/leac.png
index 1f57d192..1f57d192 100644
--- a/docs/source/projections/images/leac.png
+++ b/docs/source/usage/operations/projections/images/leac.png
diff --git a/docs/source/projections/images/lee_os.png b/docs/source/usage/operations/projections/images/lee_os.png
index 3e258393..3e258393 100644
--- a/docs/source/projections/images/lee_os.png
+++ b/docs/source/usage/operations/projections/images/lee_os.png
diff --git a/docs/source/projections/images/loxim.png b/docs/source/usage/operations/projections/images/loxim.png
index a03ba94e..a03ba94e 100644
--- a/docs/source/projections/images/loxim.png
+++ b/docs/source/usage/operations/projections/images/loxim.png
diff --git a/docs/source/projections/images/lsat.png b/docs/source/usage/operations/projections/images/lsat.png
index ec608544..ec608544 100644
--- a/docs/source/projections/images/lsat.png
+++ b/docs/source/usage/operations/projections/images/lsat.png
diff --git a/docs/source/projections/images/mbt_fps.png b/docs/source/usage/operations/projections/images/mbt_fps.png
index e97cd21e..e97cd21e 100644
--- a/docs/source/projections/images/mbt_fps.png
+++ b/docs/source/usage/operations/projections/images/mbt_fps.png
diff --git a/docs/source/projections/images/mbt_s.png b/docs/source/usage/operations/projections/images/mbt_s.png
index 4432e83b..4432e83b 100644
--- a/docs/source/projections/images/mbt_s.png
+++ b/docs/source/usage/operations/projections/images/mbt_s.png
diff --git a/docs/source/projections/images/mbtfpp.png b/docs/source/usage/operations/projections/images/mbtfpp.png
index 3d0c4fb5..3d0c4fb5 100644
--- a/docs/source/projections/images/mbtfpp.png
+++ b/docs/source/usage/operations/projections/images/mbtfpp.png
diff --git a/docs/source/projections/images/mbtfpq.png b/docs/source/usage/operations/projections/images/mbtfpq.png
index b31c52ce..b31c52ce 100644
--- a/docs/source/projections/images/mbtfpq.png
+++ b/docs/source/usage/operations/projections/images/mbtfpq.png
diff --git a/docs/source/projections/images/mbtfps.png b/docs/source/usage/operations/projections/images/mbtfps.png
index 83891be6..83891be6 100644
--- a/docs/source/projections/images/mbtfps.png
+++ b/docs/source/usage/operations/projections/images/mbtfps.png
diff --git a/docs/source/projections/images/merc.png b/docs/source/usage/operations/projections/images/merc.png
index 8202789e..8202789e 100644
--- a/docs/source/projections/images/merc.png
+++ b/docs/source/usage/operations/projections/images/merc.png
diff --git a/docs/source/projections/images/mil_os.png b/docs/source/usage/operations/projections/images/mil_os.png
index 3316d317..3316d317 100644
--- a/docs/source/projections/images/mil_os.png
+++ b/docs/source/usage/operations/projections/images/mil_os.png
diff --git a/docs/source/projections/images/mill.png b/docs/source/usage/operations/projections/images/mill.png
index f62e517c..f62e517c 100644
--- a/docs/source/projections/images/mill.png
+++ b/docs/source/usage/operations/projections/images/mill.png
diff --git a/docs/source/projections/images/misrsom.png b/docs/source/usage/operations/projections/images/misrsom.png
index 493baff3..493baff3 100644
--- a/docs/source/projections/images/misrsom.png
+++ b/docs/source/usage/operations/projections/images/misrsom.png
diff --git a/docs/source/projections/images/moll.png b/docs/source/usage/operations/projections/images/moll.png
index 5d599579..5d599579 100644
--- a/docs/source/projections/images/moll.png
+++ b/docs/source/usage/operations/projections/images/moll.png
diff --git a/docs/source/projections/images/murd1.png b/docs/source/usage/operations/projections/images/murd1.png
index 34d628c5..34d628c5 100644
--- a/docs/source/projections/images/murd1.png
+++ b/docs/source/usage/operations/projections/images/murd1.png
diff --git a/docs/source/projections/images/murd2.png b/docs/source/usage/operations/projections/images/murd2.png
index b3fdabdd..b3fdabdd 100644
--- a/docs/source/projections/images/murd2.png
+++ b/docs/source/usage/operations/projections/images/murd2.png
diff --git a/docs/source/projections/images/murd3.png b/docs/source/usage/operations/projections/images/murd3.png
index 354b009c..354b009c 100644
--- a/docs/source/projections/images/murd3.png
+++ b/docs/source/usage/operations/projections/images/murd3.png
diff --git a/docs/source/projections/images/natearth.png b/docs/source/usage/operations/projections/images/natearth.png
index 0e182a0b..0e182a0b 100644
--- a/docs/source/projections/images/natearth.png
+++ b/docs/source/usage/operations/projections/images/natearth.png
diff --git a/docs/source/projections/images/natearth2.png b/docs/source/usage/operations/projections/images/natearth2.png
index 3757646c..3757646c 100644
--- a/docs/source/projections/images/natearth2.png
+++ b/docs/source/usage/operations/projections/images/natearth2.png
diff --git a/docs/source/projections/images/nell.png b/docs/source/usage/operations/projections/images/nell.png
index c0dbdcac..c0dbdcac 100644
--- a/docs/source/projections/images/nell.png
+++ b/docs/source/usage/operations/projections/images/nell.png
diff --git a/docs/source/projections/images/nell_h.png b/docs/source/usage/operations/projections/images/nell_h.png
index a5a27076..a5a27076 100644
--- a/docs/source/projections/images/nell_h.png
+++ b/docs/source/usage/operations/projections/images/nell_h.png
diff --git a/docs/source/projections/images/nicol.png b/docs/source/usage/operations/projections/images/nicol.png
index 711db115..711db115 100644
--- a/docs/source/projections/images/nicol.png
+++ b/docs/source/usage/operations/projections/images/nicol.png
diff --git a/docs/source/projections/images/nsper.png b/docs/source/usage/operations/projections/images/nsper.png
index 06f210a1..06f210a1 100644
--- a/docs/source/projections/images/nsper.png
+++ b/docs/source/usage/operations/projections/images/nsper.png
diff --git a/docs/source/projections/images/nzmg.png b/docs/source/usage/operations/projections/images/nzmg.png
index 3625f331..3625f331 100644
--- a/docs/source/projections/images/nzmg.png
+++ b/docs/source/usage/operations/projections/images/nzmg.png
diff --git a/docs/source/projections/images/ob_tran.png b/docs/source/usage/operations/projections/images/ob_tran.png
index 9b1e0d44..9b1e0d44 100644
--- a/docs/source/projections/images/ob_tran.png
+++ b/docs/source/usage/operations/projections/images/ob_tran.png
diff --git a/docs/source/projections/images/ocea.png b/docs/source/usage/operations/projections/images/ocea.png
index 41a5a813..41a5a813 100644
--- a/docs/source/projections/images/ocea.png
+++ b/docs/source/usage/operations/projections/images/ocea.png
diff --git a/docs/source/projections/images/oea.png b/docs/source/usage/operations/projections/images/oea.png
index 601ead55..601ead55 100644
--- a/docs/source/projections/images/oea.png
+++ b/docs/source/usage/operations/projections/images/oea.png
diff --git a/docs/source/projections/images/omerc.png b/docs/source/usage/operations/projections/images/omerc.png
index 50a3d2b7..50a3d2b7 100644
--- a/docs/source/projections/images/omerc.png
+++ b/docs/source/usage/operations/projections/images/omerc.png
diff --git a/docs/source/projections/images/ortel.png b/docs/source/usage/operations/projections/images/ortel.png
index c6a5bf4f..c6a5bf4f 100644
--- a/docs/source/projections/images/ortel.png
+++ b/docs/source/usage/operations/projections/images/ortel.png
diff --git a/docs/source/projections/images/ortho.png b/docs/source/usage/operations/projections/images/ortho.png
index e8b0b9b2..e8b0b9b2 100644
--- a/docs/source/projections/images/ortho.png
+++ b/docs/source/usage/operations/projections/images/ortho.png
diff --git a/docs/source/projections/images/patterson.png b/docs/source/usage/operations/projections/images/patterson.png
index f8014249..f8014249 100644
--- a/docs/source/projections/images/patterson.png
+++ b/docs/source/usage/operations/projections/images/patterson.png
diff --git a/docs/source/projections/images/pconic.png b/docs/source/usage/operations/projections/images/pconic.png
index 7d7f9f92..7d7f9f92 100644
--- a/docs/source/projections/images/pconic.png
+++ b/docs/source/usage/operations/projections/images/pconic.png
diff --git a/docs/source/projections/images/poly.png b/docs/source/usage/operations/projections/images/poly.png
index ccf25529..ccf25529 100644
--- a/docs/source/projections/images/poly.png
+++ b/docs/source/usage/operations/projections/images/poly.png
diff --git a/docs/source/projections/images/putp1.png b/docs/source/usage/operations/projections/images/putp1.png
index c81f574c..c81f574c 100644
--- a/docs/source/projections/images/putp1.png
+++ b/docs/source/usage/operations/projections/images/putp1.png
diff --git a/docs/source/projections/images/putp2.png b/docs/source/usage/operations/projections/images/putp2.png
index 377a027c..377a027c 100644
--- a/docs/source/projections/images/putp2.png
+++ b/docs/source/usage/operations/projections/images/putp2.png
diff --git a/docs/source/projections/images/putp3.png b/docs/source/usage/operations/projections/images/putp3.png
index 08692ca1..08692ca1 100644
--- a/docs/source/projections/images/putp3.png
+++ b/docs/source/usage/operations/projections/images/putp3.png
diff --git a/docs/source/projections/images/putp3p.png b/docs/source/usage/operations/projections/images/putp3p.png
index 9e42319c..9e42319c 100644
--- a/docs/source/projections/images/putp3p.png
+++ b/docs/source/usage/operations/projections/images/putp3p.png
diff --git a/docs/source/projections/images/putp4p.png b/docs/source/usage/operations/projections/images/putp4p.png
index 43cb10c6..43cb10c6 100644
--- a/docs/source/projections/images/putp4p.png
+++ b/docs/source/usage/operations/projections/images/putp4p.png
diff --git a/docs/source/projections/images/putp5.png b/docs/source/usage/operations/projections/images/putp5.png
index 4e45de6d..4e45de6d 100644
--- a/docs/source/projections/images/putp5.png
+++ b/docs/source/usage/operations/projections/images/putp5.png
diff --git a/docs/source/projections/images/putp5p.png b/docs/source/usage/operations/projections/images/putp5p.png
index 76dcb767..76dcb767 100644
--- a/docs/source/projections/images/putp5p.png
+++ b/docs/source/usage/operations/projections/images/putp5p.png
diff --git a/docs/source/projections/images/putp6.png b/docs/source/usage/operations/projections/images/putp6.png
index c73585ee..c73585ee 100644
--- a/docs/source/projections/images/putp6.png
+++ b/docs/source/usage/operations/projections/images/putp6.png
diff --git a/docs/source/projections/images/putp6p.png b/docs/source/usage/operations/projections/images/putp6p.png
index d64c2c20..d64c2c20 100644
--- a/docs/source/projections/images/putp6p.png
+++ b/docs/source/usage/operations/projections/images/putp6p.png
diff --git a/docs/source/projections/images/qsc.png b/docs/source/usage/operations/projections/images/qsc.png
index 5824cf64..5824cf64 100644
--- a/docs/source/projections/images/qsc.png
+++ b/docs/source/usage/operations/projections/images/qsc.png
diff --git a/docs/source/projections/images/qua_aut.png b/docs/source/usage/operations/projections/images/qua_aut.png
index 6bc2d811..6bc2d811 100644
--- a/docs/source/projections/images/qua_aut.png
+++ b/docs/source/usage/operations/projections/images/qua_aut.png
diff --git a/docs/source/projections/images/rhealpix.png b/docs/source/usage/operations/projections/images/rhealpix.png
index dc1c344a..dc1c344a 100644
--- a/docs/source/projections/images/rhealpix.png
+++ b/docs/source/usage/operations/projections/images/rhealpix.png
diff --git a/docs/source/projections/images/robin.png b/docs/source/usage/operations/projections/images/robin.png
index 42a49da2..42a49da2 100644
--- a/docs/source/projections/images/robin.png
+++ b/docs/source/usage/operations/projections/images/robin.png
diff --git a/docs/source/projections/images/rouss.png b/docs/source/usage/operations/projections/images/rouss.png
index 2eca0fed..2eca0fed 100644
--- a/docs/source/projections/images/rouss.png
+++ b/docs/source/usage/operations/projections/images/rouss.png
diff --git a/docs/source/projections/images/rpoly.png b/docs/source/usage/operations/projections/images/rpoly.png
index 343127c1..343127c1 100644
--- a/docs/source/projections/images/rpoly.png
+++ b/docs/source/usage/operations/projections/images/rpoly.png
diff --git a/docs/source/projections/images/sinu.png b/docs/source/usage/operations/projections/images/sinu.png
index 9bef143a..9bef143a 100644
--- a/docs/source/projections/images/sinu.png
+++ b/docs/source/usage/operations/projections/images/sinu.png
diff --git a/docs/source/projections/images/somerc.png b/docs/source/usage/operations/projections/images/somerc.png
index 1248e6ea..1248e6ea 100644
--- a/docs/source/projections/images/somerc.png
+++ b/docs/source/usage/operations/projections/images/somerc.png
diff --git a/docs/source/projections/images/stere.png b/docs/source/usage/operations/projections/images/stere.png
index 840050f0..840050f0 100644
--- a/docs/source/projections/images/stere.png
+++ b/docs/source/usage/operations/projections/images/stere.png
diff --git a/docs/source/projections/images/sterea.png b/docs/source/usage/operations/projections/images/sterea.png
index d2aad552..d2aad552 100644
--- a/docs/source/projections/images/sterea.png
+++ b/docs/source/usage/operations/projections/images/sterea.png
diff --git a/docs/source/projections/images/tcc.png b/docs/source/usage/operations/projections/images/tcc.png
index f968f62d..f968f62d 100644
--- a/docs/source/projections/images/tcc.png
+++ b/docs/source/usage/operations/projections/images/tcc.png
diff --git a/docs/source/projections/images/tcea.png b/docs/source/usage/operations/projections/images/tcea.png
index 44212bd8..44212bd8 100644
--- a/docs/source/projections/images/tcea.png
+++ b/docs/source/usage/operations/projections/images/tcea.png
diff --git a/docs/source/projections/images/tissot.png b/docs/source/usage/operations/projections/images/tissot.png
index 2f785477..2f785477 100644
--- a/docs/source/projections/images/tissot.png
+++ b/docs/source/usage/operations/projections/images/tissot.png
diff --git a/docs/source/projections/images/tmerc.png b/docs/source/usage/operations/projections/images/tmerc.png
index b206c502..b206c502 100644
--- a/docs/source/projections/images/tmerc.png
+++ b/docs/source/usage/operations/projections/images/tmerc.png
diff --git a/docs/source/projections/images/tpeqd.png b/docs/source/usage/operations/projections/images/tpeqd.png
index 50291b68..50291b68 100644
--- a/docs/source/projections/images/tpeqd.png
+++ b/docs/source/usage/operations/projections/images/tpeqd.png
diff --git a/docs/source/projections/images/tpers.png b/docs/source/usage/operations/projections/images/tpers.png
index 480f6dce..480f6dce 100644
--- a/docs/source/projections/images/tpers.png
+++ b/docs/source/usage/operations/projections/images/tpers.png
diff --git a/docs/source/projections/images/ups.png b/docs/source/usage/operations/projections/images/ups.png
index 354b64ac..354b64ac 100644
--- a/docs/source/projections/images/ups.png
+++ b/docs/source/usage/operations/projections/images/ups.png
diff --git a/docs/source/projections/images/urm5.png b/docs/source/usage/operations/projections/images/urm5.png
index 088671c9..088671c9 100644
--- a/docs/source/projections/images/urm5.png
+++ b/docs/source/usage/operations/projections/images/urm5.png
diff --git a/docs/source/projections/images/urmfps.png b/docs/source/usage/operations/projections/images/urmfps.png
index 86432790..86432790 100644
--- a/docs/source/projections/images/urmfps.png
+++ b/docs/source/usage/operations/projections/images/urmfps.png
diff --git a/docs/source/projections/images/utm.png b/docs/source/usage/operations/projections/images/utm.png
index 3dcd5ee0..3dcd5ee0 100644
--- a/docs/source/projections/images/utm.png
+++ b/docs/source/usage/operations/projections/images/utm.png
diff --git a/docs/source/projections/images/vandg.png b/docs/source/usage/operations/projections/images/vandg.png
index 46fe2346..46fe2346 100644
--- a/docs/source/projections/images/vandg.png
+++ b/docs/source/usage/operations/projections/images/vandg.png
diff --git a/docs/source/projections/images/vandg2.png b/docs/source/usage/operations/projections/images/vandg2.png
index 597b5ae1..597b5ae1 100644
--- a/docs/source/projections/images/vandg2.png
+++ b/docs/source/usage/operations/projections/images/vandg2.png
diff --git a/docs/source/projections/images/vandg3.png b/docs/source/usage/operations/projections/images/vandg3.png
index 36d1ad04..36d1ad04 100644
--- a/docs/source/projections/images/vandg3.png
+++ b/docs/source/usage/operations/projections/images/vandg3.png
diff --git a/docs/source/projections/images/vandg4.png b/docs/source/usage/operations/projections/images/vandg4.png
index 163c1558..163c1558 100644
--- a/docs/source/projections/images/vandg4.png
+++ b/docs/source/usage/operations/projections/images/vandg4.png
diff --git a/docs/source/projections/images/vitk1.png b/docs/source/usage/operations/projections/images/vitk1.png
index 31034b3a..31034b3a 100644
--- a/docs/source/projections/images/vitk1.png
+++ b/docs/source/usage/operations/projections/images/vitk1.png
diff --git a/docs/source/projections/images/wag1.png b/docs/source/usage/operations/projections/images/wag1.png
index a2bc8adc..a2bc8adc 100644
--- a/docs/source/projections/images/wag1.png
+++ b/docs/source/usage/operations/projections/images/wag1.png
diff --git a/docs/source/projections/images/wag2.png b/docs/source/usage/operations/projections/images/wag2.png
index b4abb48c..b4abb48c 100644
--- a/docs/source/projections/images/wag2.png
+++ b/docs/source/usage/operations/projections/images/wag2.png
diff --git a/docs/source/projections/images/wag3.png b/docs/source/usage/operations/projections/images/wag3.png
index a2053815..a2053815 100644
--- a/docs/source/projections/images/wag3.png
+++ b/docs/source/usage/operations/projections/images/wag3.png
diff --git a/docs/source/projections/images/wag4.png b/docs/source/usage/operations/projections/images/wag4.png
index 7d1c50b3..7d1c50b3 100644
--- a/docs/source/projections/images/wag4.png
+++ b/docs/source/usage/operations/projections/images/wag4.png
diff --git a/docs/source/projections/images/wag5.png b/docs/source/usage/operations/projections/images/wag5.png
index 487f6022..487f6022 100644
--- a/docs/source/projections/images/wag5.png
+++ b/docs/source/usage/operations/projections/images/wag5.png
diff --git a/docs/source/projections/images/wag6.png b/docs/source/usage/operations/projections/images/wag6.png
index dd49e8d0..dd49e8d0 100644
--- a/docs/source/projections/images/wag6.png
+++ b/docs/source/usage/operations/projections/images/wag6.png
diff --git a/docs/source/projections/images/wag7.png b/docs/source/usage/operations/projections/images/wag7.png
index b9682755..b9682755 100644
--- a/docs/source/projections/images/wag7.png
+++ b/docs/source/usage/operations/projections/images/wag7.png
diff --git a/docs/source/projections/images/weren.png b/docs/source/usage/operations/projections/images/weren.png
index 7deb132f..7deb132f 100644
--- a/docs/source/projections/images/weren.png
+++ b/docs/source/usage/operations/projections/images/weren.png
diff --git a/docs/source/projections/images/wink1.png b/docs/source/usage/operations/projections/images/wink1.png
index 6cbf48ae..6cbf48ae 100644
--- a/docs/source/projections/images/wink1.png
+++ b/docs/source/usage/operations/projections/images/wink1.png
diff --git a/docs/source/projections/images/wink2.png b/docs/source/usage/operations/projections/images/wink2.png
index 21a23634..21a23634 100644
--- a/docs/source/projections/images/wink2.png
+++ b/docs/source/usage/operations/projections/images/wink2.png
diff --git a/docs/source/projections/images/wintri.png b/docs/source/usage/operations/projections/images/wintri.png
index 54a0a85a..54a0a85a 100644
--- a/docs/source/projections/images/wintri.png
+++ b/docs/source/usage/operations/projections/images/wintri.png
diff --git a/docs/source/projections/imw_p.rst b/docs/source/usage/operations/projections/imw_p.rst
index 1fd3ded0..1fd3ded0 100644
--- a/docs/source/projections/imw_p.rst
+++ b/docs/source/usage/operations/projections/imw_p.rst
diff --git a/docs/source/projections/index.rst b/docs/source/usage/operations/projections/index.rst
index 5ccf0045..f7eb0c67 100644
--- a/docs/source/projections/index.rst
+++ b/docs/source/usage/operations/projections/index.rst
@@ -4,6 +4,11 @@
 Projections
 ================================================================================
 
+Projections are coordinate operations that are technically conversions but since
+projections are so fundamental to PROJ.4 we differentiate them from conversions.
+
+Projections map the spherical 3D space to a flat 2D space.
+
 .. toctree::
    :maxdepth: 1
 
@@ -62,8 +67,6 @@ Projections
    lagrng
    larr
    lask
-   lonlat
-   latlon
    lcc
    lcca
    leac
diff --git a/docs/source/projections/isea.rst b/docs/source/usage/operations/projections/isea.rst
index 1b6457af..1b6457af 100644
--- a/docs/source/projections/isea.rst
+++ b/docs/source/usage/operations/projections/isea.rst
diff --git a/docs/source/projections/kav5.rst b/docs/source/usage/operations/projections/kav5.rst
index 2ec5d1c1..2ec5d1c1 100644
--- a/docs/source/projections/kav5.rst
+++ b/docs/source/usage/operations/projections/kav5.rst
diff --git a/docs/source/projections/kav7.rst b/docs/source/usage/operations/projections/kav7.rst
index 8371e6ea..8371e6ea 100644
--- a/docs/source/projections/kav7.rst
+++ b/docs/source/usage/operations/projections/kav7.rst
diff --git a/docs/source/projections/krovak.rst b/docs/source/usage/operations/projections/krovak.rst
index 6c774825..6c774825 100644
--- a/docs/source/projections/krovak.rst
+++ b/docs/source/usage/operations/projections/krovak.rst
diff --git a/docs/source/projections/labrd.rst b/docs/source/usage/operations/projections/labrd.rst
index 5be58db5..5be58db5 100644
--- a/docs/source/projections/labrd.rst
+++ b/docs/source/usage/operations/projections/labrd.rst
diff --git a/docs/source/projections/laea.rst b/docs/source/usage/operations/projections/laea.rst
index 2377f294..2377f294 100644
--- a/docs/source/projections/laea.rst
+++ b/docs/source/usage/operations/projections/laea.rst
diff --git a/docs/source/projections/lagrng.rst b/docs/source/usage/operations/projections/lagrng.rst
index de9e5640..de9e5640 100644
--- a/docs/source/projections/lagrng.rst
+++ b/docs/source/usage/operations/projections/lagrng.rst
diff --git a/docs/source/projections/larr.rst b/docs/source/usage/operations/projections/larr.rst
index 9529f83f..9529f83f 100644
--- a/docs/source/projections/larr.rst
+++ b/docs/source/usage/operations/projections/larr.rst
diff --git a/docs/source/projections/lask.rst b/docs/source/usage/operations/projections/lask.rst
index d34dc8a0..d34dc8a0 100644
--- a/docs/source/projections/lask.rst
+++ b/docs/source/usage/operations/projections/lask.rst
diff --git a/docs/source/projections/lcc.rst b/docs/source/usage/operations/projections/lcc.rst
index a3075e76..a3075e76 100644
--- a/docs/source/projections/lcc.rst
+++ b/docs/source/usage/operations/projections/lcc.rst
diff --git a/docs/source/projections/lcca.rst b/docs/source/usage/operations/projections/lcca.rst
index ca87e67e..ca87e67e 100644
--- a/docs/source/projections/lcca.rst
+++ b/docs/source/usage/operations/projections/lcca.rst
diff --git a/docs/source/projections/leac.rst b/docs/source/usage/operations/projections/leac.rst
index 2957798e..2957798e 100644
--- a/docs/source/projections/leac.rst
+++ b/docs/source/usage/operations/projections/leac.rst
diff --git a/docs/source/projections/lee_os.rst b/docs/source/usage/operations/projections/lee_os.rst
index 711dc754..711dc754 100644
--- a/docs/source/projections/lee_os.rst
+++ b/docs/source/usage/operations/projections/lee_os.rst
diff --git a/docs/source/projections/loxim.rst b/docs/source/usage/operations/projections/loxim.rst
index e50ba472..e50ba472 100644
--- a/docs/source/projections/loxim.rst
+++ b/docs/source/usage/operations/projections/loxim.rst
diff --git a/docs/source/projections/lsat.rst b/docs/source/usage/operations/projections/lsat.rst
index fb64bdb2..fb64bdb2 100644
--- a/docs/source/projections/lsat.rst
+++ b/docs/source/usage/operations/projections/lsat.rst
diff --git a/docs/source/projections/mbt_fps.rst b/docs/source/usage/operations/projections/mbt_fps.rst
index 55ebcf6c..55ebcf6c 100644
--- a/docs/source/projections/mbt_fps.rst
+++ b/docs/source/usage/operations/projections/mbt_fps.rst
diff --git a/docs/source/projections/mbt_s.rst b/docs/source/usage/operations/projections/mbt_s.rst
index 9a355ec8..9a355ec8 100644
--- a/docs/source/projections/mbt_s.rst
+++ b/docs/source/usage/operations/projections/mbt_s.rst
diff --git a/docs/source/projections/mbtfpp.rst b/docs/source/usage/operations/projections/mbtfpp.rst
index 9be309d9..9be309d9 100644
--- a/docs/source/projections/mbtfpp.rst
+++ b/docs/source/usage/operations/projections/mbtfpp.rst
diff --git a/docs/source/projections/mbtfpq.rst b/docs/source/usage/operations/projections/mbtfpq.rst
index 295e814d..295e814d 100644
--- a/docs/source/projections/mbtfpq.rst
+++ b/docs/source/usage/operations/projections/mbtfpq.rst
diff --git a/docs/source/projections/mbtfps.rst b/docs/source/usage/operations/projections/mbtfps.rst
index b9365361..b9365361 100644
--- a/docs/source/projections/mbtfps.rst
+++ b/docs/source/usage/operations/projections/mbtfps.rst
diff --git a/docs/source/projections/merc.rst b/docs/source/usage/operations/projections/merc.rst
index 64ba98a4..64ba98a4 100644
--- a/docs/source/projections/merc.rst
+++ b/docs/source/usage/operations/projections/merc.rst
diff --git a/docs/source/projections/mil_os.rst b/docs/source/usage/operations/projections/mil_os.rst
index 5547e43c..5547e43c 100644
--- a/docs/source/projections/mil_os.rst
+++ b/docs/source/usage/operations/projections/mil_os.rst
diff --git a/docs/source/projections/mill.rst b/docs/source/usage/operations/projections/mill.rst
index eb9c2092..eb9c2092 100644
--- a/docs/source/projections/mill.rst
+++ b/docs/source/usage/operations/projections/mill.rst
diff --git a/docs/source/projections/moll.rst b/docs/source/usage/operations/projections/moll.rst
index 1bd3d005..1bd3d005 100644
--- a/docs/source/projections/moll.rst
+++ b/docs/source/usage/operations/projections/moll.rst
diff --git a/docs/source/projections/murd1.rst b/docs/source/usage/operations/projections/murd1.rst
index 71cbf155..71cbf155 100644
--- a/docs/source/projections/murd1.rst
+++ b/docs/source/usage/operations/projections/murd1.rst
diff --git a/docs/source/projections/murd2.rst b/docs/source/usage/operations/projections/murd2.rst
index b55cde35..b55cde35 100644
--- a/docs/source/projections/murd2.rst
+++ b/docs/source/usage/operations/projections/murd2.rst
diff --git a/docs/source/projections/murd3.rst b/docs/source/usage/operations/projections/murd3.rst
index 70cc9276..70cc9276 100644
--- a/docs/source/projections/murd3.rst
+++ b/docs/source/usage/operations/projections/murd3.rst
diff --git a/docs/source/projections/natearth.rst b/docs/source/usage/operations/projections/natearth.rst
index 57dd96db..57dd96db 100644
--- a/docs/source/projections/natearth.rst
+++ b/docs/source/usage/operations/projections/natearth.rst
diff --git a/docs/source/projections/nell.rst b/docs/source/usage/operations/projections/nell.rst
index c6a3771c..c6a3771c 100644
--- a/docs/source/projections/nell.rst
+++ b/docs/source/usage/operations/projections/nell.rst
diff --git a/docs/source/projections/nell_h.rst b/docs/source/usage/operations/projections/nell_h.rst
index 6a3b26ba..6a3b26ba 100644
--- a/docs/source/projections/nell_h.rst
+++ b/docs/source/usage/operations/projections/nell_h.rst
diff --git a/docs/source/projections/nicol.rst b/docs/source/usage/operations/projections/nicol.rst
index 995cedb5..995cedb5 100644
--- a/docs/source/projections/nicol.rst
+++ b/docs/source/usage/operations/projections/nicol.rst
diff --git a/docs/source/projections/nsper.rst b/docs/source/usage/operations/projections/nsper.rst
index 4a8651fc..4a8651fc 100644
--- a/docs/source/projections/nsper.rst
+++ b/docs/source/usage/operations/projections/nsper.rst
diff --git a/docs/source/projections/nzmg.rst b/docs/source/usage/operations/projections/nzmg.rst
index 926655d8..926655d8 100644
--- a/docs/source/projections/nzmg.rst
+++ b/docs/source/usage/operations/projections/nzmg.rst
diff --git a/docs/source/projections/ob_tran.rst b/docs/source/usage/operations/projections/ob_tran.rst
index 3c996336..3c996336 100644
--- a/docs/source/projections/ob_tran.rst
+++ b/docs/source/usage/operations/projections/ob_tran.rst
diff --git a/docs/source/projections/ocea.rst b/docs/source/usage/operations/projections/ocea.rst
index 40005d9e..40005d9e 100644
--- a/docs/source/projections/ocea.rst
+++ b/docs/source/usage/operations/projections/ocea.rst
diff --git a/docs/source/projections/oea.rst b/docs/source/usage/operations/projections/oea.rst
index 379dc157..379dc157 100644
--- a/docs/source/projections/oea.rst
+++ b/docs/source/usage/operations/projections/oea.rst
diff --git a/docs/source/projections/omerc.rst b/docs/source/usage/operations/projections/omerc.rst
index 114b9fa3..114b9fa3 100644
--- a/docs/source/projections/omerc.rst
+++ b/docs/source/usage/operations/projections/omerc.rst
diff --git a/docs/source/projections/ortel.rst b/docs/source/usage/operations/projections/ortel.rst
index 03f132ef..03f132ef 100644
--- a/docs/source/projections/ortel.rst
+++ b/docs/source/usage/operations/projections/ortel.rst
diff --git a/docs/source/projections/ortho.rst b/docs/source/usage/operations/projections/ortho.rst
index 131dbfc7..131dbfc7 100644
--- a/docs/source/projections/ortho.rst
+++ b/docs/source/usage/operations/projections/ortho.rst
diff --git a/docs/source/projections/pconic.rst b/docs/source/usage/operations/projections/pconic.rst
index 6bc0018e..6bc0018e 100644
--- a/docs/source/projections/pconic.rst
+++ b/docs/source/usage/operations/projections/pconic.rst
diff --git a/docs/source/projections/poly.rst b/docs/source/usage/operations/projections/poly.rst
index e252feb5..e252feb5 100644
--- a/docs/source/projections/poly.rst
+++ b/docs/source/usage/operations/projections/poly.rst
diff --git a/docs/source/projections/putp1.rst b/docs/source/usage/operations/projections/putp1.rst
index 68971a46..68971a46 100644
--- a/docs/source/projections/putp1.rst
+++ b/docs/source/usage/operations/projections/putp1.rst
diff --git a/docs/source/projections/putp2.rst b/docs/source/usage/operations/projections/putp2.rst
index 01ea8073..01ea8073 100644
--- a/docs/source/projections/putp2.rst
+++ b/docs/source/usage/operations/projections/putp2.rst
diff --git a/docs/source/projections/putp3.rst b/docs/source/usage/operations/projections/putp3.rst
index 3aa6b9e6..3aa6b9e6 100644
--- a/docs/source/projections/putp3.rst
+++ b/docs/source/usage/operations/projections/putp3.rst
diff --git a/docs/source/projections/putp3p.rst b/docs/source/usage/operations/projections/putp3p.rst
index 5b87512e..5b87512e 100644
--- a/docs/source/projections/putp3p.rst
+++ b/docs/source/usage/operations/projections/putp3p.rst
diff --git a/docs/source/projections/putp4p.rst b/docs/source/usage/operations/projections/putp4p.rst
index b211ad9b..b211ad9b 100644
--- a/docs/source/projections/putp4p.rst
+++ b/docs/source/usage/operations/projections/putp4p.rst
diff --git a/docs/source/projections/putp5.rst b/docs/source/usage/operations/projections/putp5.rst
index 5b60a961..5b60a961 100644
--- a/docs/source/projections/putp5.rst
+++ b/docs/source/usage/operations/projections/putp5.rst
diff --git a/docs/source/projections/putp5p.rst b/docs/source/usage/operations/projections/putp5p.rst
index f586b889..f586b889 100644
--- a/docs/source/projections/putp5p.rst
+++ b/docs/source/usage/operations/projections/putp5p.rst
diff --git a/docs/source/projections/putp6.rst b/docs/source/usage/operations/projections/putp6.rst
index 94683ace..94683ace 100644
--- a/docs/source/projections/putp6.rst
+++ b/docs/source/usage/operations/projections/putp6.rst
diff --git a/docs/source/projections/putp6p.rst b/docs/source/usage/operations/projections/putp6p.rst
index 8c3add71..8c3add71 100644
--- a/docs/source/projections/putp6p.rst
+++ b/docs/source/usage/operations/projections/putp6p.rst
diff --git a/docs/source/projections/qsc.rst b/docs/source/usage/operations/projections/qsc.rst
index dedd6ff4..e3af2cee 100644
--- a/docs/source/projections/qsc.rst
+++ b/docs/source/usage/operations/projections/qsc.rst
@@ -23,7 +23,7 @@ Quadrilateralized Spherical Cube
 The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project
 a sphere surface onto the six sides of a cube:
 
-.. image:: ../../images/qsc_concept.jpg
+.. image:: ../../../../images/qsc_concept.jpg
    :scale: 50%
    :align: center
    :alt:   Quadrilateralized Spherical Cube
@@ -112,32 +112,32 @@ Explanation:
 The resulting images can be laid out in a grid like below.
 
 
-.. |topside| image:: ../../images/qsc_topside.jpg
+.. |topside| image:: ../../../../images/qsc_topside.jpg
    :scale: 50%
    :align: middle
    :alt:   Top side
 
-.. |leftside| image:: ../../images/qsc_leftside.jpg
+.. |leftside| image:: ../../../../images/qsc_leftside.jpg
    :scale: 50%
    :align: middle
    :alt:   Left side
 
-.. |frontside| image:: ../../images/qsc_frontside.jpg
+.. |frontside| image:: ../../../../images/qsc_frontside.jpg
    :scale: 50%
    :align: middle
    :alt:   Front side
 
-.. |rightside| image:: ../../images/qsc_rightside.jpg
+.. |rightside| image:: ../../../../images/qsc_rightside.jpg
    :scale: 50%
    :align: middle
    :alt:   Right side
 
-.. |backside| image:: ../../images/qsc_backside.jpg
+.. |backside| image:: ../../../../images/qsc_backside.jpg
    :scale: 50%
    :align: middle
    :alt:   Back side
 
-.. |bottomside| image:: ../../images/qsc_bottomside.jpg
+.. |bottomside| image:: ../../../../images/qsc_bottomside.jpg
    :scale: 50%
    :align: middle
    :alt:   Bottom side
diff --git a/docs/source/projections/qua_aut.rst b/docs/source/usage/operations/projections/qua_aut.rst
index d3a0aece..d3a0aece 100644
--- a/docs/source/projections/qua_aut.rst
+++ b/docs/source/usage/operations/projections/qua_aut.rst
diff --git a/docs/source/projections/rhealpix.rst b/docs/source/usage/operations/projections/rhealpix.rst
index 1701558e..5808cfaa 100644
--- a/docs/source/projections/rhealpix.rst
+++ b/docs/source/usage/operations/projections/rhealpix.rst
@@ -21,7 +21,7 @@ rHEALPix
 |                     | Valid inputs are 0--3. Defaults to 0.                    |
 +---------------------+----------------------------------------------------------+
 
-.. image:: ../../images/rhealpix.png
+.. image:: ../../../../images/rhealpix.png
    :scale: 75%
    :alt:   rHEALPix
 
diff --git a/docs/source/projections/robin.rst b/docs/source/usage/operations/projections/robin.rst
index 3e58be46..3e58be46 100644
--- a/docs/source/projections/robin.rst
+++ b/docs/source/usage/operations/projections/robin.rst
diff --git a/docs/source/projections/rouss.rst b/docs/source/usage/operations/projections/rouss.rst
index e27fb1cf..e27fb1cf 100644
--- a/docs/source/projections/rouss.rst
+++ b/docs/source/usage/operations/projections/rouss.rst
diff --git a/docs/source/projections/rpoly.rst b/docs/source/usage/operations/projections/rpoly.rst
index 80e0d640..80e0d640 100644
--- a/docs/source/projections/rpoly.rst
+++ b/docs/source/usage/operations/projections/rpoly.rst
diff --git a/docs/source/projections/sinu.rst b/docs/source/usage/operations/projections/sinu.rst
index a7ebd232..a7ebd232 100644
--- a/docs/source/projections/sinu.rst
+++ b/docs/source/usage/operations/projections/sinu.rst
diff --git a/docs/source/projections/somerc.rst b/docs/source/usage/operations/projections/somerc.rst
index c572622b..c572622b 100644
--- a/docs/source/projections/somerc.rst
+++ b/docs/source/usage/operations/projections/somerc.rst
diff --git a/docs/source/projections/stere.rst b/docs/source/usage/operations/projections/stere.rst
index d4958ec9..d4958ec9 100644
--- a/docs/source/projections/stere.rst
+++ b/docs/source/usage/operations/projections/stere.rst
diff --git a/docs/source/projections/sterea.rst b/docs/source/usage/operations/projections/sterea.rst
index 4f2f8727..4f2f8727 100644
--- a/docs/source/projections/sterea.rst
+++ b/docs/source/usage/operations/projections/sterea.rst
diff --git a/docs/source/projections/tcc.rst b/docs/source/usage/operations/projections/tcc.rst
index 586dd3b8..586dd3b8 100644
--- a/docs/source/projections/tcc.rst
+++ b/docs/source/usage/operations/projections/tcc.rst
diff --git a/docs/source/projections/tcea.rst b/docs/source/usage/operations/projections/tcea.rst
index cf5549a3..cf5549a3 100644
--- a/docs/source/projections/tcea.rst
+++ b/docs/source/usage/operations/projections/tcea.rst
diff --git a/docs/source/projections/tissot.rst b/docs/source/usage/operations/projections/tissot.rst
index 7ec1a741..7ec1a741 100644
--- a/docs/source/projections/tissot.rst
+++ b/docs/source/usage/operations/projections/tissot.rst
diff --git a/docs/source/projections/tmerc.rst b/docs/source/usage/operations/projections/tmerc.rst
index 03aa2830..03aa2830 100644
--- a/docs/source/projections/tmerc.rst
+++ b/docs/source/usage/operations/projections/tmerc.rst
diff --git a/docs/source/projections/tpeqd.rst b/docs/source/usage/operations/projections/tpeqd.rst
index e6d7ef29..e6d7ef29 100644
--- a/docs/source/projections/tpeqd.rst
+++ b/docs/source/usage/operations/projections/tpeqd.rst
diff --git a/docs/source/projections/tpers.rst b/docs/source/usage/operations/projections/tpers.rst
index 345a5faa..345a5faa 100644
--- a/docs/source/projections/tpers.rst
+++ b/docs/source/usage/operations/projections/tpers.rst
diff --git a/docs/source/projections/ups.rst b/docs/source/usage/operations/projections/ups.rst
index 7a9ab50b..7a9ab50b 100644
--- a/docs/source/projections/ups.rst
+++ b/docs/source/usage/operations/projections/ups.rst
diff --git a/docs/source/projections/urm5.rst b/docs/source/usage/operations/projections/urm5.rst
index 91d06308..91d06308 100644
--- a/docs/source/projections/urm5.rst
+++ b/docs/source/usage/operations/projections/urm5.rst
diff --git a/docs/source/projections/urmfps.rst b/docs/source/usage/operations/projections/urmfps.rst
index 515ced84..515ced84 100644
--- a/docs/source/projections/urmfps.rst
+++ b/docs/source/usage/operations/projections/urmfps.rst
diff --git a/docs/source/projections/utm.rst b/docs/source/usage/operations/projections/utm.rst
index 7fb66cb8..7fb66cb8 100644
--- a/docs/source/projections/utm.rst
+++ b/docs/source/usage/operations/projections/utm.rst
diff --git a/docs/source/projections/vandg.rst b/docs/source/usage/operations/projections/vandg.rst
index cdc772bb..cdc772bb 100644
--- a/docs/source/projections/vandg.rst
+++ b/docs/source/usage/operations/projections/vandg.rst
diff --git a/docs/source/projections/vandg2.rst b/docs/source/usage/operations/projections/vandg2.rst
index 556929e2..556929e2 100644
--- a/docs/source/projections/vandg2.rst
+++ b/docs/source/usage/operations/projections/vandg2.rst
diff --git a/docs/source/projections/vandg3.rst b/docs/source/usage/operations/projections/vandg3.rst
index d767c4d5..d767c4d5 100644
--- a/docs/source/projections/vandg3.rst
+++ b/docs/source/usage/operations/projections/vandg3.rst
diff --git a/docs/source/projections/vandg4.rst b/docs/source/usage/operations/projections/vandg4.rst
index 097ba1d8..097ba1d8 100644
--- a/docs/source/projections/vandg4.rst
+++ b/docs/source/usage/operations/projections/vandg4.rst
diff --git a/docs/source/projections/vitk1.rst b/docs/source/usage/operations/projections/vitk1.rst
index b9081547..b9081547 100644
--- a/docs/source/projections/vitk1.rst
+++ b/docs/source/usage/operations/projections/vitk1.rst
diff --git a/docs/source/projections/wag1.rst b/docs/source/usage/operations/projections/wag1.rst
index dd1ed39e..dd1ed39e 100644
--- a/docs/source/projections/wag1.rst
+++ b/docs/source/usage/operations/projections/wag1.rst
diff --git a/docs/source/projections/wag2.rst b/docs/source/usage/operations/projections/wag2.rst
index 9c7b0edc..9c7b0edc 100644
--- a/docs/source/projections/wag2.rst
+++ b/docs/source/usage/operations/projections/wag2.rst
diff --git a/docs/source/projections/wag3.rst b/docs/source/usage/operations/projections/wag3.rst
index fb70a0a6..fb70a0a6 100644
--- a/docs/source/projections/wag3.rst
+++ b/docs/source/usage/operations/projections/wag3.rst
diff --git a/docs/source/projections/wag4.rst b/docs/source/usage/operations/projections/wag4.rst
index 7b8dac96..7b8dac96 100644
--- a/docs/source/projections/wag4.rst
+++ b/docs/source/usage/operations/projections/wag4.rst
diff --git a/docs/source/projections/wag5.rst b/docs/source/usage/operations/projections/wag5.rst
index f880290b..f880290b 100644
--- a/docs/source/projections/wag5.rst
+++ b/docs/source/usage/operations/projections/wag5.rst
diff --git a/docs/source/projections/wag6.rst b/docs/source/usage/operations/projections/wag6.rst
index f74749a5..f74749a5 100644
--- a/docs/source/projections/wag6.rst
+++ b/docs/source/usage/operations/projections/wag6.rst
diff --git a/docs/source/projections/wag7.rst b/docs/source/usage/operations/projections/wag7.rst
index be1401b8..be1401b8 100644
--- a/docs/source/projections/wag7.rst
+++ b/docs/source/usage/operations/projections/wag7.rst
diff --git a/docs/source/projections/weren.rst b/docs/source/usage/operations/projections/weren.rst
index de7c5abf..de7c5abf 100644
--- a/docs/source/projections/weren.rst
+++ b/docs/source/usage/operations/projections/weren.rst
diff --git a/docs/source/projections/wink1.rst b/docs/source/usage/operations/projections/wink1.rst
index 00346765..00346765 100644
--- a/docs/source/projections/wink1.rst
+++ b/docs/source/usage/operations/projections/wink1.rst
diff --git a/docs/source/projections/wink2.rst b/docs/source/usage/operations/projections/wink2.rst
index 7e9b48a7..7e9b48a7 100644
--- a/docs/source/projections/wink2.rst
+++ b/docs/source/usage/operations/projections/wink2.rst
diff --git a/docs/source/projections/wintri.rst b/docs/source/usage/operations/projections/wintri.rst
index bfd5032f..bfd5032f 100644
--- a/docs/source/projections/wintri.rst
+++ b/docs/source/usage/operations/projections/wintri.rst
diff --git a/docs/source/usage/operations/transformations/deformation.rst b/docs/source/usage/operations/transformations/deformation.rst
new file mode 100644
index 00000000..2489f18e
--- /dev/null
+++ b/docs/source/usage/operations/transformations/deformation.rst
@@ -0,0 +1,148 @@
+.. _deformation:
+
+================================================================================
+Kinematic datum shifting utilizing a deformation model
+================================================================================
+
+Perform datum shifts means of a deformation/velocity model.
+
++-----------------+--------------------------------------------------------------------+
+| **Input type**  | Cartesian coordinates.                                             |
++-----------------+--------------------------------------------------------------------+
+| **Output type** | Cartesian coordinates.                                             |
++-----------------+--------------------------------------------------------------------+
+| **Options**                                                                          |
++-----------------+--------------------------------------------------------------------+
+| `xy_grids`      | Comma-separated list of grids to load.                             |
++-----------------+--------------------------------------------------------------------+
+| `z_grids`       | Comma-separated list of grids to load.                             |
++-----------------+--------------------------------------------------------------------+
+| `t_epoch`       | Central epoch of transformation. [decimalyear]. Only used in       |
+|                 | spatiotemporal transformations.                                    |
++-----------------+--------------------------------------------------------------------+
+| `t_obs`         | Observation time of coordinate(s). Mostly useful in 2D and 3D      |
+|                 | transformations. [decimalyear]. *Optional*.                        |
++-----------------+--------------------------------------------------------------------+
+
+The deformation operation is used to adjust coordinates for intraplate deformations.
+Usually the transformation parameters for regional plate-fixed reference frames such as
+the ETRS89 does not take intraplate deformation into account. It is assumed that
+tectonic plate of the region is rigid. Often times this is true, but near the plate
+boundary and in areas with post-glacial uplift the assumption breaks. Tntraplate
+deformations can be modelled and then applied to the coordinates so that
+they represent the physical world better. In PROJ this is done with the deformation
+operation.
+
+The horizontal grid is stored in CTable2 format and the vertical grid is stored in the
+GTX format. Both grids are expected to contain grid-values in units of mm/year.
+Details about the formats can be found in the GDAL documentation. GDAL both reads and
+writes both file formats. Using GDAL for construction of new grids is recommended.
+
+Example
+-------------------------------------------------------------------------------
+
+In [Häkli2016]_ coordinate transformation including a deformation model is described.
+The paper describes how coordinates from the global ITRFxx frames are transformed to the
+local Nordic realisations of ERTS89. Scandinavia is an area with significant post-glacial
+rebound. The deformations from the post-glacial uplift is not accounted for in the
+offcial ETRS89 transformations so in order to get accurate transformations in the Nordic
+countries it is necesarry to apply the deformation model. The transformation from ITRF2008
+to the Danish realisation of ETRS89 is in PROJ described as::
+
+    proj =  pipeline ellps = GRS80
+            # ITRF2008@t_obs -> ITRF2000@t_obs
+    step    init = ITRF2008:ITRF2000
+            # ITRF2000@t_obs -> ETRF2000@t_obs
+    step    proj=helmert t_epoch = 2000.0 transpose
+            x =  0.054  rx =  0.000891 drx =  8.1e-05
+            y =  0.051  ry =  0.00539  dry =  0.00049
+            z = -0.048  rz = -0.008712 drz = -0.000792
+            # ETRF2000@t_obs -> NKG_ETRF00@2000.0
+    step    proj = deformation t_epoch = 2000.0
+            xy_grids = ./nkgrf03vel_realigned_xy.ct2
+            z_grids  = ./nkgrf03vel_realigned_z.gtx
+            # NKG_ETRF@2000.0 -> ETRF92@2000.0
+    step    proj=helmert transpose s = -0.009420e
+            x = 0.03863 rx = 0.00617753
+            y = 0.147   ry = 5.064e-05
+            z = 0.02776 rz = 4.729e-05
+            # ETRF92@2000.0 -> ETRF92@1994.704
+    step    proj = deformation t_epoch = 1994.704 t_obs = 2000.0
+            xy_grids = ./nkgrf03vel_realigned_xy.ct2
+            z_grids  = ./nkgrf03vel_realigned_z.gtx
+
+From this we can see that the transformation from ITRF2008 to the Danish realisation of
+ETRS89 is a combination of Helmert transformations and adjustments with a deformation
+model. The first use of the deformation operation is::
+
+    proj = deformation t_epoch = 2000.0
+    xy_grids = ./nkgrf03vel_realigned_xy.ct2
+    z_grids  = ./nkgrf03vel_realigned_z.gtx
+
+Here we set the central epoch of the transformation, 2000.0. The observation epoch
+is expected as part of the input coordinate tuple. The deformation model is
+described by two grids, specified with *xy_grids* and *z_grids*. The first is
+the horizontal part of the model and the second is the vertical component.
+
+Mathematical description
+-------------------------------------------------------------------------------
+
+Mathematically speaking, application of a deformation model is simple. The deformation model is
+represented as a grid of velocities in three dimensions. Coordinate corrections are
+applied in cartesian space. For a given coordinate, :math:`(X, Y, Z)`, velocities
+:math:`(V_X, V_Y, V_Z)` can be interpolated from the gridded model. The time span
+between :math:`t_c` and :math:`t_{obs}` determine the magnitude of the coordinate
+correcton as seen in eq. :eq:`apply_velocity` below.
+
+.. math::
+    :label: apply_velocity
+
+    \begin{align}
+        \begin{pmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{pmatrix}_B =
+        \begin{pmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{pmatrix}_A +
+        (t_c - t_{obs})
+        \begin{pmatrix}
+            V_X \\
+            V_Y \\
+            V_Z \\
+        \end{pmatrix}
+    \end{align}
+
+Corrections are done in cartesian space.
+
+Coordinates of the gridded model are in ENU (east, north, up) space because it would
+otherwise require an enormous 3 dimensional grid to handle the corrections in cartesian
+space. Keeping the correction in lat/long space reduces the complexity of the grid
+significantly. Consequentyly though, the input coordinates needs to be converted to
+lat/long space when searching for corrections in the grid. This is done with *cart*
+operation. The converted grid corrections can then be applied to the input coordinates
+in cartesian space. The conversion from ENU space to cartesian space is done in the
+following way:
+
+.. math::
+    :label: enu2xyz
+
+    \begin{align}
+        \begin{pmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{pmatrix} =
+        \begin{pmatrix}
+            -\sin\phi \cos\lambda N - \sin\lambda E + \cos\phi \cos\lambda U \\
+            -\sin\phi \sin\lambda N + \sin\lambda E + \cos\phi \sin\lambda U \\
+                         \cos\phi N +                 \sin\phi U \\
+        \end{pmatrix}
+    \end{align}
+
+where :math:`\phi` and :math:`\lambda` are the latitude and longitude of the coordinate
+that is searched for in the grid. :math:`(E, N, U)` are the grid values in ENU-space and
+:math:`(X, Y, Z)` are the corrections converted to cartesian space.
diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst
new file mode 100644
index 00000000..03e5db15
--- /dev/null
+++ b/docs/source/usage/operations/transformations/helmert.rst
@@ -0,0 +1,388 @@
+.. _helmert:
+
+================================================================================
+Helmert transform
+================================================================================
+
+The Helmert transformation changes coordinates from one reference frame to
+anoether by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and
+14-parameter kinematic counterparts.
+
++-----------------+-------------------------------------------------------------------+
+| **Input type**  | Cartesian coordinates (spatial), decimalyears (temporal).         |
++-----------------+-------------------------------------------------------------------+
+| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal).         |
++-----------------+-------------------------------------------------------------------+
+| **Options**                                                                         |
++----------------+--------------------------------------------------------------------+
+| `x`            | Translation of the x-axis [m]. *Optional*.                         |
++----------------+--------------------------------------------------------------------+
+| `y`            | Translation of the y-axis [m]. *Optional*.                         |
++----------------+--------------------------------------------------------------------+
+| `z`            | Translation of the z-axis. [m]. *Optional*.                        |
++----------------+--------------------------------------------------------------------+
+| `s`            | Scale factor [ppm]. *Optional*.                                    |
++----------------+--------------------------------------------------------------------+
+| `rx`           | X-axis rotation in the 3D Helmert [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `ry`           | Y-axis rotatoin in the 3D Helmert [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `rz`           | Z-axis rotation in the 3D Helmert [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `theta`        | Rotation angle in the 2D Helmert. [arc seconds]. *Optional*.       |
++----------------+--------------------------------------------------------------------+
+| `dx`           | Translation rate of the x-axis. [m/year]. *Optional*.              |
++----------------+--------------------------------------------------------------------+
+| `dy`           | Translation rate of the y-axis. [m/year]. *Optional*.              |
++----------------+--------------------------------------------------------------------+
+| `dz`           | Translation rate of the z-axis. [m/year]. *Optional*.              |
++----------------+--------------------------------------------------------------------+
+| `ds`           | Scale rate factor [ppm/year]. *Optional*.                          |
++----------------+--------------------------------------------------------------------+
+| `drx`          | Rotation rate of the x-axis [arc seconds/year]. *Optional*.        |
++----------------+--------------------------------------------------------------------+
+| `dry`          | Rotation rate of the y-axis [arc seconds/year]. *Optional*.        |
++----------------+--------------------------------------------------------------------+
+| `drz`          | Rotation rate of the y-axis [arc seconds/year]. *Optional*.        |
++----------------+--------------------------------------------------------------------+
+| `t_epoch`      | Central epoch of transformation. [decimalyear]. Only used in       |
+|                | spatiotemporal transformations. *Optional*.                        |
++----------------+--------------------------------------------------------------------+
+| `t_obs`        | Observation time of coordinate(s). Mostly useful in 2D and 3D      |
+|                | transformations. [decimalyear]. *Optional*.                        |
++----------------+--------------------------------------------------------------------+
+| `exact`        | Use exact transformation equations. *Optional*.                    |
++----------------+--------------------------------------------------------------------+
+| `transpose`    | Transpose rotation matrix. *Optional*.                             |
++----------------+--------------------------------------------------------------------+
+
+The Helmert transform, in all it's various incarnations, is used to perform reference
+frame shifts. The transformation operates in cartesian space. It can be used to transform
+planar coordinates from one datum to another, transform 3D cartesian
+coordinates from one static reference frame to another or it can be used to do fully
+kinematic transformations from global reference frames to local static frames.
+
+All of the parameters described in the table above are marked as optional. This is true
+as long as at least one parameter is defined in the setup of the transformation.
+The behaviour of the transformation depends on which parameters are used in the setup.
+For instance, if a rate of change paramater is specified a kinematic version of the
+transformation is used.
+
+The kinematic transformations require an observation time of the coordinate, as well
+as a central epoch for the transformation. The latter is usually documented
+alongside the rest of the transformation parameters for a given transformation.
+The central eopch is controlled with the parameter `t_epoch`. The observation
+time can either by stated as part of the coordinate when using PROJ's
+4D-functionality or it can be controlled in the transformation setup by the
+parameter `t_obs`. When `t_obs` is specified, all transformed coordinates are
+treated as if they have the same observation time.
+
+Examples
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert:
+
+::
+
+    proj=helmert ellps=GRS80 x=-9597.3572 y=.6112
+                 s=0.304794780637 theta=-1.244048
+
+Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters:
+
+::
+
+    proj=helmert ellps=GRS80 x=0.67678    y=0.65495   z=-0.52827
+                rx=-0.022742 ry=0.012667 rz=0.022704  s=-0.01070
+
+Transformation from `ITRF2000@2017.0`  to `ITRF93@2017.0` using 15 parameters:
+
+::
+
+    proj=helmert ellps=GRS80
+         x=0.0127     y=0.0065     z=-0.0209  s=0.00195
+         dx=-0.0029   dy=-0.0002   dz=-0.0006 ds=0.00001
+         rx=-0.00039  ry=0.00080   rz=-0.00114
+         drx=-0.00011 dry=-0.00019 drz=0.00007
+         epoch=1988.0 tobs=2017.0    transpose
+
+Mathematical description
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+In the notation used below, :math:`\hat{P}` is the rate of change of a given transformation
+parameter :math:`P`. :math:`\dot{P}` is the kinematically adjusted version of :math:`P`,
+described by
+
+.. math::
+    :label: propagation
+
+    \dot{P}= P + \hat{P}\left(t - t_{central}\right)
+
+where :math:`t` is the observation time of the coordinate and :math:`t_{central}` is
+the central epoch of the transformation. Equation :eq:`propagation` can be used to
+propagate all transformation parameters in time.
+
+Superscripts of vectors denote the reference frame the coordinates in the vector belong to.
+
+
+2D Helmert
+-------------------------------------------------------------------------------
+
+The simplest version of the Helmert transform is the 2D case. In the 2-dimensional
+case only the horizontal coordinates are changed. The coordinates can be
+translated, rotated and scale. Translation is controlled with the `x` and `y`
+parameters. The rotation is determined by `theta` and the scale is controlled with
+the `s` paramaters.
+
+.. note::
+
+    The scaling parameter `s` is unitless for the 2D Helmert, as opposed to the
+    3D version where the scaling parameter is given in units of ppm.
+
+Mathematically the 2D Helmert is described as:
+
+.. math::
+    :label: 4param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            T_x \\
+            T_y \\
+        \end{bmatrix} +
+        s
+        \begin{bmatrix}
+            \hphantom{-}\cos \theta & \sin \theta \\
+            -\sin \theta & \cos \theta \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^A
+    \end{align}
+
+
+:eq:`4param` can be extended to a time-varying kinematic version by
+adjusting the parameters with :eq:`propagation` to :eq:`4param`, which yields
+the kinematic 2D Helmert transform:
+
+.. math::
+    :label: 8param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            \dot{T_x} \\
+            \dot{T_y} \\
+        \end{bmatrix} +
+        s(t)
+        \begin{bmatrix}
+             \hphantom{-}\cos \dot{\theta} & \sin \dot{\theta}  \\
+                        -\sin\ \dot{\theta} & \cos \dot{\theta} \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+        \end{bmatrix}^A
+    \end{align}
+
+All parameters in :eq:`8param` are determined by the use of :eq:`propagation`,
+which applies the rate of change to each individual parameter for a given
+timespan between :math:`t` and :math:`t_{central}`.
+
+
+3D Helmert
+-------------------------------------------------------------------------------
+
+The general form of the 3D Helmert is
+
+.. math::
+    :label: general-helmert
+
+
+    \begin{align}
+        V^B = T + \left(1 + s \times 10^{-6}\right) \mathbf{R} V^A
+    \end{align}
+
+Where :math:`T` is a vector consisting of the three translation parameters, :math:`s`
+is the scaling factor and :math:`\mathbf{R}` is a rotation matrix. :math:`V^A` and
+:math:`V^B` are coordinate vectors, with :math:`V^A` being the input coordinate and
+:math:`V^B` is the output coordinate.
+
+The rotation matrix is composed of three rotation matrices, one for each axis:
+
+.. math::
+
+    \begin{align}
+        \mathbf{R}_X &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos\phi & -\sin\phi\\ 0 & \sin\phi & \cos\phi \end{bmatrix}
+    \end{align}
+
+.. math::
+
+    \begin{align}
+        \mathbf{R}_Y &= \begin{bmatrix} \cos\theta & 0 & \sin\theta\\ 0 & 1 & 0\\ -\sin\theta & 0 & \cos\theta \end{bmatrix}
+    \end{align}
+
+.. math::
+
+    \begin{align}
+        \mathbf{R}_Z &= \begin{bmatrix} \cos\psi & -\sin\psi & 0\\ \sin\psi & \cos\psi & 0\\ 0 & 0 & 1 \end{bmatrix}
+    \end{align}
+
+The three rotation matrices can be combined in one:
+
+.. math::
+
+    \begin{align}
+        \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y}
+    \end{align}
+
+For :math:`\mathbf{R}`, this yields:
+
+.. math::
+    :label: rot_exact
+
+    \begin{bmatrix}
+      \cos\theta \cos\psi &  -\cos\phi \sin\psi + \sin\phi \sin\theta \cos\psi &   \sin\phi \sin\psi + \cos\phi \sin\theta \cos\psi \\
+      \cos\theta\sin\psi &  \cos\phi \cos\psi + \sin\phi \sin\theta \sin\psi &  - \sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\
+      -\sin\theta             &  \sin\phi \cos\theta                                          &   \cos\phi \cos\theta \\
+     \end{bmatrix}
+
+
+Using the small angle approxition the rotation matrix can be simplified to
+
+.. math::
+    :label: rot_approx
+
+    \begin{align} \mathbf{R} =
+        \begin{bmatrix}
+             1  & -R_z  &  R_y \\
+             Rz &  1    & -R_x \\
+            -Ry &  R_x  &  1   \\
+        \end{bmatrix}
+    \end{align}
+
+Which allow us to express the most common version of the Helmert transform,
+using the approximated rotation matrix:
+
+
+.. math::
+    :label: 7param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            T_x \\
+            T_y \\
+            T_z \\
+        \end{bmatrix} +
+        \left(1 + s \times 10^{-6}\right)
+        \begin{bmatrix}
+             1  & -R_z  &  R_y \\
+             Rz &  1    & -R_x \\
+            -Ry &  R_x  &  1   \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}
+
+If the rotation matrix is transposed the transformation is effectively reversed.
+This is cause for some confusion since there is no correct way of defining the
+rotation matrix. Two conventions exists and they seem to be equally popular.
+In PROJ the rotation matrix can be transposed by adding the `transpose` flag in
+the transformation setup.
+
+Applying :eq:`propagation` we get the kinematic version of the approximated
+3D Helmert:
+
+.. math::
+    :label: 14param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            \dot{T_x} \\
+            \dot{T_y} \\
+            \dot{T_z} \\
+        \end{bmatrix} +
+        \left(1 + \dot{s} \times 10^{-6}\right)
+        \begin{bmatrix}
+             1         & -\dot{R_z}  &  \dot{R_y} \\
+             \dot{R_z} &  1          & -\dot{R_x} \\
+            -\dot{R_y} &  \dot{R_x}  &  1      \\
+        \end{bmatrix}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}
+
+
+
+
+The Helmert transformation can be applied without using the rotation parameters,
+in which case it becomes a simlpe translation of the origin of the coordinate
+system. When using the Helmert in this version equation :eq:`general-helmert`
+simplies to:
+
+.. math::
+    :label: 3param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            T_x \\
+            T_y \\
+            T_z \\
+        \end{bmatrix} +
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}
+
+That after application of :eq:`propagation` has the following kinematic
+countpart:
+
+.. math::
+    :label: 6param
+
+    \begin{align}
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^B =
+        \begin{bmatrix}
+            \dot{T_x} \\
+            \dot{T_y} \\
+            \dot{T_z} \\
+        \end{bmatrix} +
+        \begin{bmatrix}
+            X \\
+            Y \\
+            Z \\
+        \end{bmatrix}^A
+    \end{align}
diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst
new file mode 100644
index 00000000..a9690260
--- /dev/null
+++ b/docs/source/usage/operations/transformations/hgridshift.rst
@@ -0,0 +1,39 @@
+.. _hgridshift:
+
+================================================================================
+Horizontal grid shift
+================================================================================
+
+Change of horizontal datum by grid shift.
+
++-----------------+--------------------------------------------------------------------+
+| **Input type**  | Geodetic coordinates.                                              |
++-----------------+--------------------------------------------------------------------+
+| **Output type** | Geodetic coordinates.                                              |
++-----------------+--------------------------------------------------------------------+
+| **Options**                                                                          |
++-----------------+--------------------------------------------------------------------+
+| `+grids`        | Comma-separated list of grids to load.                             |
++-----------------+--------------------------------------------------------------------+
+
+The horizontal grid shift is done by offsetting the planar input coordinates by
+a specific amount determined by the loaded grids. The simplest use case of the
+horizontal grid shift is applying a single grid::
+
+    +hgridshift +grids=nzgr2kgrid0005.gsb
+
+
+More than one grid can be loaded at the same time, for instance in case the
+dataset needs to be transformed spans several countries. In this example grids
+of the continental US, Alaska and Canada is loaded at the same time::
+
+    +hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat
+
+The ``@`` in the above example states that the grid is optional, in case the grid
+is not found in the PROJ.4 search path. The list of grids is prioritized so that
+grids in the start of the list takes presedence over the grids in the back of the
+list.
+
+PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details
+about all three formats can be found in the GDAL documentation. GDAL reads and
+writes all three formats. Using GDAL for construction of new grids is recommended.
diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst
new file mode 100644
index 00000000..5112ffa2
--- /dev/null
+++ b/docs/source/usage/operations/transformations/index.rst
@@ -0,0 +1,17 @@
+.. _transformation_list:
+
+================================================================================
+Transformations
+================================================================================
+
+Transformations coordinate operation in which the two coordinate reference
+systems are based on different datums.
+
+.. toctree::
+   :maxdepth: 1
+
+   deformation
+   helmert
+   molodensky
+   hgridshift
+   vgridshift
diff --git a/docs/source/usage/operations/transformations/molodensky.rst b/docs/source/usage/operations/transformations/molodensky.rst
new file mode 100644
index 00000000..d4ff3e79
--- /dev/null
+++ b/docs/source/usage/operations/transformations/molodensky.rst
@@ -0,0 +1,74 @@
+.. _molodensky:
+
+================================================================================
+Molodensky transform
+================================================================================
+
+The Molodensky transformation resembles a :ref:`Helmert` with zero
+rotations and a scale of unity, but converts directly from geodetic coordinates to
+geodetic coordinates, without the intermediate shifts to and from cartesian
+geocentric coordinates, associated with the Helmert transformation.
+The Molodensky transformation is simple to implement and to parameterize, requiring
+only the 3 shifts between the input and output frame, and the corresponding
+differences between the semimajor axes and flattening parameters of the reference
+ellipsoids. Due to its algorithmic simplicity, it was popular prior to the
+ubiquity of digital computers. Today, it is mostly interesting for historical
+reasons, but nevertheless indispensable due to the large amount of data that has
+already been transformed that way [EversKnudsen2017]_.
+
++---------------------+----------------------------------------------------------+
+| **Input type**      | Geodetic coordinates.                                    |
++---------------------+----------------------------------------------------------+
+| **Output type**     | Geodetic coordinates.                                    |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+da`               | Difference in semimajor axis of the defining ellipsoids. |
++---------------------+----------------------------------------------------------+
+| `+df`               | Difference in flattening of the defining ellipsoids.     |
++---------------------+----------------------------------------------------------+
+| `+dx`               | Offset of the X-axes of the defining ellipsoids.         |
++---------------------+----------------------------------------------------------+
+| `+dy`               | Offset of the Y-axes of the defining ellipsoids.         |
++---------------------+----------------------------------------------------------+
+| `+dz`               | Offset of the Z-axes of the defining ellipsoids.         |
++---------------------+----------------------------------------------------------+
+| `+ellps`            | Ellipsoid definition of source coordinates.              |
+|                     | Any specification can be used (e.g. `+a`, `+rf`, etc).   |
+|                     | If not specified, default ellipsoid is used.             |
++---------------------+----------------------------------------------------------+
+| `+abridged`         | Use the abridged version of the Molodensky transform.    |
+|                     | Optional.                                                |
++---------------------+----------------------------------------------------------+
+
+The Molodensky transform can be used to perform a datum shift from coordinate
+:math:`(\phi_1, \lambda_1, h_1)` to :math:`(\phi_2, \lambda_2, h_2)` where the two
+coordinates are referenced to different ellipsoids. This is based on three
+assumptions:
+
+    1. The cartesian axes, :math:`X, Y, Z`,  of the two ellipsoids are parallel.
+    2. The offset, :math:`\delta X, \delta Y, \delta Z`,  between the two ellipsoid
+       are known.
+    3. The characteristics of the two ellipsoids, expressed as the difference in
+       semimajor axis (:math:`\delta a`) and flattening (:math:`\delta f`),  are known.
+
+The Molodensky transform is mostly used for transforming between old systems
+dating back to the time before computers. The advantage of the Molodensky transform
+is that it is fairly simple to compute by hand. The ease of computation come at the
+cost of limited accuracy.
+
+A derivation of the mathematical formulas for the Molodensky transform can be found
+in [Deakin2004]_.
+
+
+Examples
+###############################################################################
+
+The abridged Molodensky::
+
+    proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8  dx=-134 dy=-48 dz=149 abridged
+
+The same transformation using the standard Molodensky::
+
+    proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8  dx=-134 dy=-48 dz=149
+
diff --git a/docs/source/usage/operations/transformations/vgridshift.rst b/docs/source/usage/operations/transformations/vgridshift.rst
new file mode 100644
index 00000000..31b3e56e
--- /dev/null
+++ b/docs/source/usage/operations/transformations/vgridshift.rst
@@ -0,0 +1,41 @@
+.. _vgridshift:
+
+================================================================================
+Vertical grid shift
+================================================================================
+
+Change Vertical datum change by grid shift
+
++-----------------+--------------------------------------------------------------------+
+| **Input type**  | Geodetic coordinates (horizontal), meters (vertical).              |
++-----------------+--------------------------------------------------------------------+
+| **Output type** | Geodetic coordinates (horizontal), meters (vertical).              |
++-----------------+--------------------------------------------------------------------+
+| **Options**                                                                          |
++-----------------+--------------------------------------------------------------------+
+| `+grids`        | Comma-separated list of grids to load.                             |
++-----------------+--------------------------------------------------------------------+
+
+The vertical grid shift is done by offsetting the vertical input coordinates by
+a specific amount determined by the loaded grids. The simplest use case of the
+horizontal grid shift is applying a single grid. Here we change the vertical
+reference from the ellipsoid to the global geoid model, EGM96::
+
+    +vgridshift +grids=egm96_16.gtx
+
+
+More than one grid can be loaded at the same time, for instance in the case where
+a better geoid model than the global is available for a certain area. Here the
+gridshift is set up so that the local DVR90 geoid model takes presedence over
+the global model::
+
+    +vgridshift +grids=@dvr90.gtx,egm96_16.gtx
+
+The ``@`` in the above example states that the grid is optional, in case the grid
+is not found in the PROJ.4 search path. The list of grids is prioritized so that
+grids in the start of the list takes presedence over the grids in the back of the
+list.
+
+PROJ supports the GTX file format for vertical grid corrections. Details
+about all the format can be found in the GDAL documentation. GDAL both reads and
+writes the format. Using GDAL for construction of new grids is recommended.
diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst
new file mode 100644
index 00000000..8f0b3586
--- /dev/null
+++ b/docs/source/usage/projections.rst
@@ -0,0 +1,164 @@
+.. _projections_intro:
+
+================================================================================
+Cartographic projection
+================================================================================
+
+The foundation of PROJ.4 is the large number of
+:doc:`projections<operations/projections/index>` available in the library. This section
+is devoted to the generic parameters that can be used on any projection in the
+PROJ.4 library.
+
+Below is a list of PROJ.4 parameters which can be applied to most coordinate
+system definitions. This table does not attempt to describe the parameters
+particular to particular projection types. These can be found on the pages
+documenting the individual :doc:`projections<operations/projections/index>`.
+
+    ==========   ================================================================
+    Parameter    Description
+    ==========   ================================================================
+    +a           Semimajor radius of the ellipsoid axis
+    +axis        Axis orientation
+    +b           Semiminor radius of the ellipsoid axis
+    +ellps       Ellipsoid name (see ``proj -le``)
+    +k           Scaling factor (deprecated)
+    +k_0         Scaling factor
+    +lat_0       Latitude of origin
+    +lon_0       Central meridian
+    +lon_wrap    Center longitude to use for wrapping (see below)
+    +no_defs     Don't use the /usr/share/proj/proj_def.dat defaults file
+    +over        Allow longitude output outside -180 to 180 range, disables
+                 wrapping (see below)
+    +pm          Alternate prime meridian (typically a city name, see below)
+    +proj        Projection name (see ``proj -l``)
+    +units       meters, US survey feet, etc.
+    +vunits      vertical units.
+    +x_0         False easting
+    +y_0         False northing
+    ==========   ================================================================
+
+In the sections below most of the parameters are explained in details.
+
+Units
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Horizontal units can be specified using the ``+units`` keyword with a symbolic
+name for a unit (ie. ``us-ft``).  Alternatively the translation to meters can be
+specified with the ``+to_meter`` keyword (ie. 0.304800609601219 for US feet).  The
+``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list symbolic unit names.
+The default unit for projected coordinates is the meter.
+A few special projections deviate from this behaviour, most notably the
+latlong pseudo-projection that returns degrees.
+
+Vertical (Z) units can be specified using the ``+vunits`` keyword with a
+symbolic name for a unit (ie. ``us-ft``).  Alternatively the translation to
+meters can be specified with the ``+vto_meter`` keyword (ie. 0.304800609601219
+for US feet).  The ``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list
+symbolic unit names.  If no vertical units are specified, the vertical units will
+default to be the same as the horizontal coordinates.
+
+.. note::
+    ``proj`` do not handle vertical units at all and hence the ``+vto_meter``
+    argument will be ignored.
+
+Scaling of output units can be done by applying the ``+k_0`` argument. The
+returned coordinates are scaled by the value assigned with the ``+k_0``
+parameter.
+
+False Easting/Northing
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Virtually all coordinate systems allow for the presence of a false easting
+(``+x_0``) and northing (``+y_0``).  Note that these values are always expressed in
+meters even if the coordinate system is some other units.  Some coordinate
+systems (such as UTM) have implicit false easting and northing values.
+
+Longitude Wrapping
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+By default PROJ.4 wraps output longitudes in the range -180 to 180.  The ``+over``
+switch can be used to disable the default wrapping which is done at a low level
+in ``pj_inv()``.  This is particularly useful with projections like the
+:doc:`equidistant cylindrical<operations/projections/eqc>`
+where it would be desirable for X values past -20000000 (roughly) to continue
+past -180 instead of wrapping to +180.
+
+The ``+lon_wrap`` option can be used to provide an alternative means of doing
+longitude wrapping within ``pj_transform()``.  The argument to this option is a
+center longitude.  So ``+lon_wrap=180`` means wrap longitudes in the range 0 to
+360.  Note that ``+over`` does **not** disable ``+lon_wrap``.
+
+Prime Meridian
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+A prime meridian may be declared indicating the offset between the prime
+meridian of the declared coordinate system and that of greenwich.  A prime
+meridian is clared using the "pm" parameter, and may be assigned a symbolic
+name, or the longitude of the alternative prime meridian relative to greenwich.
+
+Currently prime meridian declarations are only utilized by the
+``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls.
+Consequently the user utility ``cs2cs`` does honour prime meridians but the
+``proj`` user utility ignores them.
+
+The following predeclared prime meridian names are supported.  These can be
+listed using with ``cs2cs -lm``.
+
+ ===========     ================
+ Meridian        Longitude
+ ===========     ================
+   greenwich     0dE
+      lisbon     9d07'54.862"W
+       paris     2d20'14.025"E
+      bogota     74d04'51.3"E
+      madrid     3d41'16.48"W
+        rome     12d27'8.4"E
+        bern     7d26'22.5"E
+     jakarta     106d48'27.79"E
+       ferro     17d40'W
+    brussels     4d22'4.71"E
+   stockholm     18d3'29.8"E
+      athens     23d42'58.815"E
+        oslo     10d43'22.5"E
+ ===========     ================
+
+Example of use.  The location ``long=0``, ``lat=0`` in the greenwich based lat/long
+coordinates is translated to lat/long coordinates with Madrid as the prime
+meridian.
+
+::
+
+    cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid
+    0 0                           <i>(input)</i>
+    3d41'16.48"E    0dN 0.000     <i>(output)</i>
+
+
+Axis orientation
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Starting in PROJ 4.8.0, the +axis argument can be used to control the axis
+orientation of the coordinate system.  The default orientation is "easting,
+northing, up" but directions can be flipped, or axes flipped using combinations
+of the axes in the +axis switch.  The values are:
+
+* "e" - Easting
+* "w" - Westing
+* "n" - Northing
+* "s" - Southing
+* "u" - Up
+* "d" - Down
+
+They can be combined in +axis in forms like:
+
+* ``+axis=enu`` - the default easting, northing, elevation.
+* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic
+  coordinates, or south orientated transverse mercator.
+* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems
+  have "west positive" coordinate systems
+
+.. note::
+
+    The ``+axis`` argument does not work with the ``proj`` command line
+    utility.
+
+
diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst
new file mode 100644
index 00000000..96bfbba1
--- /dev/null
+++ b/docs/source/usage/quickstart.rst
@@ -0,0 +1,68 @@
+.. _quickstart:
+
+================================================================================
+Quick start
+================================================================================
+
+Coordinate transformations are defined by, what in PROJ.4 terminology is
+known as, "proj-strings". A proj-string describes any transformation regardless of
+how simple or complicated it might be. The simplest case is projection of geodetic
+coordinates. This section focuses on the simpler cases and introduces the basic
+anatomy of the proj-string. The complex cases are discussed in
+:doc:`transformation`.
+
+A proj-strings holds the parameters of a given coordinate transformation, e.g.
+
+::
+
+    +proj=merc +lat_ts=56.5 +ellps=GRS80
+
+I.e. a proj-string consists of a projection specifier, ``+proj``, a number of
+parameters that applies to the projection and, if needed, a description of a
+datum shift. In the example above geodetic coordinates are transformed to
+projected space with the :doc:`Mercator projection<operations/projections/merc>` with
+the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every
+projection in PROJ.4 is identified by a shorthand such as ``merc`` in the above
+example.
+
+By using the  above projection definition as parameters for the command line
+utility ``proj`` we can convert the geodetic coordinates to projected space:
+
+::
+
+    $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+
+If called as above ``proj`` will be in interactive mode, letting you type the
+input data manually and getting a responce presented on screen. ``proj``
+works as any UNIX filter though, which means that you can also pipe data to
+the utility, for instance by using the ``echo`` command:
+
+::
+
+    $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+    3399483.80      752085.60
+
+
+PROJ.4 also comes bundled with the ``cs2cs`` utility which is used to transform
+from onecoordinate reference system to another. Say we want to convert
+the above Mercator coordinates to UTM, we can do that with ``cs2cs``:
+
+::
+
+    $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32
+    6103992.36      1924052.47 0.00
+
+Notice the ``+to`` parameter that seperates the source and destination
+projection definitions.
+
+If you happen to know the EPSG identifiers for the two cordinates reference
+systems you are transforming between you can use those with ``cs2cs``:
+
+::
+
+   $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832
+   231950.54      1920310.71 0.00
+
+In the above example we transform geodetic coordinates in the WGS84 reference
+frame to UTM zone 32N coordinates in the ETRS89 reference frame.
+UTM coordinates 
diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst
new file mode 100644
index 00000000..9a202879
--- /dev/null
+++ b/docs/source/usage/resource_files.rst
@@ -0,0 +1,121 @@
+.. _resource_files:
+
+================================================================================
+Resource files
+================================================================================
+
+A number of files containing preconfigured transformations and default parameters
+for certain projections are bundled with the PROJ.4 distribution. Init files
+contains preconfigured proj-strings for various coordinate reference systems
+and the defaults file contains default values for parameters of select
+projections.
+
+Init files
+-------------------------------------------------------------------------------
+
+Init files are used for preconfiguring proj-strings for often used
+transformations, such as those found in the EPSG database. Most init files contain
+transformations from a given coordinate reference system to WGS84. This makes
+it easy to transformations between any two coordinate reference systems with
+``cs2cs``. Init files can however contain any proj-string and don't necesarily
+have to follow the *cs2cs* paradigm where WGS84 is used as a pivot datum. The
+ITRF init file is a good example of that.
+
+A number of init files come pre-bundled with PROJ.4 but it is also possible to
+add your own custom init files. PROJ.4 looks for the init files in the directoty
+listed in the ``PROJ_LIB`` environment variable.
+
+The format of init files made up of a identifier in angled brackets and a
+proj-string:
+
+::
+
+    <3819> +proj=longlat +ellps=bessel
+           +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs <>
+
+The above example is the first entry from the ``epsg`` init file. So, this is the
+coordinate reference system with ID 3819 in the EPSG database. Comments can be
+inserted by prefixing them with a "#". With version 4.10.0 a new special metadata
+entry is now accepted in init files. It can be parsed with a function from the public
+API. The metadata entry in the epsg init file looks like this at the time of writing:
+
+::
+
+<metadata> +version=9.0.0 +origin=EPSG +lastupdate=2017-01-10
+
+Pre-configured proj-strings from init files are used in the following way:
+
+::
+
+    $ cs2cs -v +proj=latlong +to +init=epsg:3819
+    # ---- From Coordinate System ----
+    #Lat/long (Geodetic alias)
+    #
+    # +proj=latlong +ellps=WGS84
+    # ---- To Coordinate System ----
+    #Lat/long (Geodetic alias)
+    #
+    # +init=epsg:3819 +proj=longlat +ellps=bessel
+    # +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs
+
+It is possible to override parameters when using ``+init``. Just add the parameter
+to the proj-string alongside the ``+init`` parameter. For instance by overriding
+the ellipsoid as in the following example
+
+::
+
+    +init=epsg:25832 +ellps=intl
+
+where the Hayford ellipsoid is used instead of the predefined GRS80 ellipsoid.
+It is also possible to add additional parameters not specified in the init file,
+for instance by adding an obervation epoch when transforming from ITRF2000 to
+ITRF2005:
+
+::
+
+    +init=ITRF2000:ITRF2005 +tobs=2010.5
+
+which then expands to
+
+::
+
+    +proj=helmert +x=-0.0001 +y=0.0008 +z=0.0058 +s=-0.0004
+    +dx=0.0002 +dy=-0.0001 +dz=0.0018 +ds=-0.000008
+    +epoch=2000.0 +transpose
+    +tobs=2010.5
+
+Below is a list of the init files that are packaged with PROJ.4.
+
+    ========    ================================================================
+    Name        Description
+    ========    ================================================================
+    esri        Auto-generated mapping from Esri projection index. Not
+                maintained any more
+    epsg        EPSG database
+    GL27        Great Lakes Grids
+    IGNF        French coordinate systems supplied by the IGNF
+    ITRF2000    Full set of transformation parameters between ITRF2000 and other
+                ITRF's
+    ITRF2008    Full set of transformation parameters between ITRF2008 and other
+                ITRF's
+    ITRF2014    Full set of transformation parameters between ITRF2014 and other
+                ITRF's
+    nad27       State plane coordinate systems, North American Datum 1927
+    nad83       State plane coordinate systems, North American Datum 1983
+    ========    ================================================================
+
+
+Defaults file
+-------------------------------------------------------------------------------
+
+The ``proj_def.dat`` file supplies default parameters for PROJ.4. It uses the same
+syntax as the init files described above. The identifiers in the defaults file
+describe to what the parameters should apply. If the ``<general>`` identifier is
+used, then all parameters in that section applies for all proj-strings. Otherwise
+the identifier is connected to a specific projection. With the defaults file
+supplied with PROJ.4 the default ellipsoid is set to WGS84 (for all proj-strings).
+Apart from that only the Albers Equal Area,
+:doc:`Lambert Conic Conformal<operations/projections/lcc>` and the
+:doc:`Lagrange<operations/projections/lagrng>` projections have default parameters.
+Defaults can be ignored by adding the ``+no_def`` parameter to a proj-string.
+
diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst
new file mode 100644
index 00000000..98e607a7
--- /dev/null
+++ b/docs/source/usage/transformation.rst
@@ -0,0 +1,314 @@
+.. _transformation:
+
+================================================================================
+Geodetic transformation
+================================================================================
+
+PROJ.4 can do everything from the most simple projection to very complex
+transformations across many reference frames. While originally developed as a
+tool for cartographic projections, PROJ.4 has over time evolved into a powerfull
+generic coordinate transformation engine that makes it possible to do both
+large scale cartographic projections as well as coordinate transformation at a
+geodetic high precision level. This chapter delves into the details of how
+geodetec transformations of varying complexity can be performed.
+
+In PROJ.4, two frameworks for geodetic transformations exists, the *cs2cs*
+framework and the *transformation pipelines* framework. The first is the original,
+and limited, framework for doing geodetic transforms in PROJ.4 The latter is a
+newer addition that aims to be a more complete transformation framework. Both are
+described in the sections below. Large portions of the text are based on
+[EversKnudsen2017]_.
+
+Before describing the details of the two frameworks, let us first remark that
+most cases of geodetic transformations can be expressed as a series of elementary
+operations, the output of one operation being the input of the next. E.g. when
+going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the
+simplest case, go through 5 steps:
+
+1. Back-project the UTM coordinates to geographic coordinates
+2. Convert the geographic coordinates to 3D cartesian geocentric coordinates
+3. Apply a Helmert transformation from ED50 to ETRS89
+4. Convert back from cartesian to geographic coordinates
+5. Finally project the geographic coordinates to UTM zone 32 planar coordinates.
+
+
+Transformation pipelines
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The homology between the above steps and a Unix shell style pipeline is evident.
+It is there the main architectural inspiration behind the transformation pipeline
+framework. The pipeline framework is realized by utilizing a special "projection",
+that takes as its user supplied arguments, a series of elementary operations,
+which it strings together in order to implement the full transformation needed.
+Additionally, a number of elementary geodetic operations, including Helmert
+transformations, general high order polynomial shifts and the Molodensky
+transformation are available as part of the pipeline framework.
+In anticipation of upcoming support for full time-varying transformations, we
+also introduce a 4D spatiotemporal data type, and a programming interface
+(API) for handling this.
+
+The Molodensky transformation converts directly from geodetic coordinates
+in one datum, to geodetic coordinates in another datum, while the (typically more
+accurate) Helmert transformation converts from 3D cartesian to 3D cartesian
+coordinates. So when using the Helmert transformation one typically needs to do an
+initial conversion from geodetic to cartesian coordinates, and a final conversion
+the other way round, to arrive at the desired result. Fortunately, this three-step
+compound transformation has the attractive characteristic that each step depends
+only on the output of the immediately preceding step. Hence, we can build a
+geodetic-to-geodetic Helmert transformation by tying together the outputs and inputs
+of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style.
+The pipeline driver, makes this kind of chained transformations possible.
+The implementation is compact, consisting of just one pseudo-projection, called
+``pipeline``, which takes as its arguments strings of elementary projections
+(note: "projection" is the, slightly misleading, PROJ.4 term used for any kind of
+transformation).
+The pipeline pseudo projection is supplemented by a number of elementary
+transformations, all in all providing a framework for building high accuracy
+solutions for a wide spectrum of geodetic tasks.
+
+
+As a first example, let us take a look at the iconic
+*geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in
+the itroduction). In PROJ.4 it can be implemented as
+
+::
+
+    proj=pipeline
+    step proj=cart ellps=intl
+    step proj=helmert
+         x=-81.0703  y=-89.3603  z=-115.7526
+        rx=-0.48488 ry=-0.02436 rz=-0.41321  s=-0.540645
+    step proj=cart inv ellps=GRS80
+
+The pipeline can be expanded at both ends to accommodate whatever coordinate type
+is needed for input and output: In the example below, we transform from the
+deprecated Danish System 45, a 2D system with some tension in the original defining
+network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial
+transformation (the init=./s45b... step, s45b.pol is a file containing the
+polynomial coefficients), taking the S45 coordinates to a technical coordinate
+system (TC32), defined to represent "UTM zone 32 coordinates, as they would look if
+the Helmert transformation between ED50 and ETRS89 was perfect". The TC32
+coordinates are then converted back to geodetic(ED50) coordinates, using an
+inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89),
+using the relevant Helmert transformation, and back to geodetic(ETRS89), before
+finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step
+pipeline, implementing a transformation with centimeter level accuracy from a
+deprecated system with decimeter level tensions.
+
+::
+
+    proj=pipeline
+    step init=./s45b.pol:s45b_tc32
+    step proj=utm inv ellps=intl zone=32
+    step proj=cart ellps=intl
+    step proj=helmert
+          x=-81.0703  y=-89.3603  z=-115.7526
+         rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645
+    step proj=cart inv ellps=GRS80
+    step proj=utm ellps=GRS80 zone=33
+
+With the pipeline framework spatiotemporal transformation is possible. This is
+possible by leveraging the time dimension in PROJ.4 that enables 4D coordinates
+(three spatial components and one temporal component) to be passed through a
+transformation pipeline. In the example below a transformation from ITRF93 to
+ITRF2000 is defined. The temporal component is given as GPS weeks in the input
+data, but the 14-parameter Helmert transform expects temporal units in decimalyears.
+Hence the first step in the pipeline is the unitconvert pseudo-projection that makes
+sure the correct units are passed along to the Helmert transform.
+Most parameters of the Helmert transform are taken from [AltamimiEtAl2002]_,
+except the epoch which is the epoch of the transformation. The default setting is to
+use “coordinate frame” convention of the Helmert transform, but “position vector”
+convention can also be used. The last step in the pipeline is converting the
+coordinate timestamps back to GPS weeks.
+
+::
+
+    proj=pipeline
+    step proj=unitconvert t_in=gps_week t_out=decimalyear
+    step proj=helmert
+         x=0.0127 y=0.0065 z=-0.0209 s=0.00195
+         rx=0.00039 ry=-0.00080 rz=0.00114
+         dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001
+         drx=0.00011 dry=0.00019 drz=-0.00007
+         epoch=1988.0
+    step proj=unitconvert t_in=decimalyear t_out=gps_week
+
+
+cs2cs paradigm
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    ============   ==============================================================
+    Parameter      Description
+    ============   ==============================================================
+    +datum         Datum name (see ``proj -ld``)
+    +geoidgrids    Filename of GTX grid file to use for vertical datum transforms
+    +nadgrids      Filename of NTv2 grid file to use for datum transforms
+    +towgs84       3 or 7 term datum transform parameters
+    +to_meter      Multiplier to convert map units to 1.0m
+    +vto_meter     Vertical conversion to meters
+    ============   ==============================================================
+
+The *cs2cs* framework delivers a subset of the geodetic transformations available
+with the *pipeline* framework. Coordinate transformations done in this framework
+are transformed in a two-step process with WGS84 as a pivot datum That is, the
+input coordinates are transformed to WGS84 geodetic coordinates and then transformed
+from WGS84 coordinates to the specified output coordinate reference system, by
+utilizing either the Helmert transform, datum shift grids or a combination of both.
+Datum shifts can be described in a proj-string with the parameters ``+towgs84``,
+``+nadgrids`` and ``+geoidgrids``.
+An inverse transform exists for all three and is applied if
+specified in the input proj-string. The most common is ``+towgs84``, which is used to
+define a 3- or 7-parameter Helmert shift from the input reference frame to WGS84.
+Exactly which realization of WGS84 is not specified, hence a fair amount of
+uncertainty is introduced in this step of the transformation. With the +nadgrids
+parameter a non-lineaer planar correction derived from interpolation in a
+correction grid can be applied. Originally this was implemented as a means to
+transform coordinates between the american datums NAD27 and NAD83, but corrections
+can be applied for any datum for which a correction grid exists. The inverse
+transform for the horizontal grid shift is "dumb", in the sense that the
+correction grid is applied verbatim without taking into account that the inverse
+operation is non-linear. Similar to the horizontal grid correction, ``+geoidgrids``
+can be used to perform grid corrections in the vertical component.
+Both grid correction methods allow inclusion of more than one grid in the same
+transformation
+
+In contrast to the *transformation pipeline* framework, transformations with the
+*cs2cs* framework are expressed as two separate proj-strings. One proj-string *to*
+WGS84 and one *from* WGS84. Together they form the mapping from the source
+coordinate reference system to the destination coordinate reference system.
+When used with the ``cs2cs`` the source and destination CRS's are separated by the
+special ``+to`` parameter.
+
+The following example demonstrates converting from the Greek GGRS87 datum
+to WGS84 with the ``+towgs84`` parameter.
+
+::
+
+    cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62
+        +to +proj=latlong +datum=WGS84
+    20 35
+    20d0'5.467"E    35d0'9.575"N 8.570
+
+The EPSG database provides this example for transforming from WGS72 to WGS84
+using an approximated 7 parameter transformation.
+
+::
+
+    cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \
+        +to +proj=latlong +datum=WGS84
+    4 55
+    4d0'0.554"E     55d0'0.09"N 3.223
+
+
+Grid Based Datum Adjustments
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+In many places (notably North America and Austrialia) national geodetic
+organizations provide grid shift files for converting between different datums,
+such as NAD27 to NAD83.  These grid shift files include a shift to be applied
+at each grid location. Actually grid shifts are normally computed based on an
+interpolation between the containing four grid points.
+
+PROJ.4 supports use of grid files for shifting between various reference frames.
+The grid shift table formats are ctable (the binary format produced by the PROJ.4
+``nad2bin`` program), NTv1 (the old Canadian format), and NTv2 (``.gsb`` - the new
+Canadian and Australian format).
+
+The text in this section is based on the *cs2cs* framework. Gridshifting is off
+course also possible with the *pipeline* framework. The major difference between the
+two is that the *cs2cs* framework is limited to grid mappings to WGS84, whereas with
+*transformation pipelines* it is possible to perform grid shifts between any two
+reference frames, as long as a grid exists.
+
+Use of grid shifts with ``cs2cs`` is specified using the ``+nadgrids``
+keyword in a coordinate system definition. For example:
+
+::
+
+    % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 50
+    EOF
+    111d0'2.952"W   50d0'0.111"N 0.000
+
+In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was
+loaded, and used to get a grid shift value for the selected point.
+
+It is possible to list multiple grid shift files, in which case each will be
+tried in turn till one is found that contains the point being transformed.
+
+::
+
+    cs2cs +proj=latlong +ellps=clrk66 \
+              +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 44
+    EOF
+    111d0'2.788"W   43d59'59.725"N 0.000
+
+
+Skipping Missing Grids
+................................................................................
+
+The special prefix ``@`` may be prefixed to a grid to make it optional.  If it
+not found, the search will continue to the next grid.  Normally any grid not
+found will cause an error.  For instance, the following would use the
+``ntv2_0.gsb`` file if available (see :ref:`nonfreegrids`), otherwise it would
+fallback to using the ``ntv1_can.dat`` file.
+
+::
+
+    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 50
+    EOF
+    111d0'3.006"W   50d0'0.103"N 0.000
+
+The null Grid
+................................................................................
+
+A special ``null`` grid shift file is shift with releases after 4.4.6 (not
+inclusive).  This file provides a zero shift for the whole world.  It may be
+listed at the end of a nadgrids file list if you want a zero shift to be
+applied to points outside the valid region of all the other grids.  Normally if
+no grid is found that contains the point to be transformed an error will occur.
+
+::
+
+    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 45
+    EOF
+    111d0'3.006"W   50d0'0.103"N 0.000
+
+    cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
+        +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+    -111 44
+    -111 55
+    EOF
+    111d0'2.788"W   43d59'59.725"N 0.000
+    111dW   55dN 0.000
+
+For more information see the chapter on :ref:`Grids`.
+
+Caveats
+................................................................................
+
+* Where grids overlap (such as conus and ntv1_can.dat for instance) the first
+  found for a point will be used regardless of whether it is appropriate or
+  not.  So, for instance, ``+nadgrids=ntv1_can.dat``,conus would result in
+  the Canadian data being used for some areas in the northern United States
+  even though the conus data is the approved data to use for the area.
+  Careful selection of files and file order is necessary.  In some cases
+  border spanning datasets may need to be pre-segmented into Canadian and
+  American points so they can be properly grid shifted
+* There are additional grids for shifting between NAD83 and various HPGN
+  versions of the NAD83 datum.  Use of these haven't been tried recently so
+  you may encounter problems.  The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla
+  are examples of high precision grid shifts.  Take care!
+* Additional detail on the grid shift being applied can be found by setting
+  the PROJ_DEBUG environment variable to a value.  This will result in output
+  to stderr on what grid is used to shift points, the bounds of the various
+  grids loaded and so forth
+* The *cs2cs* framework always assumes that grids contain a shift **to**  NAD83 (essentially
+  WGS84). Other types of grids can be used with the *pipeline* framework.
diff --git a/examples/pj_obs_api_mini_demo.c b/examples/pj_obs_api_mini_demo.c
index 855c37f8..34021488 100644
--- a/examples/pj_obs_api_mini_demo.c
+++ b/examples/pj_obs_api_mini_demo.c
@@ -31,6 +31,9 @@
     and destructor may be left out, and the default context selected
     by passing a null-pointer to pj_create.
 
+    Note: This file is in-lined in the documentation. Any changes must be
+    reflected in docs/source/development/quickstart.rst 
+
     Thomas Knudsen, 2016-10-30/2017-07-06
 *******************************************************************************/
 #include <stdio.h>
@@ -53,7 +56,6 @@ int main (void) {
     a = proj_coord (proj_torad(12), proj_torad(55), 0, 0);
 
     /* transform to UTM zone 32, then back to geographical */
-    /* note the use of union selectors to indicate what kind of coordinates are expected */
     b = proj_trans_coord (P, PJ_FWD, a);
     printf ("easting: %g, northing: %g\n", b.en.e, b.en.n);
     b = proj_trans_coord (P, PJ_INV, b);