Merge pull request #990 from kbevers/doc-frontpage-about

Documentation improvements

15 files changed, 567 insertions, 145 deletions

diff --git a/docs/source/about.rst b/docs/source/about.rst
new file mode 100644
index 00000000..198dbead
--- /dev/null
+++ b/docs/source/about.rst
@@ -0,0 +1,69 @@
+###############################################################################
+About
+###############################################################################
+
+PROJ is a generic coordinate transformation software, that transforms geospatial
+coordinates from one coordinate reference system (CRS) to another. This
+includes cartographic projections as well as geodetic transformations.
+
+PROJ includes :ref:`command line applications<apps>` for easy conversion of
+coordinates from text files or directly from user input. In addition to the
+command line utilities PROJ also exposes an
+:ref:`application programming interface<reference>`, or API in short. The API
+let developers use the functionality of PROJ in their own software without having
+to implement similar functionality themselves.
+
+PROJ started purely as a cartography application letting users convert geodetic
+coordinates into projected coordinates using a number of different cartographic
+projections. Over the years, as the need has become apparent, support for datum
+shifts has slowly worked it's way into PROJ as well. Today PROJ support more
+than a hundred different map projections and can transform coordinates between
+datums using all but the most obscure geodetic techniques.
+
+Citation
+-------------------------------------------------------------------------------
+
+To cite PROJ in publications use:
+
+  PROJ contributors (2018). PROJ coordinate transformation software
+  library. Open Source Geospatial Foundation. URL http://proj4.org/.
+
+A BibTeX entry for LaTeX users is
+
+.. code-block:: latex
+
+  @Manual{,
+    title = {{PROJ} coordinate transformation software library},
+    author = {{PROJ contributors}},
+    organization = {Open Source Geospatial Foundation},
+    year = {2018},
+    url = {http://proj4.org/},
+  }
+
+License
+-------------------------------------------------------------------------------
+
+PROJ uses the MIT license. The software was initially released by the USGS in
+the public domain. When Frank Warmerdam took over the development of PROJ it
+was moved under the MIT license. The license is as follows:
+
+     Copyright (c) 2000, Frank Warmerdam
+
+     Permission is hereby granted, free of charge, to any person obtaining a
+     copy of this software and associated documentation files (the "Software"),
+     to deal in the Software without restriction, including without limitation
+     the rights to use, copy, modify, merge, publish, distribute, sublicense,
+     and/or sell copies of the Software, and to permit persons to whom the
+     Software is furnished to do so, subject to the following conditions:
+
+     The above copyright notice and this permission notice shall be included
+     in all copies or substantial portions of the Software.
+
+     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+     OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+     THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+     DEALINGS IN THE SOFTWARE.
+
diff --git a/docs/source/community/channels.rst b/docs/source/community/channels.rst
new file mode 100644
index 00000000..ea12c3f7
--- /dev/null
+++ b/docs/source/community/channels.rst
@@ -0,0 +1,37 @@
+.. _channels:
+
+===========================
+Communication channels
+===========================
+
+Mailing list
+-------------------------------------------------------------------------------
+
+Users and developers of the library are using the mailing list to discuss all
+things related to PROJ. The mailing list is the primary forum for asking for
+help with use of PROJ. The mailing list is also used for announcements, discussions
+about the development of the library and from time to time interesting discussions
+on geodesy appear as well. You are more than welcome to join in on the discussions!
+
+
+The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj
+
+
+GitHub
+-------------------------------------------------------------------------------
+
+GitHub is the development platform we use for collaborating on the PROJ code.
+We use GitHub to keep track of the changes in the code and to index bug reports
+and feature requests. We are happy to take contributions in any form, either
+as code, bug reports, documentation or feature requests. See :ref:`contributing`
+for more info on how you can help improve PROJ.
+
+The PROJ GitHub page can be found at https://github.com/OSGeo/proj.4
+
+.. note::
+
+    The issue tracker on GitHub is only meant to keep track of bugs, feature
+    request and other things related to the development of PROJ. Please ask
+    your questions about the use of PROJ on the mailing list instead.
+
+
diff --git a/docs/source/development/for_proj_contributors.rst b/docs/source/community/code_contributions.rst
index d85f5cb1..ef144399 100644
--- a/docs/source/development/for_proj_contributors.rst
+++ b/docs/source/community/code_contributions.rst
@@ -1,7 +1,7 @@
-.. _for_proj_contributors:
+.. _code_contributions:
 
 ================================================================================
-Development rules and tools for PROJ code contributors
+Guidelines for PROJ code contributors
 ================================================================================
 
 This is a guide for PROJ, casual or regular, code contributors.
diff --git a/docs/source/contributing.rst b/docs/source/community/contributing.rst
index 368f659f..d56aef6e 100644
--- a/docs/source/contributing.rst
+++ b/docs/source/community/contributing.rst
@@ -92,13 +92,13 @@ 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's supported projections please
-use the `Mercator projection <http://proj4.org/projections/merc.html>`__
+use the :doc:`Mercator projection <../operations/projections/merc>`
 as a template.
 
 Code contributions
 ------------------
 
-See :doc:`Code contributions <development/for_proj_contributors>`
+See :doc:`Code contributions <code_contributions>`
 
 Legalese
 ~~~~~~~~
diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst
new file mode 100644
index 00000000..675d107a
--- /dev/null
+++ b/docs/source/community/index.rst
@@ -0,0 +1,16 @@
+.. _community:
+
+Community
+===============================================================================
+
+The PROJ community is what makes the software stand out from its competitors.
+PROJ is used and developed by group of very enthusiastic, knowledgeable and
+friendly people. Whether you are a first time user of PROJ or a long-time
+contributor the community is always very welcoming.
+
+.. toctree::
+   :maxdepth: 1
+
+   channels
+   contributing
+   code_contributions
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
index 0a5fea60..3f8a7bf6 100644
--- a/docs/source/development/index.rst
+++ b/docs/source/development/index.rst
@@ -19,4 +19,3 @@ PROJ project or using the library in their own software.
    cmake
    bindings
    migration
-   for_proj_contributors
diff --git a/docs/source/download.rst b/docs/source/download.rst
index d7c60d63..32ce8012 100644
--- a/docs/source/download.rst
+++ b/docs/source/download.rst
@@ -4,13 +4,11 @@
 Download
 ================================================================================
 
-.. contents:: Contents
-   :depth: 3
-   :backlinks: none
+Here you can download current and previous releases of PROJ. We only supply a
+distribution of the source code and various resource files archives. See
+:ref:`install` for information on how to get pre-built packages of PROJ.
 
-Release Notes
---------------------------------------------------------------------------------
-* `NEWS <https://github.com/OSGeo/proj.4/blob/master/NEWS>`_ 
+.. _current_release:
 
 Current Release
 --------------------------------------------------------------------------------
@@ -20,6 +18,7 @@ Current Release
 * **2018-03-01** `proj-datumgrid-europe-1.0.zip`_
 * **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_
 * **2018-03-01** `proj-datumgrid-oceania-1.0.zip`_
+* **PDF Manual** `proj.pdf`_
 
 Past Releases
 --------------------------------------------------------------------------------
@@ -42,31 +41,4 @@ Past Releases
 .. _`proj-datumgrid-north-america-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.0.zip
 .. _`proj-datumgrid-oceania-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip
 .. _`md5`: http://download.osgeo.org/proj/proj-5.0.1.tar.gz.md5
-
-Binaries
---------------------------------------------------------------------------------
-
-Linux
-................................................................................
-
-* `RedHat RPMs <http://yum.postgresql.org>`__
-* `SUSE <http://download.opensuse.org/repositories/Application:/Geo/ openSUSE Application:Geo Repository>`__
-* `Debian <http://packages.debian.org/proj>`__
-* `pkgsrc <http://pkgsrc.se/misc/proj pkgsrc package>`__
-* `Delphi <http://www.triplexware.huckfinn.de/geogfix.html#proj>`__
-
-Docker
-................................................................................
-
-A `Docker`_ image with just PROJ binaries and a full compliment of grid shift
-files is available on `DockerHub`_:
-
-.. _`Docker`: https://docker.org
-.. _`DockerHub`: https://hub.docker.com/r/osgeo/proj.4/
-
-Windows
-................................................................................
-
-* `OSGeo4W`_ contains 32-bit and 64-bit Windows binaries, including support for many :ref:`grids <resource_files>`.
-
-.. _`OSGeo4W`: https://trac.osgeo.org/osgeo4w/
+.. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index 6d6d2280..333a5029 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -4,9 +4,11 @@
 FAQ
 ******************************************************************************
 
-.. contents:: Contents
-   :depth: 3
-   :backlinks: none
+.. only:: not latex
+
+    .. contents::
+       :depth: 3
+       :backlinks: none
 
 
 
diff --git a/docs/source/geodesic.rst b/docs/source/geodesic.rst
index 8f6f5bbe..f677ae1d 100644
--- a/docs/source/geodesic.rst
+++ b/docs/source/geodesic.rst
@@ -3,10 +3,6 @@
 Geodesic calculations
 =====================
 
-.. contents:: Contents
-   :depth: 2
-   :backlinks: none
-
 Introduction
 ------------
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 72bf1600..86393291 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,43 +1,13 @@
 .. _home:
 
-******************************************************************************
 PROJ
-******************************************************************************
-
-PROJ 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 is maintained on `GitHub <http://github.com/OSGeo/proj.4/>`_.
-
-.. only:: html
-
-    =============  ================================================================
-     Platform                Test Status and Coverage
-    =============  ================================================================
-    Travis         |travis|
-    AppVeyor       |appveyor|
-    Coverage       |coverals|
-    =============  ================================================================
-
-
-    .. |travis| image:: https://travis-ci.org/OSGeo/proj.4.svg?branch=master
-                        :target:  https://travis-ci.org/OSGeo/proj.4
-    .. |appveyor| image:: https://ci.appveyor.com/api/projects/status/584j49uguwoo5evi?svg=true
-                        :target: https://ci.appveyor.com/project/OSGeo/proj-4
-    .. |coverals| image:: https://coveralls.io/repos/OSGeo/proj.4/badge.svg?branch=master
-                        :target: https://coveralls.io/r/OSGeo/proj.4?branch=master
-
-.. only:: not latex
-
-   Full documentation is available as a single PDF at
-   https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf
-
-Documentation
-=================
+###############################################################################
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
+   :hidden:
 
+   about
    download
    install
    usage/index
@@ -46,20 +16,308 @@ Documentation
    resource_files
    geodesic
    development/index
+   community/index
    faq
-   contributing
    glossary
-   license
    references
 
-Mailing List
-================================================================================
+.. only:: html
+
+    PROJ 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 is maintained on `GitHub <http://github.com/OSGeo/proj.4/>`_.
+
+
+    NEWS
+    ---------------------------------------------------------------------------
+
+    .. attention::
+
+        The ``projects.h`` header and the functions related to it is considered
+        deprecated from version 5.0.0 and onwards. The header  will be removed
+        from PROJ in version 6.0.0 scheduled for release February 1st 2019.
+
+    .. attention::
+
+        The nmake build system on Windows will not be supported from
+        version 6.0.0 on onwards. Use CMake instead.
+
+    .. attention::
+
+        The ``proj_api.h`` header and the functions related to it is
+        considered deprecated from version 5.0.0 and onwards. The header will be
+        removed from PROJ in version 7.0.0 scheduled for release February 1st
+        2020.
+
+
+
+
+    PROJ 5.0.1
+    ++++++++++++++++++++++++++++++++++++++++
+    *March 1st 2018*
+
+    Bug fixes
+    ***********
+
+    * Handle ellipsoid change correctly in pipelines when ``+towgs84=0,0,0`` is set (`#881 <https://github.com/OSGeo/proj.4/issues/881>`_)
+
+
+    * Handle the case where nad_ctable2_init returns NULL (`#883 <https://github.com/OSGeo/proj.4/issues/883>`_)
+
+
+    * Avoid shadowed declaration errors with old gcc (`#880 <https://github.com/OSGeo/proj.4/issues/880>`_)
+
+
+    * Expand ``+datum`` properly in pipelines (`#872 <https://github.com/OSGeo/proj.4/issues/872>`_)
+
+
+    * Fail gracefully when incorrect headers are encountered in grid files (`#875 <https://github.com/OSGeo/proj.4/issues/875>`_)
+
+
+    * Improve roundtrip stability in pipelines using ``+towgs84`` (`#871 <https://github.com/OSGeo/proj.4/issues/871>`_)
+
+
+    * Fixed typo in gie error codes (`#861 <https://github.com/OSGeo/proj.4/issues/861>`_)
+
+
+    * Numerical stability fixes to the geodesic package (`#826 <https://github.com/OSGeo/proj.4/issues/826>`_ & `#843 <https://github.com/OSGeo/proj.4/issues/843>`_)
+
+
+    * Make sure that transient errors are returned correctly (`#857 <https://github.com/OSGeo/proj.4/issues/857>`_)
+
+
+    * Make sure that locally installed header files are not used when building PROJ (`#849 <https://github.com/OSGeo/proj.4/issues/849>`_)
+
+
+    * Fix inconsistent parameter names in ``proj.h``/``proj_4D_api.c`` (`#842 <https://github.com/OSGeo/proj.4/issues/842>`_)
+
+
+    * Make sure ``+vunits`` is applied (`#833 <https://github.com/OSGeo/proj.4/issues/833>`_)
+
+
+    * Fix incorrect Web Mercator transformations (`#834 <https://github.com/OSGeo/proj.4/issues/834>`_)
+
+
+
+    PROJ 5.0.0
+    +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+    *February 1st 2018*
+
+    This version of PROJ introduces some significant extensions and
+    improvements to (primarily) the geodetic functionality of the system.
+
+    The main driver for introducing the new features is the emergence of
+    dynamic reference frames, the increasing use of high accuracy GNSS,
+    and the related growing demand for accurate coordinate
+    transformations.  While older versions of PROJ included some geodetic
+    functionality, the new framework lays the foundation for turning PROJ
+    into a generic geospatial coordinate transformation engine.
+
+    The core of the library is still the well established projection code.
+    The new functionality is primarily exposed in a new programming
+    interface and a new command line utility, :ref:`cct<cct>`
+    (for "Coordinate Conversion and Transformation").  The old programming interface is
+    still available and can - to some extent - use the new geodetic
+    transformation features.
+
+    The internal architecture has also seen many changes and much
+    improvement.  So far, these improvements respect the existing
+    programming interface. But the process has revealed a need to simplify
+    and reduce the code base, in order to support sustained active
+    development.
+
+
+    **Therefore we have scheduled regular releases over the coming years**
+    **which will gradually remove the old programming interface.**
+
+    **This will cause breaking changes with the next two major version**
+    **releases, which will affect all projects that depend on PROJ**
+    **(cf. section "deprecations" below).**
+
+    The decision to break the existing API has not been easy, but has
+    ultimately been deemed necessary to ensure the long term survival of
+    the project. Not only by improving the maintainability immensely, but
+    also by extending the potential user (and hence developer) community.
+
+    The end goal is to deliver a generic coordinate transformation
+    software package with a clean and concise code base appealing to
+    both users and developers.
+
+
+    Versioning and naming
+    ***************************************************************************
+
+    For the first time in more than 25 years the major version number of
+    the software is changed. The decision to do this is based on the many
+    new features and new API. While backwards compatibility remains -
+    except in a few rare corner cases - the addition of a new and improved
+    programming interface warrants a new major release.
+
+    The new major version number unfortunately leaves the project in a bit
+    of a conundrum regarding the name. For the majority of the life-time
+    of the product it has been known as PROJ.4, but since we have now
+    reached version 5 the name is no longer aligned with the version
+    number.
+
+    Hence we have decided to decouple the name from the version number and
+    from this version and onwards the product will simply be called PROJ.
+
+    In recognition of the history of the software we are keeping PROJ.4 as
+    the *name of the organizing project*. The same project team also
+    produces the datum-grid package.
+
+    In summary:
+
+    * The PROJ.4 project provides the product PROJ, which is now at
+      version 5.0.0.
+
+    * The foundational component of PROJ is the library libproj.
+
+    * Other PROJ components include the application proj, which provides
+      a command line interface to libproj.
+
+    * The PROJ.4 project also distributes the datum-grid package,
+      which at the time of writing is at version 1.6.0.
+
+    Updates
+    ***************************************************************************
+
+    * Introduced new API in ``proj.h``.
+
+        - The new API is orthogonal to the existing ``proj_api.h`` API and the internally used ``projects.h`` API.
+
+        - The new API adds the ability to transform spatiotemporal (4D) coordinates.
+
+        - Functions in the new API use the ``proj_`` namespace.
+
+        - Data types in the new API use the ``PJ_`` namespace.
+
+    *  Introduced the concept of "transformation pipelines" that makes possible to do complex geodetic transformations of coordinates by daisy chaining simple coordinate operations.
+
+    * Introduced :ref:`cct`, the Coordinate Conversion and Transformation application.
+
+    * Introduced :ref:`gie`, the Geospatial Integrity Investigation Environment.
+
+      - Selftest invoked by ``-C`` flag in :ref:`proj` has been removed
+      - Ported approx. 1300 built-in selftests to :ref:`gie` format
+      - Ported approx. 1000 tests from the gigs test framework
+      - Added approx. 200 new tests
+
+    * Adopted terminology from the OGC/ISO-19100 geospatial standards series. Key definitions are:
+
+        - At the most generic level, a *coordinate operation* is a change of coordinates, based on a one-to-one relationship, from one coordinate reference system to another.
+
+        - A *transformation* is a coordinate operation in which the two coordinate reference systems are based on different datums, e.g. a change from a global reference frame to a regional frame.
+
+        - A *conversion* is a coordinate operation in which both coordinate reference systems are based on the same datum, e.g. change of units of coordinates.
+
+        - A *projection* is a coordinate conversion from an ellipsoidal coordinate system to a plane. Although projections are simply conversions according to the standard, they are treated as separate entities in PROJ as they make up the vast majority of operations in the library.
+
+    * New operations
+
+        - :ref:`The pipeline operator<pipeline>` (``pipeline``)
+
+        - Transformations
+            + :ref:`Helmert transform<helmert>` (``helmert``)
+            + Horner real and complex polynomial evaluation (``horner``)
+            + :ref:`Horizontal gridshift<hgridshift>` (``hgridshift``)
+            + :ref:`Vertical gridshift<vgridshift>` (``vgridshift``)
+            + :ref:`Molodensky transform<molodensky>` (``molodensky``)
+            + :ref:`Kinematic gridshift with deformation model<deformation>` (``deformation``)
+
+        - Conversions
+            + :ref:`Unit conversion<unitconvert>` (``unitconvert``)
+            + :ref:`Axis swap<axisswap>` (``axisswap``)
+
+        - Projections
+            + :ref:`Central Conic projection<ccon>` (``ccon``)
+
+    * Significant documentation updates, including
+
+        - Overhaul of the structure of the documentation
+        - A better introduction to the use of PROJ
+        - :ref:`A complete reference to the new API<reference>`
+        - a complete rewrite of the section on geodesic calculations
+        - Figures for all projections
+
+    * New "free format" option for operation definitions, which permits separating tokens by whitespace when specifying key/value- pairs, e.g. ``proj = merc lat_0 = 45``.
+
+    * Added metadata to init-files that can be read with the :c:func:`proj_init_info` function in the new ``proj.h`` API.
+
+    * Added ITRF2000, ITRF2008 and ITRF2014 init-files with ITRF transformation parameters, including plate motion model parameters.
+
+    * Added ellipsoid parameters for GSK2011, PZ90 and "danish". The latter is similar to the already supported andrae ellipsoid, but has a slightly different semimajor axis.
+
+    * Added Copenhagen prime meridian.
+
+    * Updated EPSG database to version 9.2.0.
+
+    * Geodesic library updated to version 1.49.2-c.
+
+    * Support for analytical partial derivatives has been removed.
+
+    * Improved performance in Winkel Tripel and Aitoff.
+
+    * Introduced ``pj_has_inverse()`` function to ``proj_api.h``. Checks if an operation has an inverse. Use this instead of checking whether ``P->inv`` exists, since that can no longer be relied on.
+
+    * ABI version number updated to 13:0:0.
+
+    * Removed support for Windows CE.
+
+    * Removed the VB6 COM interface.
+
+    Bug fixes
+    ***************************************************************************
+
+    * Fixed incorrect convergence calculation in Lambert Conformal Conic. (`#16 <https://github.com/OSGeo/proj.4/issues/16>`_)
+
+
+    * Handle ellipsoid parameters correctly when using ``+nadgrids=@null``. (`#22 <https://github.com/OSGeo/proj.4/issues/22>`_)
+
+
+    * Return correct latitude when using negative northings in Transverse Mercator. (`#138 <https://github.com/OSGeo/proj.4/issues/138>`_)
+
+
+    * Return correct result at origin in inverse Mod. Stereographic of Alaska. (`#161 <https://github.com/OSGeo/proj.4/issues/161>`_)
+
+
+    * Return correct result at origin in inverse Mod. Stereographic of 48 U.S. (`#162 <https://github.com/OSGeo/proj.4/issues/162>`_)
+
+
+    * Return correct result at origin in inverse Mod. Stereographic of 50 U.S. (`#163 <https://github.com/OSGeo/proj.4/issues/163>`_)
+
+
+    * Return correct result at origin in inverse Lee Oblated Stereographic. (`#164 <https://github.com/OSGeo/proj.4/issues/164>`_)
+
+
+    * Return correct result at origin in inverse Miller Oblated Stereographic. (`#165 <https://github.com/OSGeo/proj.4/issues/165>`_)
+
+
+    * Fixed scaling and wrap-around issues in Oblique Cylindrical Equal Area. (`#166 <https://github.com/OSGeo/proj.4/issues/166>`_)
+
+
+    * Corrected a coefficient error in inverse Transverse Mercator. (`#174 <https://github.com/OSGeo/proj.4/issues/174>`_)
+
+    * Respect ``-r`` flag when calling :program:`proj` with ``-V``. (`#184 <https://github.com/OSGeo/proj.4/issues/184>`_)
+
+    * Remove multiplication by 2 at the equator error in Stereographic projection. (`#194 <https://github.com/OSGeo/proj.4/issues/194>`_)
+
+    * Allow +alpha=0 and +gamma=0 when using Oblique Mercator. (`#195 <https://github.com/OSGeo/proj.4/issues/195>`_)
+
+    * Return correct result of inverse Oblique Mercator when alpha is between 90 and 270. (`#331 <https://github.com/OSGeo/proj.4/issues/331>`_)
+
+    * Avoid segmentation fault when accessing point outside grid. (`#396 <https://github.com/OSGeo/proj.4/issues/396>`_)
+
+    * Avoid segmentation fault on NaN input in Robin inverse. (`#463 <https://github.com/OSGeo/proj.4/issues/463>`_)
+
+    * Very verbose use of :program:`proj` (``-V``) on Windows is fixed. (`#484 <https://github.com/OSGeo/proj.4/issues/484>`_)
 
-The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj
+    * Fixed memory leak in General Oblique Transformation. (`#497 <https://github.com/OSGeo/proj.4/issues/497>`_)
 
-Indices and tables
-==================
+    * Equations for meridian convergence and partial derivatives have
+      been corrected for non-conformal projections. (`#526 <https://github.com/OSGeo/proj.4/issues/526>`_)
 
-* :ref:`genindex`
-* :ref:`search`
+    * Fixed scaling of cartesian coordinates in ``pj_transform()``. (`#726 <https://github.com/OSGeo/proj.4/issues/726>`_)
 
+    * Additional bug fixes courtesy of `Google's OSS-Fuzz program <https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=proj4>`_
diff --git a/docs/source/install.rst b/docs/source/install.rst
index 5b3256a1..03e6bc9d 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -9,6 +9,34 @@ yourself. Below are guides for installing on Windows, Linux and Mac OS X. This
 is a good place to get started if this is your first time using PROJ. More
 advanced users may want to compile the software themselves.
 
+Installation from package management systems
+################################################################################
+
+
+Cross platform
+--------------------------------------------------------------------------------
+
+PROJ is also available via cross platform package managers.
+
+Conda
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The conda package manager includes several PROJ packages. We recommend installing
+from the ``conda-forge`` channel::
+
+    conda install -c conda-forge proj4
+
+Docker
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+A `Docker`_ image with just PROJ binaries and a full compliment of grid shift
+files is available on `DockerHub`_. Get the package with::
+
+    docker pull osgeo/proj.4
+
+.. _`Docker`: https://docker.org
+.. _`DockerHub`: https://hub.docker.com/r/osgeo/proj.4/
+
 Windows
 --------------------------------------------------------------------------------
 
@@ -69,6 +97,99 @@ On Red Hat based system packages are installed with yum::
 Mac OS X
 --------------------------------------------------------------------------------
 
-On OS X PROJ can be installed via the Homebrew package manager:
+On OS X PROJ can be installed via the Homebrew package manager::
 
     brew install proj
+
+PROJ is also available from the MacPorts system::
+
+    sudo ports install proj
+
+Compilation and installation from source code
+################################################################################
+
+The classical way of installing PROJ is via the source code distribution. The
+most recent version is available from the :ref:`download page<current_release>`.
+You will need that and at least the standard *proj-datumgrid* package for a
+successful installation.
+The following guides show how to compile and install the software using the
+Autotools and CMake build systems.
+
+Autotools
+--------------------------------------------------------------------------------
+
+FSF's configuration procedure is used to ease installation of the PROJ system.
+
+.. note::
+    The Autotools build system is only available on UNIX-like systems.
+    Follow the CMake installation guide if you are not using a UNIX-like
+    operating system.
+
+The default destination path prefix for installed files is ``/usr/local``.
+Results from the installation script will be placed into subdirectories ``bin``,
+``include``, ``lib``, ``man/man1`` and ``man/man3``. If this default path prefix
+is proper, then execute::
+
+    ./configure
+
+If another path prefix is required, then execute::
+
+    ./configure --prefix=/my/path
+
+In either case, the directory of the prefix path must exist and be writable by
+the installer.
+
+Before proceeding with the installation we need to add the datum grids. Unzip
+the contents of the *proj-datumgrid* package into ``nad/``::
+
+    unzip proj-datumgrid-1.7.zip -d proj-5.0.1/nad/
+
+The installation will automatically move the grid files to the correct location.
+Alternatively the grids can be installed manually in the directory pointed to
+by the :envvar:`PROJ_LIB` environment variable. The default location is
+``/usr/local/share/proj``.
+
+With the grid files in place we can now build and install PROJ::
+
+    make
+    make install
+
+The install target will create, if necessary, all required sub-directories.
+
+Tests are run with::
+
+    make check
+
+The test suite requires that the proj-datumgrid package is installed in
+:envvar:`PROJ_LIB`.
+
+
+CMake
+--------------------------------------------------------------------------------
+
+With the CMake build system you can compile and install PROJ on more or less any
+platform. After unpacking the source distribution archive step into the source-
+tree::
+
+    cd proj-5.0.1
+
+Create a build directory and step into it::
+
+    mkdir build
+    cd build
+
+From the build directory you can now configure CMake and build the binaries::
+
+    cmake ..
+    cmake --build .
+
+On Windows, one may need to specify generator::
+
+    cmake -G "Visual Studio 15 2017" ..
+
+Tests are run with::
+
+    ctest
+
+The test suite requires that the proj-datumgrid package is installed
+in :envvar:`PROJ_LIB`.
diff --git a/docs/source/license.rst b/docs/source/license.rst
deleted file mode 100644
index bd4f633c..00000000
--- a/docs/source/license.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-.. _license:
-
-================================================================================
-License
-================================================================================
-
-:Author: Frank Warmerdam
-:Contact: warmerdam@pobox.com
-:Date: 2001
-
-PROJ.4 has been placed under an MIT license. I believe this to be as close as
-possible to public domain while satisfying those who say that a copyright
-notice is required in some countries. The COPYING file read as follows:
-
-All source, data files and other contents of the PROJ.4 package are available
-under the following terms. Note that the PROJ 4.3 and earlier was "public
-domain" as is common with US government work, but apparently this is not a well
-defined legal term in many countries. I am placing everything under the
-following MIT style license because I believe it is effectively the same as
-public domain, allowing anyone to use the code as they wish, including making
-proprietary derivatives.
-
-Though I have put my own name as copyright holder, I don't mean to imply I did
-the work. Essentially all work was done by Gerald Evenden.
-
-::
-
-     Copyright (c) 2000, Frank Warmerdam
-
-     Permission is hereby granted, free of charge, to any person obtaining a
-     copy of this software and associated documentation files (the "Software"),
-     to deal in the Software without restriction, including without limitation
-     the rights to use, copy, modify, merge, publish, distribute, sublicense,
-     and/or sell copies of the Software, and to permit persons to whom the
-     Software is furnished to do so, subject to the following conditions:
-
-     The above copyright notice and this permission notice shall be included
-     in all copies or substantial portions of the Software.
-
-     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-     OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-     THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-     DEALINGS IN THE SOFTWARE.
diff --git a/docs/source/references.rst b/docs/source/references.rst
index 75d7f352..807e2faa 100644
--- a/docs/source/references.rst
+++ b/docs/source/references.rst
@@ -1,8 +1,10 @@
 .. _references:
 
-================================================================================
-References
-================================================================================
+.. only:: not latex
+
+    ================================================================================
+    References
+    ================================================================================
 
 .. [AltamimiEtAl2002] Altamimi, Z., P. Sillard, and C. Boucher (2002),
     ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications,
diff --git a/docs/source/resource_files.rst b/docs/source/resource_files.rst
index daf5c00a..b6aa950d 100644
--- a/docs/source/resource_files.rst
+++ b/docs/source/resource_files.rst
@@ -4,10 +4,6 @@
 Resource files
 ================================================================================
 
-.. contents:: Contents
-   :depth: 2
-   :backlinks: none
-
 A number of files containing preconfigured transformations and default parameters
 for certain projections are bundled with the PROJ distribution. Init files
 contains preconfigured proj-strings for various coordinate reference systems
diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst
index f5f46f46..20e82763 100644
--- a/docs/source/usage/projections.rst
+++ b/docs/source/usage/projections.rst
@@ -129,8 +129,8 @@ 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>
+    0 0
+    3d41'16.48"E    0dN 0.000
 
 
 Axis orientation