ReadTheDocs: use ninja, fix branch ref

Fix tests still running despite being disabled in Release 5.2

.gitignore

@@ -1,16 +1,21 @@
 *~
+*.bak
+*.pyc
 build.local.bat
 build.local.sh
 Makefile
 Makefile.in
 CMakeFiles
 CMakeCache.txt
+CMakeSettings.json
 CTestTestfile.cmake
 cmake_install.cmake
 install_manifest.txt
 cmake/project-config*.cmake
 README
+test-driver
 
+/.idea
 /.vs*
 /*.manifest
 /*.swp
@@ -36,9 +41,11 @@ README
 /DartConfiguration.tcl
 /Testing
 
-# html
+# docs
 /html/dl
 /html/robots.txt
+/docs/plot/images
+/latex
 
 # m4
 /m4/libtool.m4
@@ -84,16 +91,37 @@ README
 /src/nad2bin
 /src/proj
 /src/geod
+/src/geodtest.log
+/src/geodtest.trs
 /src/stamp-h*
 /src/proj_config.h
 /src/proj_config.h.in
 /src/cs2cs
 /src/multistresstest
 /src/test228
+/src/test-suite.log
 /src/cct
 /src/gie
 /src/geodtest
 
+# test
+test/googletest/.libs/
+test/googletest/libgtest.la
+test/googletest/src/.deps/
+test/googletest/src/.dirstamp
+test/googletest/src/.libs/
+test/googletest/src/gtest-all.lo
+test/googletest/src/gtest-all.o
+test/unit/.deps/
+test/unit/.libs/
+test/unit/basic_test
+test/unit/basic_test.o
+test/unit/main.o
+test/unit/pj_phi2_test
+test/unit/pj_phi2_test.o
+test/unit/proj_errno_string_test
+test/unit/proj_errno_string_test.o
+
 # Java bridge
 jniwrap/out
 

.readthedocs.yaml

@@ -0,0 +1,45 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "mambaforge-4.10"
+
+  jobs:
+    post_checkout:
+      # Cancel building pull requests when there aren't changed in the docs directory or YAML file.
+      # You can add any other files or directories that you'd like here as well,
+      # like your docs requirements file, or other files that will change your docs build.
+      #
+      # If there are no changes (git diff exits with 0) we force the command to return with 183.
+      # This is a special exit code on Read the Docs that will cancel the build immediately.
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/5.2 -- docs/ .readthedocs.yaml;
+        then
+          exit 183;
+        fi
+      - (git --no-pager log --pretty="tformat:%s -- %b" -1 | grep -viq "skip ci") || exit 183
+    pre_build:
+      - ./docs/rtd/pre_build.sh
+      - ./docs/rtd/plot.sh
+
+  apt_packages:
+    - cmake
+    - ninja-build
+    - g++
+
+formats:
+  - pdf
+  - epub
+
+conda:
+  environment: docs/environment.yml
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true

CITATION

@@ -1,7 +1,7 @@
 To cite PROJ in publications use:
 
   PROJ contributors (2018). PROJ coordinate transformation software
-  library. Open Source Geospatial Foundation. URL http://proj4.org/.
+  library. Open Source Geospatial Foundation. URL https://proj4.org/.
 
 A BibTeX entry for LaTeX users is
 
@@ -10,5 +10,5 @@ A BibTeX entry for LaTeX users is
     author = {{PROJ contributors}},
     organization = {Open Source Geospatial Foundation},
     year = {2018},
-    url = {http://proj4.org/},
+    url = {https://proj4.org/},
   }

CMakeLists.txt

@@ -12,7 +12,7 @@
 cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)
 
 # For historic reasons, the CMake PROJECT-NAME is PROJ4
-project(PROJ4 C)
+project(PROJ4 C CXX)
 set(PROJECT_INTERN_NAME PROJ)
 
 if (NOT CMAKE_VERSION VERSION_LESS 3.1)
@@ -23,11 +23,15 @@ endif ()
 if("${CMAKE_C_COMPILER_ID}" STREQUAL "MSVC")
   # Suppress warning 4706 about assignment within conditional expression
   # Suppress warning 4996 about sprintf, etc., being unsafe
+  # Suppress warning 4589 about Constructor of abstract class...ignores initializer for virtual base class (see https://github.com/weidai11/cryptopp/issues/214#issuecomment-230283061)
   set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /W4 /wd4706 /wd4996 /D_CRT_SECURE_NO_WARNINGS")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /EHsc /W4 /wd4706 /wd4996 /wd4589 /D_CRT_SECURE_NO_WARNINGS")
 elseif("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU")
   set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Wswitch -Wshadow -Wunused-parameter -Wmissing-prototypes -Wmissing-declarations -Wformat -Wformat-security")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11 -Wall -Wextra -Wswitch -Wshadow -Wunused-parameter -Wmissing-declarations -Wformat -Wformat-security")
 elseif("${CMAKE_C_COMPILER_ID}" MATCHES "Clang")
   set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Wswitch -Wshadow -Wunused-parameter -Wmissing-prototypes -Wmissing-declarations -Wformat -Wformat-security -Wfloat-conversion -Wc99-extensions -Wc11-extensions")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11 -Wall -Wextra -Wswitch -Wshadow -Wunused-parameter -Wmissing-declarations -Wformat -Wformat-security -Wfloat-conversion")
 endif()
 
 # Tell Intel compiler to do arithmetic accurately.  This is needed to
@@ -37,8 +41,10 @@ endif()
 if (CMAKE_C_COMPILER_ID STREQUAL "Intel")
   if (MSVC)
     set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /fp:precise")
+    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Qstd=c++11")
   else ()
     set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fp-model precise")
+    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
   endif ()
 endif ()
 
@@ -57,9 +63,9 @@ colormsg(_HIBLUE_ "Configuring PROJ:")
 #PROJ version information
 #################################################################################
 include(ProjVersion)
-proj_version(MAJOR 5 MINOR 0 PATCH 0)
+proj_version(MAJOR 5 MINOR 2 PATCH 0)
 set(PROJ_API_VERSION "14")
-set(PROJ_BUILD_VERSION "14.0.1")
+set(PROJ_BUILD_VERSION "14.0.2")
 
 #################################################################################
 # Build features and variants
@@ -124,7 +130,6 @@ endif ()
 option(PROJ_TESTS "Enable build of collection of PROJ tests" ON)
 boost_report_value(PROJ_TESTS)
 if(PROJ_TESTS)
-    include(CTest)
     enable_testing()
 endif(PROJ_TESTS)
 include(ProjTest)
@@ -159,5 +164,6 @@ add_subdirectory(nad)
 add_subdirectory(src)
 add_subdirectory(man)
 add_subdirectory(cmake)
-add_subdirectory(test)
-
+if(PROJ_TESTS)
+  add_subdirectory(test)
+endif(PROJ_TESTS)

CONTRIBUTING.md

@@ -68,18 +68,18 @@ Note that not all feature requests are accepted.
 ## Write documentation
 
 PROJ.4 is in dire need of better documentation. Any contributions of documentation
-are greatly appreciated. The PROJ.4 documentation is available on [proj4.org](ttp://proj4.org).
+are greatly appreciated. The PROJ.4 documentation is available on [proj4.org](https://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.
+[Mercator projection](https://proj4.org/projections/merc.html) as a template.
 
 
 ## Code contributions
 
-See [Code Contributions](http://proj4.org/development/for_proj_contributors.html)
+See [Code Contributions](https://proj4.org/development/for_proj_contributors.html)
 
 #### Legalese
 Committers are the front line gatekeepers to keep the code base clear of improperly contributed code.
@@ -125,7 +125,7 @@ improperly contributing code to the source repository:
 
 ## Additional Resources
 
-* [General GitHub documentation](http://help.github.com/)
+* [General GitHub documentation](https://help.github.com/)
 * [GitHub pull request documentation](https://help.github.com/articles/about-pull-requests/)
 
 ## Acknowledgements

Dockerfile

@@ -1,24 +1,18 @@
 ##
 # osgeo/proj.4
 
-FROM ubuntu:xenial
+FROM ubuntu:18.04
 
 MAINTAINER Howard Butler <howard@hobu.co>
 
 
 # Setup build env
 RUN mkdir /build
-RUN apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 16126D3A3E5C1192    \
-    && apt-get update \
+RUN apt-get update -y \
     && apt-get install -y --fix-missing --no-install-recommends \
             software-properties-common build-essential ca-certificates \
-            git make cmake wget unzip libtool automake python-pip \
-            libpython-dev libjpeg-dev zlib1g-dev \
-            python-dev python-pip g++ doxygen dvipng \
-            cmake libjpeg8-dev zlib1g-dev texlive-latex-base \
-            texlive-latex-extra git \
-            graphviz python-matplotlib \
-            python-setuptools imagemagick \
+            git make cmake wget unzip libtool automake \
+            zlib1g-dev \
     && apt-get remove --purge -y $BUILD_PACKAGES  && rm -rf /var/lib/apt/lists/*
 
 
@@ -35,9 +29,6 @@ RUN mkdir /vdatum \
     && wget http://download.osgeo.org/proj/vdatum/egm08_25/egm08_25.gtx && mv egm08_25.gtx /usr/share/proj \
     && rm -rf /vdatum
 
-RUN pip install Sphinx breathe \
-    sphinx_bootstrap_theme awscli sphinxcontrib-bibtex \
-    sphinx_rtd_theme
 
 RUN git clone https://github.com/OSGeo/proj.4.git \
     && cd proj.4 \
@@ -45,7 +36,5 @@ RUN git clone https://github.com/OSGeo/proj.4.git \
     && ./configure --prefix=/usr \
     && make \
     && make install \
-    && cd /proj.4/docs \
-    && make html \
     && rm -rf /proj.4
 

HOWTO-RELEASE

@@ -1,24 +1,37 @@
-	Preparing a PROJ.4 Release
-	==========================
+Preparing a PROJ Release
+===============================================================================
 
-1) Update the version number in configure.ac (in AC_INIT()).
+Preparing a PROJ release is a three-step process. Before the actual release is
+published we want to issue one or more release candidates to ensure that the
+code is in fact ready to be released. That is step one. Step two starts when a
+release candidate has been selected for promotion to final release. Step three
+updates version numbers in the master branch to avoid confusion between
+released code and code still in development.
 
-   1a) Update the version number in PROJ_BUILD_VERSION in CMakeLists.txt
-   1b) Update the version number in doc/source/conf.py
-   1c) Update version numbers in man pages in man/man1/ and man/man3/
+The three phases are described below.
 
-2) Update the version number in proj_api.h (#define PJ_VERSION).
+1 Release candidate
+===============================================================================
 
-   2a) Update PROJ_VERSION_MAJOR, PROJ_VERSION_MINOR and PROJ_VERSION_PATCH
-       in src/proj.h
+At least one release candidate is necessary before the final release is
+published. In case more than one release candidate is needed most steps below
+can be skipped depending on what prompted the release candidate 1+n. Steps 1.6
+and 1.7 are mandatory for all release candidates, otherwise it will in most
+cases only be necessary to update the NEWS section (1.3).
 
-3) Update the version number, and date in src/pj_release.c.
+Release candidates should be released about a week before the final release is
+scheduled. When preparing major version releases it may be wise to issue the
+release candidate earlier than that.
 
-4) Update the version number in the -version-info definition in
-   src/Makefile.am.  It consists of "current:revision:age".
+When a release candidate has not prompted any request for changes in 48 hours,
+a motion for promotion to final release should be issued on the PROJ mailing
+list. The PROJ PSC guidelines describes the rules for passing a motion.
 
-   4a) Increment PROJ_BUILD_VERSION in CMakeLists.txt to follow
-       libtool versioning
+1.1 Update ABI version numbers:
+-------------------------------------------------------------------------------
+
+Determine the ABI version number. It consists of "current:revision:age". Follow
+the steps below to determine the next ABI version number:
 
    - If the library source code has changed at all since the last update,
      then increment revision (c:r:a becomes c:r+1:a).
@@ -32,47 +45,194 @@
    - If any interfaces have been removed since the last public release, then
      set age to 0.
 
-4.5) Run "autogen.sh" (hopefully on the same machine it was last run on)
+Update the following files with the new ABI version number:
 
-5) Update man pages:
+    - `src/Makefile.am`     Update -version-info
+    - `CMakelists.txt`:     Update PROJ_BUILD_VERSION (cur:rev:age) and
+                            PROJ_API_VERSION (current)
 
-    ./scripts/update_man.sh
+*Commit the changes to master.*
 
-   The script builds man pages from Sphinx docs, copies them to man/ and commits
-   them to git.
 
-6) Add a note to the ChangeLog that a new release is being issued, and what
-   the release number is.
+1.2 Update man pages
+-------------------------------------------------------------------------------
 
-7) Update NEWS file with summary of release changes.
+Man pages are (mostly) automatically generated from the Sphinx docs. The pages
+in man/man3/ was manually updated in 1.1. Here we update the pages in
+man/man1/. Follow these steps:
 
-8) Update the year in CITATION
+    - Update version number and date in `man/man3/pj_init.3` and
+      `man/man3/geodesic.3`
+    - Temporarily update version in `docs/source/conf.py`
+    - run `script/update_man.sh`
+    - Revert version number in `docs/source/conf.py`
 
-9) If this is a major release, prepare a branch.
+The `update_man.sh` script builds the man pages and commits the update man pages
+to master.
 
-   git checkout -b 5.0
 
-10) Tag the release
+1.3 Write release notes
+-------------------------------------------------------------------------------
 
-   git tag 5.0.0
+Update `NEWS` with descriptions of the changes since the last release.
+Hopefully issues and pull requests that go into the new release have been
+properly tagged with the milestone for the current release.
 
-11) Do a "make dist-all" in the proj root directory.  After some grinding
-   this should result in files like proj-4.4.3.tar.gz and proj-4.4.3.zip
-   being created.  These are full source distributions.
+End the section by thanking the authors that contributed to the release. Get a
+sorted list of contributors in descending order of activity:
 
-12) Put these in the proj ftp area on /osgeo/download/proj on
-   download.osgeo.org.  This can be done via scp using a command like the
-   following.
+```
+git shortlog -sn x.y.z..HEAD | tac | awk '{print $2 " " $3}'
+```
 
-  scp proj-4.4.3.{tar.gz,zip} warmerdam@download.osgeo.org:/osgeo/download/proj
+where `x.y.z` is the tag of the previous release. You may need to edit the list
+slightly since not all authors has properly configured their names in git.
 
-13) Announce the new release on the PROJ.4 and MetaCRS mailing lists.
+*Commit the changes to master.*
 
-14) Issue a new release report on GitHub:
 
-   https://github.com/OSGeo/proj.4/releases/new
+1.4 Update `CITATION`
+-------------------------------------------------------------------------------
 
-NOTES:
+If needed, update the year in `CITATION` and `docs/source/about.rst`.
 
- o Information about preparing binary releases, and RPMs should be formalized.
- o A "beta" release step should likely be incorporated.
+*Commit the changes to master.*
+
+
+1.5 Create maintenance branch
+-------------------------------------------------------------------------------
+
+*Skip this step if you are preparing a patch release or RC2 and later.*
+
+Create the branch:
+
+```
+git branch x.y
+```
+
+where `x` is the major version number and `y` is the minor version number. Bug
+fixes found in the release candidates should be pushed to master and
+subsequently cherry-picked to the maintenance branch.
+
+*Push branch upstream.*
+
+
+1.6 Prepare and upload archives
+-------------------------------------------------------------------------------
+
+Run autoconf and configure the build:
+
+```
+./autogen.sh
+mkdir build
+cd build
+../configure
+make dist
+```
+
+Rename the archives and generate MD5 sum files:
+
+```
+mv proj-x.y.z.tar.gz proj-x.y.zRCn.tar.gz
+mv proj-x.y.z.zip proj-x.y.zRCn.zip
+md5 proj-x.y.zRCn.tar.gz > proj-x.y.zRCn.tar.gz.md5
+md5 proj-x.y.zRCn.zip > proj-x.y.zRCn.zip.md5
+```
+
+Upload to the OSGeo download server:
+
+```
+scp proj-x.y.zRCn.* warmerdam@download.osgeo.org:/osgeo/download/proj
+```
+
+Adjust version numbers and usernames accordingly.
+
+
+1.7 Announce the release candidate
+-------------------------------------------------------------------------------
+
+Announce the release candidate on the PROJ mailing list.
+
+
+1.8 Promotion to final release
+-------------------------------------------------------------------------------
+
+When you are confident that the latest release candidate is ready for promotion
+to final release a motion for promotion should be issued on the PROJ mailing
+list. Allow for a minimum of 48 hours for voting time.
+
+
+2 Final release
+===============================================================================
+
+Barring a successful promotion process we can proceed with the final release.
+
+2.1 Prepare and upload archives
+-------------------------------------------------------------------------------
+
+See step 1.6 above. Do not rename the archives with RC postfixes.
+
+2.2 Update website
+------------------------------------------------------------------------------
+
+  - Add the release notes from `NEWS` to `docs/source/news.rst`
+  - Update download links in `docs/source/download.rst`
+  - Update `$TRAVIS_BRANCH` in `travis\after_success.sh` to new maintenance
+    branch.
+
+*Commit the changes to master and cherry-pick into maintenance branch.*
+
+When pushed upstream the website will be update to the current version.
+
+2.3 Tag the release
+-------------------------------------------------------------------------------
+
+Tag the release with:
+
+```
+git tag -a -m "Create tag x.y.z" x.y.z
+git push --tags
+```
+
+2.4 Prepare the release on GitHub
+-------------------------------------------------------------------------------
+
+When the new tag is pushed upstream GitHub picks up that a new release has been
+issued. Update the new release on https://github.com/OSGeo/proj.4/releases with
+the release notes from `NEWS` and add the prepared source distribution archives
+to the release (otherwise GitHub will just package the entire repository - we
+don't want that).
+
+
+2.5 Announce the new release
+-------------------------------------------------------------------------------
+
+The release should be announced on PROJ and MetaCRS mailing lists. Additionally
+the release announcement should be sent to news_item@osgeo.org which will add
+the announcement to osgeo.org and other OSGeo communication channels.
+
+Make some noise on Twitter and other relevant social media.
+
+
+3 Post final release
+===============================================================================
+
+3.1 Update version numbers
+-------------------------------------------------------------------------------
+
+*Skip this step if you are preparing a patch release.*
+
+PROJ uses [semantic versioning](http://semver.org/). Depending on the changes
+in the release will be either a major, minor or patch release. Update the
+version numbers in the files.
+
+  - configure.ac:         Update the version number in AC_INIT().
+  - src/proj.h:           Update PROJ_VERSION_MAJOR, PROJ_VERSION_MINOR and
+                          PROJ_VERSION_PATCH.
+  - src/proj_api.h:       Update PJ_VERSION.
+  - src/pj_release.c:     Update date to the scheduled release date.
+  - CMakelists.txt:       Update proj_version()
+  - doc/source/conf.py:   Update version number
+
+
+*Commit changes to master branch.*

NEWS

@@ -1,3 +1,78 @@
+5.2.0 Release Notes
+-------------------
+
+ UPDATES
+ -------
+
+ o Added support for deg, rad and grad in unitconvert (#1054)
+
+ o Assume +t_epoch as time input when not otherwise specified (#1065)
+
+ o Added inverse Lagrange projection (#1058)
+
+ o Added +multiplier option to vgridshift (#1072)
+
+ o Added Equal Earth projection (#1085)
+
+ o Added "require_grid" option to gie (#1088)
+
+ o Replace +transpose option of Helmert transform with +convention.
+   From now on the convention used should be explicitly written. An
+   error will be returned when using the +transpose option (#1091)
+
+ o Improved numerical precision of inverse spherical Mercator
+   projection (#1105)
+
+ o cct will now forward text after coordinate input to output
+   stream (#1111)
+
+
+ BUG FIXES
+ ------------
+
+ o Do not pivot over WGS84 when doing cs2cs-emulation with geocent (#1026)
+
+ o Do not scan past the end of the read data in pj_ctx_fgets (#1042)
+
+ o Make sure proj_errno_string() is available in DLL (#1050)
+
+ o Respect +to_meter setting when doing cs2cs-emulation (#1053)
+
+ o Fixed unit conversion factors for geod (#1075)
+
+ o Fixed test failures related to GCC 8 (#1084)
+
+ o Improved handling of +geoc flag (#1093)
+
+ o Calculate correct projection factors for Webmercator (#1095)
+
+ o cs2cs now always outputs degrees when transformed coordinates are
+   in angular units (#1112)
+
+
+ All bug fix numbers refer to issues or pull requests indexed at
+ https://github.com/OSGeo/proj.4/
+
+ THANKS TO
+ ------------
+
+ Version 5.2.0 is made possible by the following contributors:
+
+Søren Holm
+Mateusz Łoskot
+Jürnjakob Dugge
+Greg Minshall
+Aaron Puchert
+Vedran Stojnović
+Bojan Šavrič
+Charles Karney
+Mateusz Loskot
+Howard Butler
+Mike Toews
+Kurt Schwehr
+Even Rouault
+Kristian Evers
+
 5.1.0 Release Notes
 -------------------
 

README.md

@@ -1,8 +1,10 @@
 # PROJ
 
-[![Travis Status](https://travis-ci.org/OSGeo/proj.4.svg?branch=master)](https://travis-ci.org/OSGeo/proj.4)
+[![Travis Status](https://travis-ci.com/OSGeo/proj.4.svg?branch=master)](https://travis-ci.com/OSGeo/proj.4)
 [![AppVeyor Status](https://ci.appveyor.com/api/projects/status/584j49uguwoo5evi?svg=true)](https://ci.appveyor.com/project/OSGeo/proj-4)
 [![Coveralls Status](https://coveralls.io/repos/github/OSGeo/proj.4/badge.svg?branch=master)](https://coveralls.io/github/OSGeo/proj.4?branch=master)
+[![Gitter](https://badges.gitter.im/OSGeo/proj.4.svg)](https://gitter.im/OSGeo/proj.4)
+[![Mailing List](https://img.shields.io/badge/PROJ-mailing%20list-4eb899.svg)](http://lists.maptools.org/mailman/listinfo/proj)
 
 PROJ is a generic coordinate transformation software, that transforms
 coordinates from one coordinate reference system (CRS) to another.
@@ -10,7 +12,7 @@ This includes cartographic projections as well as geodetic transformations.
 
 For more information on the PROJ.4 project please see the web page at:
 
-http://proj4.org/
+https://proj4.org/
 
 The PROJ.4 mailing list can be found at:
 

appveyor.yml

@@ -1,78 +0,0 @@
-platform:
-- x64
-- x86
-
-environment:
-  matrix:
-
-# Does not work
-# VS 2008
-#  - BUILD_TYPE: cmake
-#    VS_VERSION: Visual Studio 9 2008
-
-# VS 2010
-  - BUILD_TYPE: cmake
-    VS_VERSION: Visual Studio 10
-
-# VS 2012
-  - BUILD_TYPE: cmake
-    VS_VERSION: Visual Studio 11
-
-# VS 2013
-  - BUILD_TYPE: cmake
-    VS_VERSION: Visual Studio 12
-
-# VS 2015
-  - BUILD_TYPE: cmake
-    VS_VERSION: Visual Studio 14
-    APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015
-
-# VS 2017
-  - BUILD_TYPE: cmake
-    VS_VERSION: Visual Studio 15
-    APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
-
-  - BUILD_TYPE: nmake
-
-shallow_clone: true
-
-build_script:
-  - echo build_script
-  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x86" call "%VS120COMNTOOLS%\..\..\VC\vcvarsall.bat"
-  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x64
-  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" call "%VS120COMNTOOLS%\..\..\VC\vcvarsall.bat" x86_amd64
-  - if "%BUILD_TYPE%" == "nmake" nmake /f makefile.vc
-  - if "%BUILD_TYPE%" == "nmake" nmake /f makefile.vc install-all
-  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" cd src
-  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" nmake /f makefile.vc multistresstest.exe
-# Disabled for now as it scales badly
-#  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" multistresstest.exe
-  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" cd ..
-  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" SET VS_FULL=%VS_VERSION% Win64
-  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" SET VS_FULL=%VS_VERSION%
-  - if "%BUILD_TYPE%" == "cmake" echo "%VS_FULL%"
-  - if "%BUILD_TYPE%" == "cmake" cmake -G "%VS_FULL%" . -DCMAKE_BUILD_TYPE=Release -DCMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE=../bin -DBUILD_LIBPROJ_SHARED=ON -DCMAKE_C_FLAGS="/WX"
-  - if "%BUILD_TYPE%" == "cmake" cmake --build . --config Release
-
-test_script:
-  - echo test_script
-  - if "%BUILD_TYPE%" == "cmake" set PROJ_LIB=C:\projects\proj-4\nad
-  - if "%BUILD_TYPE%" == "nmake" set PROJ_LIB=C:\PROJ\SHARE
-  - if "%BUILD_TYPE%" == "nmake" mkdir %PROJ_LIB%\tests
-  - if "%BUILD_TYPE%" == "nmake" copy nad\tests\*.* %PROJ_LIB%\tests
-  - cd %PROJ_LIB%
-  - curl -O http://download.osgeo.org/proj/proj-datumgrid-1.7.zip
-  - 7z e -aoa -y proj-datumgrid-1.7.zip
-  - dir
-  - cd ..
-  - dir
-  - cd bin
-  - echo "Contents of current directory:"
-  - dir
-  - echo "Contents of ..\test\gie:"
-  - dir ..\test\gie
-  - echo "Contents of PROJ_LIB " %PROJ_LIB%
-  - dir %PROJ_LIB%
-  - gie.exe ..\test\gie\*.gie ..\test\gigs\*.gie
-
-deploy: off

cmake/ProjConfig.cmake

@@ -5,7 +5,7 @@
 #
 # Distributed under the Boost Software License, Version 1.0.
 # (See accompanying file LICENSE_1_0.txt or copy at
-# http://www.boost.org/LICENSE_1_0.txt)
+# https://www.boost.org/LICENSE_1_0.txt)
 ################################################################################
 include (CheckIncludeFiles)
 include (CheckLibraryExists) 
@@ -34,7 +34,7 @@ set(PACKAGE_BUGREPORT "https://github.com/OSGeo/proj.4/issues")
 set(PACKAGE_NAME "PROJ")
 set(PACKAGE_STRING "PROJ ${${PROJECT_INTERN_NAME}_VERSION}")
 set(PACKAGE_TARNAME "proj")
-set(PACKAGE_URL "http://proj4.org")
+set(PACKAGE_URL "https://proj4.org")
 set(PACKAGE_VERSION "${${PROJECT_INTERN_NAME}_VERSION}")
 
 configure_file(cmake/proj_config.cmake.in src/proj_config.h)

cmake/ProjSystemInfo.cmake

@@ -7,7 +7,7 @@
 #
 # Distributed under the Boost Software License, Version 1.0.
 # (See accompanying file LICENSE_1_0.txt or copy at
-# http://www.boost.org/LICENSE_1_0.txt)
+# https://www.boost.org/LICENSE_1_0.txt)
 ################################################################################
 # The following variables are defined:
 #   PROJ_COMPILER_NAME - name of compiler toolset, follows Boost toolset naming.

cmake/ProjUtilities.cmake

@@ -9,7 +9,7 @@
 #
 # Distributed under the Boost Software License, Version 1.0.
 # See accompanying file LICENSE_1_0.txt or copy at
-#   http://www.boost.org/LICENSE_1_0.txt
+#   https://www.boost.org/LICENSE_1_0.txt
 ################################################################################
 # Macros in this module:
 #
@@ -355,7 +355,7 @@ endmacro()
 #
 # Scans the current directory and returns a list of subdirectories.
 # Author: Robert Fleming
-# Source: http://www.cmake.org/pipermail/cmake/2008-February/020114.html
+# Source: https://www.cmake.org/pipermail/cmake/2008-February/020114.html
 #
 # Third parameter is 1 if you want relative paths returned.
 # Usage: list_subdirectories(the_list_is_returned_here /path/to/project TRUE)

configure.ac

@@ -1,8 +1,8 @@
 dnl Process this file with autoconf to produce a configure script.
 
 AC_PREREQ(2.59)
-AC_INIT([PROJ], [5.1.0],
-        [https://github.com/OSGeo/proj.4/issues], proj, [http://proj4.org])
+AC_INIT([PROJ], [5.2.0],
+        [https://github.com/OSGeo/proj.4/issues], proj, [https://proj4.org])
 AC_CONFIG_MACRO_DIR([m4])
 AC_LANG(C)
 
@@ -10,17 +10,139 @@ AC_CONFIG_AUX_DIR([.])
 AM_INIT_AUTOMAKE
 AM_CONFIG_HEADER(src/proj_config.h)
 
-dnl Enable as much warnings as possible
-AX_CFLAGS_WARN_ALL(C_WFLAGS)
-AC_SUBST(C_WFLAGS,$C_WFLAGS)
-
 dnl Checks for programs.
 AC_PROG_CC
+AC_PROG_CXX
+AX_CXX_COMPILE_STDCXX_11([noext],[mandatory])
 AC_PROG_INSTALL
 AC_PROG_LN_S
 AC_PROG_MAKE_SET
 AM_PROG_LIBTOOL
 
+dnl Enable as much warnings as possible
+AX_CFLAGS_WARN_ALL(C_WFLAGS)
+AX_CXXFLAGS_WARN_ALL(CXX_WFLAGS)
+
+dnl For ICC: it needs -we10006 instead of -Werror to turn unknown options to errors
+dnl Some gcc/clang versions might succeed on this test, so also include -Werror in ERROR_ON_UNKNOWN_OPTIONS
+AX_CHECK_COMPILE_FLAG([-Werror -we10006],[ERROR_ON_UNKNOWN_OPTIONS="-Werror -we10006"],[ERROR_ON_UNKNOWN_OPTIONS="-Werror"])
+
+dnl A few ICC warnings to turn off
+dnl warning #188: enumerated type mixed with another type  (needed on libcsf)
+dnl warning #1684: conversion from pointer to same-sized integral type (potential portability problem)  (needed on frmts/mrf)
+dnl warning #2259: non-pointer conversion from "size_t={unsigned long}" to "int" may lose significant bits
+dnl warning #2304: non-explicit constructor with single argument may cause implicit type conversion
+dnl warning #3280: declaration hides member
+dnl remark #11074: Inlining inhibited by limit max-size
+dnl remark #11076: To get full report use -qopt-report=4 -qopt-report-phase ipo
+AX_CHECK_COMPILE_FLAG([-diag-disable 188,1684,2259,2304,3280,11074,11076],[C_WFLAGS="$C_WFLAGS -diag-disable 188,1684,2259,2304,3280,11074,11076" CXX_WFLAGS="$CXX_WFLAGS -diag-disable 188,1684,2259,2304,3280,11074,11076"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+AX_CHECK_COMPILE_FLAG([-Wextra],[C_WFLAGS="$C_WFLAGS -Wextra" CXX_WFLAGS="$CXX_WFLAGS -Wextra"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Winit-self],[C_WFLAGS="$C_WFLAGS -Winit-self" CXX_WFLAGS="$CXX_WFLAGS -Winit-self"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wunused-parameter], [C_WFLAGS="$C_WFLAGS -Wunused-parameter" CXX_WFLAGS="$CXX_WFLAGS -Wunused-parameter" NO_UNUSED_PARAMETER_FLAG="-Wno-unused-parameter"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wmissing-prototypes], [C_WFLAGS="$C_WFLAGS -Wmissing-prototypes"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wmissing-declarations], [C_WFLAGS="$C_WFLAGS -Wmissing-declarations"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wformat], [C_WFLAGS="$C_WFLAGS -Wformat" CXX_WFLAGS="$CXX_WFLAGS -Wformat"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wformat -Werror=format-security -Wno-format-nonliteral], [C_WFLAGS="$C_WFLAGS -Werror=format-security -Wno-format-nonliteral" CXX_WFLAGS="$CXX_WFLAGS -Werror=format-security -Wno-format-nonliteral"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wshorten-64-to-32], [C_WFLAGS="$C_WFLAGS -Wshorten-64-to-32" CXX_WFLAGS="$CXX_WFLAGS -Wshorten-64-to-32"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wlogical-op], [C_WFLAGS="$C_WFLAGS -Wlogical-op" CXX_WFLAGS="$CXX_WFLAGS -Wlogical-op" NO_LOGICAL_OP_FLAG="-Wno-logical-op"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wshadow], [C_WFLAGS="$C_WFLAGS -Wshadow" CXX_WFLAGS="$CXX_WFLAGS -Wshadow"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl Error out on things that will fail with MSVC
+AX_CHECK_COMPILE_FLAG([-Werror=vla], [C_WFLAGS="$C_WFLAGS -Werror=vla" CXX_WFLAGS="$CXX_WFLAGS -Werror=vla"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Werror=declaration-after-statement], [C_WFLAGS="$C_WFLAGS -Wdeclaration-after-statement"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl -Wclobbered is not reliable on most gcc versions
+dnl AX_CHECK_COMPILE_FLAG([-Wno-clobbered], [C_WFLAGS="$C_WFLAGS -Wno-clobbered" CXX_WFLAGS="$CXX_WFLAGS -Wno-clobbered"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl Warn when macros __TIME__, __DATE__ or __TIMESTAMP__ are encountered as they might prevent bit-wise-identical reproducible compilations. 
+AX_CHECK_COMPILE_FLAG([-Wdate-time], [C_WFLAGS="$C_WFLAGS -Wdate-time" CXX_WFLAGS="$CXX_WFLAGS -Wdate-time"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl GCC 6 warnings
+AX_CHECK_COMPILE_FLAG([-Wnull-dereference], [C_WFLAGS="$C_WFLAGS -Wnull-dereference" CXX_WFLAGS="$CXX_WFLAGS -Wnull-dereference"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wduplicated-cond], [C_WFLAGS="$C_WFLAGS -Wduplicated-cond" CXX_WFLAGS="$CXX_WFLAGS -Wduplicated-cond"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl GCC 7 warnings
+dnl Do not enable yet. Causes warning in alg/gdalthinplate.cpp due to armadillo templates
+dnl AX_CHECK_COMPILE_FLAG([-Wduplicated-branches], [C_WFLAGS="$C_WFLAGS -Wduplicated-branches" CXX_WFLAGS="$CXX_WFLAGS -Wduplicated-branches"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl GCC 8 warnings
+AC_LANG_PUSH([C++])
+AX_CHECK_COMPILE_FLAG([-Wextra-semi], [CXX_WFLAGS="$CXX_WFLAGS -Wextra-semi"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AC_LANG_POP([C++])
+
+AX_CHECK_COMPILE_FLAG([-Wno-sign-compare], [NO_SIGN_COMPARE="-Wno-sign-compare"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl clang >= 3.9
+AX_CHECK_COMPILE_FLAG([-Wcomma], [C_WFLAGS="$C_WFLAGS -Wcomma" CXX_WFLAGS="$CXX_WFLAGS -Wcomma"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl clang and gcc 5
+AX_CHECK_COMPILE_FLAG([-Wfloat-conversion], [C_WFLAGS="$C_WFLAGS -Wfloat-conversion" CXX_WFLAGS="$CXX_WFLAGS -Wfloat-conversion"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl clang >= 3.2
+AX_CHECK_COMPILE_FLAG([-Wdocumentation -Wno-documentation-deprecated-sync], [C_WFLAGS="$C_WFLAGS -Wdocumentation -Wno-documentation-deprecated-sync" CXX_WFLAGS="$CXX_WFLAGS -Wdocumentation -Wno-documentation-deprecated-sync"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl gnu89 is a reasonable target to get MSVC compatibility.
+dnl but only apply it with gcc, since clang will throw a lot of warnings
+SAVED_CFLAGS=$CFLAGS
+CFLAGS="$CFLAGS $ERROR_ON_UNKNOWN_OPTIONS -std=gnu89"
+AC_MSG_CHECKING([if -std=gnu89 can be enabled])
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
+  [[#if defined(__clang__) || !defined(__GNUC__)
+    #error "not gcc"
+    #endif]])],
+  [C_WFLAGS="$C_WFLAGS -std=gnu89"]
+  [AC_MSG_RESULT([yes])],
+  [AC_MSG_RESULT([no])])
+CFLAGS=$SAVED_CFLAGS
+
+dnl C++ specific stuff
+
+AC_LANG_PUSH([C++])
+AX_CHECK_COMPILE_FLAG([-Wunused-private-field], [CXX_WFLAGS="$CXX_WFLAGS -Wunused-private-field"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wmissing-prototypes], [CXX_WFLAGS="$CXX_WFLAGS -Wmissing-prototypes"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wmissing-declarations], [CXX_WFLAGS="$CXX_WFLAGS -Wmissing-declarations"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wnon-virtual-dtor], [CXX_WFLAGS="$CXX_WFLAGS -Wnon-virtual-dtor" NO_NON_VIRTUAL_DTOR_FLAG="-Wno-non-virtual-dtor"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Wold-style-cast], [WARN_OLD_STYLE_CAST="-Wold-style-cast"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+AX_CHECK_COMPILE_FLAG([-Weffc++], [WARN_EFFCPLUSPLUS="-Weffc++"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl g++-4.8 complain a bit too much with -Weffc++
+if test "$WARN_EFFCPLUSPLUS" != ""; then
+    SAVED_CXXFLAGS=$CXXFLAGS
+    CXXFLAGS="$CXXFLAGS $WARN_EFFCPLUSPLUS -Werror"
+    AC_MSG_CHECKING([if -Weffc++ should be enabled])
+    AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
+    [[
+    class Base {};
+    class A: public Base {};
+    ]])],
+    [AC_MSG_RESULT([yes])],
+    [WARN_EFFCPLUSPLUS=""]
+    [AC_MSG_RESULT([no])])
+    CXXFLAGS="$SAVED_CXXFLAGS"
+    CXX_WFLAGS="$CXX_WFLAGS $WARN_EFFCPLUSPLUS"
+fi
+
+dnl Clang enables -Woverloaded-virtual if -Wall is defined, but not GCC
+AX_CHECK_COMPILE_FLAG([-Woverloaded-virtual], [CXX_WFLAGS="$CXX_WFLAGS -Woverloaded-virtual"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+dnl Forbid use of 'or', 'and', ... alias operators
+AX_CHECK_COMPILE_FLAG([-fno-operator-names], [CXX_WFLAGS="$CXX_WFLAGS -fno-operator-names"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+
+HAVE_GCC_WARNING_ZERO_AS_NULL_POINTER_CONSTANT=no
+AX_CHECK_COMPILE_FLAG([-Wzero-as-null-pointer-constant], [CXX_WFLAGS="$CXX_WFLAGS -Wzero-as-null-pointer-constant" HAVE_GCC_WARNING_ZERO_AS_NULL_POINTER_CONSTANT=yes NO_ZERO_AS_NULL_POINTER_CONSTANT_FLAG="-Wno-zero-as-null-pointer-constant"],,[$ERROR_ON_UNKNOWN_OPTIONS])
+if test "$HAVE_GCC_WARNING_ZERO_AS_NULL_POINTER_CONSTANT" = "yes"; then
+AC_DEFINE_UNQUOTED(HAVE_GCC_WARNING_ZERO_AS_NULL_POINTER_CONSTANT, 1,
+          [Define to 1 if the compiler supports -Wzero-as-null-pointer-constant])
+fi
+
+AC_LANG_POP([C++])
+
+AC_SUBST(C_WFLAGS,$C_WFLAGS)
+AC_SUBST(CXX_WFLAGS,$CXX_WFLAGS)
+AC_SUBST(NO_ZERO_AS_NULL_POINTER_CONSTANT_FLAG,$NO_ZERO_AS_NULL_POINTER_CONSTANT_FLAG)
+
+
 dnl Checks for libraries.
 save_CFLAGS="$CFLAGS"
 CFLAGS=`echo "$CFLAGS" | sed "s/-Werror/ /"`
@@ -142,7 +264,12 @@ AC_SUBST(MUTEX_SETTING,$MUTEX_SETTING)
 AC_SUBST(THREAD_LIB,$THREAD_LIB)
 
 AC_CONFIG_FILES([Makefile cmake/Makefile src/Makefile
-                 test/Makefile test/gie/Makefile test/gigs/Makefile
+                 test/Makefile test/gie/Makefile test/gigs/Makefile test/unit/Makefile
+                 test/googletest/Makefile test/googletest/include/Makefile
+                 test/googletest/include/gtest/Makefile
+                 test/googletest/include/gtest/internal/Makefile
+                 test/googletest/include/gtest/internal/custom/Makefile
+                 test/googletest/src/Makefile
                  man/Makefile man/man1/Makefile man/man3/Makefile nad/Makefile
                  jniwrap/Makefile jniwrap/org.osgeo.proj/Makefile jniwrap/org.osgeo.proj/org/Makefile jniwrap/org.osgeo.proj/org/proj4/Makefile])
 AC_CONFIG_FILES([nad/install], [chmod +x nad/install])

disabled_workflows/.travis.yml

@@ -10,8 +10,9 @@ matrix:
   include:
 
     - os: linux
+      dist: trusty
       compiler: gcc
-      language: c
+      language: cpp
       sudo: required
       services:
         - docker
@@ -19,8 +20,9 @@ matrix:
         - BUILD_NAME=linux_gcc
         - DETAILS="linux, gcc"
     - os: linux
+      dist: trusty
       compiler: clang
-      language: c
+      language: cpp
       sudo: required
       services:
         - docker
@@ -28,13 +30,14 @@ matrix:
         - BUILD_NAME=linux_clang
         - DETAILS="linux, clang"
     - os: osx
-      language: c
+      language: cpp
       env:
         - BUILD_NAME=osx
         - DETAILS="osx"
     - os: linux
+      dist: trusty
       compiler: gcc
-      language: c
+      language: cpp
       sudo: required
       env:
         - BUILD_NAME=mingw32
@@ -42,7 +45,7 @@ matrix:
 
     - os: linux
       compiler: gcc
-      language: c
+      language: cpp
       dist: trusty
       env:
         - BUILD_NAME=csa

disabled_workflows/appveyor.yml

@@ -0,0 +1,81 @@
+platform:
+- x64
+- x86
+
+environment:
+  matrix:
+
+# VS 2015
+  - BUILD_TYPE: cmake
+    VS_VERSION: Visual Studio 14
+    APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015
+
+# VS 2017
+  - BUILD_TYPE: cmake
+    VS_VERSION: Visual Studio 15
+    APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
+
+  - BUILD_TYPE: nmake
+
+shallow_clone: true
+
+build_script:
+  - echo build_script
+  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x86" call "%VS120COMNTOOLS%\..\..\VC\vcvarsall.bat"
+  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x64
+  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" call "%VS120COMNTOOLS%\..\..\VC\vcvarsall.bat" x86_amd64
+  - if "%BUILD_TYPE%" == "nmake" nmake /f makefile.vc
+  - if "%BUILD_TYPE%" == "nmake" nmake /f makefile.vc install-all
+  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" cd src
+  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" nmake /f makefile.vc multistresstest.exe
+# Disabled for now as it scales badly
+#  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" multistresstest.exe
+  - if "%BUILD_TYPE%" == "nmake" if "%platform%" == "x64" cd ..
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" SET VS_FULL=%VS_VERSION% Win64
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" SET VS_FULL=%VS_VERSION%
+  - if "%BUILD_TYPE%" == "cmake" echo "%VS_FULL%"
+#
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" mkdir build_dll
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" cd build_dll
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" cmake -G "%VS_FULL%" .. -DCMAKE_BUILD_TYPE=Release -DBUILD_LIBPROJ_SHARED=ON -DCMAKE_C_FLAGS="/WX"
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" cmake --build . --config Release
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" cd ..
+#
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" mkdir build_static
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" cd build_static
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" cmake -G "%VS_FULL%" .. -DCMAKE_BUILD_TYPE=Release -DBUILD_LIBPROJ_SHARED=OFF -DCMAKE_C_FLAGS="/WX"
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" cmake --build . --config Release
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" cd ..
+
+test_script:
+  - echo test_script
+  - if "%BUILD_TYPE%" == "cmake" set PROJ_LIB=C:\projects\proj-4\nad
+  - if "%BUILD_TYPE%" == "nmake" set PROJ_LIB=C:\PROJ\SHARE
+  - if "%BUILD_TYPE%" == "nmake" mkdir %PROJ_LIB%\tests
+  - if "%BUILD_TYPE%" == "nmake" copy nad\tests\*.* %PROJ_LIB%\tests
+  - set CURDIR=%CD%
+  - cd %PROJ_LIB%
+  - curl -O http://download.osgeo.org/proj/proj-datumgrid-1.7.zip
+  - 7z e -aoa -y proj-datumgrid-1.7.zip
+  - dir
+  - cd ..
+  - if "%BUILD_TYPE%" == "nmake" dir
+  - if "%BUILD_TYPE%" == "nmake" cd bin
+  - if "%BUILD_TYPE%" == "nmake" echo "Contents of current directory:"
+  - if "%BUILD_TYPE%" == "nmake" dir
+  - if "%BUILD_TYPE%" == "nmake" echo "Contents of ..\test\gie:"
+  - if "%BUILD_TYPE%" == "nmake" dir ..\test\gie
+  - if "%BUILD_TYPE%" == "nmake" echo "Contents of PROJ_LIB " %PROJ_LIB%
+  - if "%BUILD_TYPE%" == "nmake" dir %PROJ_LIB%
+  - if "%BUILD_TYPE%" == "nmake" gie.exe ..\test\gie\*.gie ..\test\gigs\*.gie
+  - cd %CURDIR%
+#
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" cd build_dll
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" ctest -C Release
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x64" cd ..
+#
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" cd build_static
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" ctest -C Release
+  - if "%BUILD_TYPE%" == "cmake" if "%platform%" == "x86" cd ..
+
+deploy: off

docs/docbuild/Dockerfile

@@ -0,0 +1,13 @@
+FROM ubuntu:18.04
+
+RUN apt-get -y update && DEBIAN_FRONTEND=noninteractive apt-get install -y \
+    python-dev python-pip g++ doxygen dvipng latexmk \
+    cmake libjpeg8-dev zlib1g-dev texlive-latex-base \
+    texlive-latex-extra git \
+    graphviz python-matplotlib
+
+RUN pip install Sphinx breathe \
+    sphinx_bootstrap_theme awscli sphinxcontrib-bibtex \
+    sphinx_rtd_theme
+
+

docs/environment.yml

@@ -0,0 +1,15 @@
+name: proj
+channels:
+  - conda-forge
+dependencies:
+  - descartes
+  - geojson
+  - matplotlib
+  - shapely < 1.8
+  - pip
+  - pip:
+    - Jinja2 < 3.1
+    - pybtex
+    - sphinx < 3
+    - sphinx-rtd-theme < 1.0
+    - sphinxcontrib-bibtex

docs/plot/figure_caption.sh

@@ -0,0 +1,2 @@
+
+python3 figure_captions.py plotdefs.json ../source/operations/projections/

docs/plot/figure_captions.py

@@ -0,0 +1,79 @@
+import sys
+import os
+import json
+import pathlib
+import re
+
+
+def update_caption(image_filename, proj_string, doc_directory,
+                   doc_extension='rst'):
+    """
+    Update the figure caption with a proj-string
+
+    This function assumes that within the "doc_directory" there is a file with
+    the same basename as the "image_filename" (e.g. for the image "aea.png",
+    the function will assume that there is a documentation file "aea.rst").
+    Within that documentation file, the function will try to find a section
+    starting with "..figure:: ./images/" and ending with a line like
+    "   proj-string:...".
+    This line will be replaced with something like
+    "   proj-string: ``+proj=aea``"
+
+    :param filename: The name of the image that's used in the documentation
+    :param proj_string: The proj-string that was used to generate the image
+    :param doc_directory: The directory containing the projection documentation .rst files
+    :return:
+    """
+
+    basename, image_extension = os.path.splitext(image_filename)
+    doc_path = os.path.join(doc_directory, basename + os.extsep + doc_extension)
+    p = pathlib.Path(doc_path)
+
+    if p.is_file():
+        replacement_string = r'\1   proj-string: ``{}``\2'.format(proj_string)
+        new_doc_content = re.sub(
+            r'(\.\. figure\:\: \.\/images\/.*?^)[ \t]*proj-string.*?($)',
+            replacement_string,
+            p.read_text(),
+            flags=re.MULTILINE + re.DOTALL)
+        p.write_text(new_doc_content)
+
+    else:
+        print("File {} not found.".format(doc_path))
+
+
+def main():
+    """
+    Main function of caption replacement script.
+
+    Parses json-file with plot setups and runs the caption replacement
+    for each plot setup.
+    """
+
+    if os.path.exists(sys.argv[1]):
+        # first argument is the JSON plot definition setup file
+        with open(sys.argv[1]) as plotsetup:
+            plotdefs = json.load(plotsetup)
+    else:
+        raise ValueError('No plot definition file entered')
+
+    plots = []
+    # second argument is the projections documentation directory
+    outdir = sys.argv[2]
+
+    for i, plotdef in enumerate(plotdefs):
+        if plots != [] and plotdef['name'] not in plots:
+            continue
+
+        print(i, plotdef['projstring'])
+        if 'skip' in plotdef.keys():
+            print('skipping')
+            continue
+
+        update_caption(plotdef['name'],
+                       plotdef['projstring'],
+                       outdir)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

docs/plot/greyscale.sh

@@ -1,7 +1,3 @@
-
-
-for f in $(ls *.png)
-do
-
-    convert $f -fx '(r+g+b)/3' -colorspace Gray $f
-done;
+# Use Imagemagick to convert all images to grayscale,
+# printing progress information
+mogrify -monitor -colorspace Gray *.png

docs/plot/plot.py

@@ -1,5 +1,6 @@
+#!/usr/bin/env python3
 '''
-Plot map data in different projections supported by PROJ.4
+Plot map data in different projections supported by PROJ.
 
 Call with:
 
@@ -41,28 +42,31 @@ or "line". The rest of the inputs are fairly free form.
 Change PROJ to path on your local system before running the script.
 '''
 
-from __future__ import print_function
-from __future__ import division
-
+import argparse
 import os
-import os.path
+import shutil
 import sys
 import json
 import subprocess
 import functools
+from pathlib import Path
 
+import geojson
 import numpy as np
 import matplotlib.pyplot as plt
-from matplotlib.patches import Polygon
-import fiona
-from shapely.geometry import Polygon
-from shapely.geometry import MultiPolygon
+from shapely.geometry import MultiPolygon, Polygon, box as Box
 from shapely.geometry import shape
 from shapely.ops import transform
 from descartes import PolygonPatch
 
-PROJ = '../../src/proj'
-PROJ_LIB = '../../nad'
+PROJ_COMMAND = os.environ.get('PROJ_EXE', '../../src/proj')
+if not os.path.exists(PROJ_COMMAND):
+    PROJ = shutil.which('proj')
+    if PROJ is None:
+        raise ValueError("specify PROJ_EXE or modify PATH to find proj")
+else:
+    PROJ = PROJ_COMMAND
+PROJ_LIB = os.environ.get('PROJ_LIB', '../../nad')
 
 LINE_LOW = 'data/coastline.geojson'
 LINE_MED = 'data/coastline50.geojson'
@@ -85,7 +89,7 @@ def interp_coords(coords, tol):
 
     The function tries to densify a list of coordinates based on a simple measure.
     If two adjacent points in the input coordinate list are further away from each
-    other than the specified tolerance, the list will be densied between those two
+    other than the specified tolerance, the list will be densified between those two
     points. Roughly speaking, a point will be inserted every `tol` between the
     points.
 
@@ -118,7 +122,7 @@ def interp_coords(coords, tol):
         xy.append((x[offset:i], y[offset:i]))
 
         # Interpolate between points above tolerance.
-        n = np.ceil(dsts[i] / tol)
+        n = int(np.ceil(dsts[i] / tol))
         x1 = np.linspace(x[i], x[i + 1], n + 1)
         y1 = np.linspace(y[i], y[i + 1], n + 1)
         xy.append((x1[:-1], y1[:-1]))
@@ -157,8 +161,14 @@ def project(coordinates, proj_string, in_radians=False):
     args = [PROJ, '-b']
     args.extend(proj_string.split(' '))
 
-    proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
-                            env={'PROJ_LIB': os.path.abspath(PROJ_LIB)})
+    try:
+        proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                env={'PROJ_LIB': os.path.abspath(PROJ_LIB)})
+    except FileNotFoundError as e:
+        print("'proj' binary not found, set the PROJ_EXE environment variable "
+              "to point to your local 'proj' binary --%s--" % e)
+        exit(1)
+
     stdout, _ = proc.communicate(coordinates.tobytes(order='C'))
 
     out = np.frombuffer(stdout, dtype=np.double)
@@ -217,7 +227,10 @@ def resample_polygon(polygon):
     '''
     Use interp_coords() to resample (multi)polygons.
     '''
-    xy = polygon.exterior.coords.xy
+    try:
+        xy = polygon.exterior.coords.xy
+    except AttributeError: #no xy's
+        return polygon
     ext = interp_coords(xy, 2)
     # interiors
     rings = []
@@ -226,27 +239,46 @@ def resample_polygon(polygon):
     return Polygon(ext, rings)
 
 
+def plot_with_interruptions(axes, x, y, delta_cut=1e100, **kwargs):
+    """
+    Plot x/y with proper splitting for interrupted projections.
+    """
+    _x = np.atleast_1d(x)
+    _y = np.atleast_1d(y)
+
+    dx = np.nan_to_num(_x[1: ]) - np.nan_to_num(_x[0: -1])
+    dy = np.nan_to_num(_y[1: ]) - np.nan_to_num(_y[0: -1])
+    split, = ((np.abs(dx) > delta_cut) | (np.abs(dy) > delta_cut)).nonzero()
+    split = np.append(split, _x.size - 1)
+    split += 1
+
+    last_part = 0
+    for part in split:
+        axes.plot(x[last_part: part],
+                  y[last_part: part],
+                  **kwargs)
+        last_part = part
+
+
 def plotproj(plotdef, data, outdir):
     '''
     Plot map.
     '''
-    fig, axes = plt.subplots()
+    axes = plt.axes()
 
-    bounds = (plotdef['lonmin'], plotdef['latmin'], plotdef['lonmax'], plotdef['latmax'])
-    for geom in data.filter(bbox=bounds):
-        temp_pol = shape(geom['geometry'])
+    box = Box(
+        plotdef['lonmin'], plotdef['latmin'],
+        plotdef['lonmax'], plotdef['latmax'])
+    for feat in data["features"]:
+        geom = shape(feat["geometry"])
+        if not geom.intersects(box):
+            continue
 
-        box = Polygon([
-            (plotdef['lonmin'], plotdef['latmin']),
-            (plotdef['lonmin'], plotdef['latmax']),
-            (plotdef['lonmax'], plotdef['latmax']),
-            (plotdef['lonmax'], plotdef['latmin']),
-        ])
-        temp_pol = temp_pol.intersection(box)
+        temp_pol = geom.intersection(box)
 
         if plotdef['type'] == 'poly':
             if isinstance(temp_pol, MultiPolygon):
-                polys = [resample_polygon(polygon) for polygon in temp_pol]
+                polys = [resample_polygon(polygon) for polygon in temp_pol.geoms]
                 pol = MultiPolygon(polys)
             else:
                 pol = resample_polygon(temp_pol)
@@ -257,11 +289,15 @@ def plotproj(plotdef, data, outdir):
         proj_geom = transform(trans, pol)
 
         if plotdef['type'] == 'poly':
-            patch = PolygonPatch(proj_geom, fc=COLOR_LAND, zorder=0)
-            axes.add_patch(patch)
+            try:
+                patch = PolygonPatch(proj_geom, fc=COLOR_LAND, zorder=0)
+                axes.add_patch(patch)
+            except TypeError:
+                pass
         else:
             x, y = proj_geom.xy
-            axes.plot(x, y, color=COLOR_COAST, linewidth=0.5)
+            plot_with_interruptions(axes, x, y, color=COLOR_COAST, linewidth=0.5,
+                                    delta_cut=plotdef.get('delta_cut', 1e100))
 
     # Plot frame
     frame = [
@@ -272,7 +308,8 @@ def plotproj(plotdef, data, outdir):
         line = project(line, plotdef['projstring'])
         x = line[:, 0]
         y = line[:, 1]
-        axes.plot(x, y, '-k')
+        plot_with_interruptions(axes, x, y, color='black', linestyle='-',
+                                delta_cut=plotdef.get('delta_cut', 1e6))
 
     graticule = build_graticule(
         plotdef['lonmin'],
@@ -286,60 +323,77 @@ def plotproj(plotdef, data, outdir):
         feature = project(feature, plotdef['projstring'])
         x = feature[:, 0]
         y = feature[:, 1]
-        axes.plot(x, y, color=COLOR_GRAT, linewidth=0.4)
+        plot_with_interruptions(axes, x, y, color=COLOR_GRAT, linewidth=0.4,
+                                delta_cut=plotdef.get('delta_cut', 1e6))
+
+    # Plot interrupted boundaries if necessary
+    interrupted_lines = []
+    if 'top_interrupted_lons' in plotdef:
+        for lon in plotdef['top_interrupted_lons']:
+            for delta in [-0.0001, 0.0001]:
+                merid = meridian(lon + delta, 0.0, plotdef['latmax'])
+                interrupted_lines.append(project(merid, plotdef['projstring']))
+
+    if 'bottom_interrupted_lons' in plotdef:
+        for lon in plotdef['bottom_interrupted_lons']:
+            for delta in [-0.0001, 0.0001]:
+                merid = meridian(lon + delta, plotdef['latmin'], 0)
+                interrupted_lines.append(project(merid, plotdef['projstring']))
+
+    for line in interrupted_lines:
+        x = line[:, 0]
+        y = line[:, 1]
+        plot_with_interruptions(axes, x, y, color=COLOR_GRAT, linewidth=0.4,
+                                delta_cut=plotdef.get('delta_cut', 1e100))
+
+    # Switch off the axis lines...
+    plt.axis('off')
+    # ... and additionally switch off the visibility of the axis lines and
+    # labels so they can be removed by "bbox_inches='tight'" when saving
+    axes.get_xaxis().set_visible(False)
+    axes.get_yaxis().set_visible(False)
 
-    axes.axis('off')
     font = {
         'family': 'serif',
         'color': 'black',
         'style': 'italic',
         'size': 12
     }
-    fig.suptitle(plotdef['projstring'], fontdict=font)
 
-    axes.autoscale(tight=True)
-    if not os.path.exists(outdir):
-        os.makedirs(outdir)
-    fig.savefig(outdir + '/' + plotdef['filename'], dpi=300)
+    # Make sure the plot is not stretched
+    axes.set_aspect('equal')
+
+    outdir = Path(outdir)
+    if not outdir.exists():
+        outdir.mkdir(parents=True)
+    if not outdir.is_dir():
+        raise OSError("outdir is not a directory")
+    plt.savefig(outdir / plotdef['filename'],
+                dpi=400,
+                bbox_inches='tight')
 
     # Clean up
-    fig = None
-    del fig
     axes = None
     del axes
     plt.close()
 
 
-def main():
+def main(plotdefs, outdir, plots=[]):
     '''
     Main function of plotting script.
 
     Parses json-file with plot setups and runs the plotting
     for each plot setup.
     '''
+    plotdefs = json.loads(Path(plotdefs).read_text())
 
     data = {
-        ('line', 'low'): fiona.open(LINE_LOW),
-        ('line', 'med'): fiona.open(LINE_MED),
-        ('poly', 'low'): fiona.open(POLY_LOW),
-        ('poly', 'med'): fiona.open(POLY_MED),
+        ('line', 'low'): geojson.loads(Path(LINE_LOW).read_text()),
+        ('line', 'med'): geojson.loads(Path(LINE_MED).read_text()),
+        ('poly', 'low'): geojson.loads(Path(POLY_LOW).read_text()),
+        ('poly', 'med'): geojson.loads(Path(POLY_MED).read_text()),
     }
 
-    if os.path.exists(sys.argv[1]):
-        # first argument is the JSON plot definition setup file
-        with open(sys.argv[1]) as plotsetup:
-            plotdefs = json.load(plotsetup)
-    else:
-        raise ValueError('No plot definition file entered')
-
-    plots = []
-    # second argument is the output dir
-    outdir = sys.argv[2]
-
-    # subsecond arguments are (optional) names of plot in plotdef.json
-    if len(sys.argv) > 3:
-        plots = sys.argv[3:len(sys.argv)]
-
     for i, plotdef in enumerate(plotdefs):
         if plots != [] and plotdef['name'] not in plots:
             continue
@@ -351,9 +405,20 @@ def main():
 
         plotproj(plotdef, data[(plotdef['type'], plotdef['res'])], outdir)
 
-    for key in data:
-        data[key].close()
-
 
 if __name__ == "__main__":
-    sys.exit(main())
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument(
+        'plotdefs',
+        help='A JSON file with setup for each auto-generated plot')
+    parser.add_argument(
+        'outdir',
+        help='Directory to put the plots in.')
+    parser.add_argument(
+        'plots', nargs='*',
+        help='A list of plot names within the plotdefs file. '
+        'More than one plotname can be given at once.')
+    args = parser.parse_args()
+    sys.exit(main(**vars(args)))

docs/plot/plot.sh

@@ -1,2 +0,0 @@
-
-python3 plot.py plotdefs.json images/

docs/plot/plotdefs.json

@@ -307,6 +307,17 @@
         "res": "low",
         "type": "poly"
     },
+    {
+        "filename": "eqearth.png",
+        "latmax": 90,
+        "latmin": -90,
+        "lonmax": 180,
+        "lonmin": -180,
+        "name": "eqearth",
+        "projstring": "+proj=eqearth",
+        "res": "low",
+        "type": "poly"
+    },
     {
         "filename": "euler.png",
         "latmax": 90,

docs/rtd/plot.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+set -e
+
+export PATH="$HOME/.local/bin:$PATH"
+export PROJ_LIB="$HOME/.local/share/proj"
+
+cd docs/plot
+python plot.py plotdefs.json images
+cd ../..
+
+mkdir -p docs/source/operations/projections/images/
+cp -r docs/plot/images/* docs/source/operations/projections/images/

docs/rtd/pre_build.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -e
+
+mkdir build
+cd build
+
+cmake -GNinja -DCMAKE_BUILD_TYPE=Release -DPROJ_TESTS=OFF -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
+
+ninja install

docs/source/about.rst

@@ -26,7 +26,7 @@ Citation
 To cite PROJ in publications use:
 
   PROJ contributors (2018). PROJ coordinate transformation software
-  library. Open Source Geospatial Foundation. URL http://proj4.org/.
+  library. Open Source Geospatial Foundation. URL https://proj4.org/.
 
 A BibTeX entry for LaTeX users is
 
@@ -37,7 +37,7 @@ A BibTeX entry for LaTeX users is
     author = {{PROJ contributors}},
     organization = {Open Source Geospatial Foundation},
     year = {2018},
-    url = {http://proj4.org/},
+    url = {https://proj4.org/},
   }
 
 License

docs/source/apps/cct.rst

@@ -32,6 +32,12 @@ The following control parameters can appear in any order:
 
     Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4.
 
+.. option:: -d <n>
+
+.. versionadded:: 5.2.0
+
+    Specify the number of decimals in the output.
+
 .. option:: -I
 
     Do the inverse transformation.
@@ -133,6 +139,13 @@ Should give results comparable to the classic :program:`proj` command
 
       cct -t 0 -z 0 +proj=utm +ellps=GRS80 +zone=32
 
+6. Auxiliary data following the coordinate input is forward to the output
+   stream:
+
+.. code-block:: console
+
+    $ echo 12 56 100 2018.0 auxiliary data | cct +proj=merc
+    1335833.8895   7522963.2411      100.0000     2018.0000 auxiliary data
 
 Background
 **********
@@ -171,10 +184,10 @@ Hence, in honour of *cct* (the geodesist) this is :program:`cct` (the program).
     Bugs
     ****
 
-    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    A list of know bugs can be found at https://github.com/OSGeo/proj.4/issues
     where new bug reports can be submitted to.
 
     Home page
     *********
 
-    http://proj4.org/
+    https://proj4.org/

docs/source/apps/cs2cs.rst

@@ -36,6 +36,12 @@ The following control parameters can appear in any order:
     line to be passed through without processing. This option applicable to
     ASCII input only. (# is the default value).
 
+.. option:: -d <n>
+
+.. versionadded:: 5.2.0
+
+    Specify the number of decimals in the output.
+
 .. option:: -e <string>
 
     Where *string* is an arbitrary string to be output if an error is detected during
@@ -171,7 +177,7 @@ The x-y output data will appear as three lines of:
 
 ::
 
-    1402285.99      5076292.42 0.000
+    1402285.98  5076292.42 -0.00
 
 .. only:: man
 
@@ -183,10 +189,10 @@ The x-y output data will appear as three lines of:
     Bugs
     ****
 
-    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    A list of know bugs can be found at https://github.com/OSGeo/proj.4/issues
     where new bug reports can be submitted to.
 
     Home page
     *********
 
-    http://proj4.org/
+    https://proj4.org/

docs/source/apps/geod.rst

@@ -205,10 +205,10 @@ Further reading
     Bugs
     ****
 
-    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    A list of know bugs can be found at https://github.com/OSGeo/proj.4/issues
     where new bug reports can be submitted to.
 
     Home page
     *********
 
-    http://proj4.org/
+    https://proj4.org/

docs/source/apps/gie.rst

@@ -275,6 +275,14 @@ gie command language
 
     See ``gie -l`` for a list of error codes that can be ignored.
 
+.. option:: require_grid <grid_name>
+
+    Checks the availability of the grid <grid_name>. If it is not found, then
+    all :option:`accept`/:option:`expect` pairs until the next
+    :option:`operation` will be skipped.
+    :option:`require_grid` can be repeated several times to specify several grids whose
+    presence is required.
+
 .. option:: echo <text>
 
     Add user defined text to the output stream. See the example below.
@@ -363,10 +371,10 @@ So in honour, and hopefully also in the spirit, of Gerald Ian Evenden
     Bugs
     ****
 
-    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    A list of know bugs can be found at https://github.com/OSGeo/proj.4/issues
     where new bug reports can be submitted to.
 
     Home page
     *********
 
-    http://proj4.org/
+    https://proj4.org/

docs/source/apps/proj.rst

@@ -20,7 +20,7 @@ Synopsis
 Description
 ***********
 :program:`proj` and :program:`invproj` perform respective forward and inverse
-transformation of cartographic data to or from cartesian data with a wide
+conversion of cartographic data to or from cartesian data with a wide
 range of selectable projection functions.
 
 :program:`invproj` may not be available on all platforms; in this case
@@ -37,6 +37,12 @@ The following control parameters can appear in any order
     floating point words. This option is to be used when :program:`proj` is a child process
     and allows bypassing formatting operations.
 
+.. option:: -d <n>
+
+.. versionadded:: 5.2.0
+
+    Specify the number of decimals in the output.
+
 .. option:: -i
 
     Selects binary input only (see :option:`-b`).
@@ -179,7 +185,7 @@ also used for supporting files like datum shift files.
 
 
 One or more files (processed in left to right order) specify the source of
-data to be transformed. A ``-`` will specify the location of processing standard
+data to be converted. A ``-`` will specify the location of processing standard
 input. If no files are specified, the input is assumed to be from stdin.
 For ASCII input data the two data values must be in the first two white space
 separated fields and when both input and output are ASCII all trailing
@@ -230,10 +236,10 @@ data will appear as three lines of::
     Bugs
     ****
 
-    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    A list of know bugs can be found at https://github.com/OSGeo/proj.4/issues
     where new bug reports can be submitted to.
 
     Home page
     *********
 
-    http://proj4.org/
+    https://proj4.org/

docs/source/bibstyle.py

@@ -0,0 +1,64 @@
+###############################################################################
+#
+#  Purpose: Configure custom bibliography style for sphinxcontrib-bibtex
+#  Author:  Mike Toews <mwtoews at gmail.com>
+#
+###############################################################################
+#  Copyright (c) 2018, Mike Toews <mwtoews at gmail.com>
+#
+#  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.
+###############################################################################
+
+import re
+from pybtex.style.formatting.unsrt import Style as UnsrtStyle
+from pybtex.style.labels.alpha import LabelStyle
+from pybtex.plugin import register_plugin
+
+
+class LinkLabelStyle(LabelStyle):
+    """Citation label used in text, and before each item in the
+    References section"""
+
+    re_char_nums = re.compile(r'^[\d\w]+$')
+
+    def format_label(self, entry):
+        """Returns BibTeX key for label
+
+        Raises KeyError if BibTeX key has other characters other than letters
+        and numbers.
+        """
+        label = entry.key
+        if not self.re_char_nums.match(label):
+            raise KeyError(
+                'BibTeX key must contain only letters and numbers '
+                '(found {0!r})'.format(label))
+        return label
+
+
+class CustomStyle(UnsrtStyle):
+    """Citation style in the References section"""
+
+    default_label_style = 'linklabel'
+    default_name_style = 'lastfirst'
+    default_sorting_style = 'author_year_title'
+    # TODO: Make more Harvard-like, i.e. year after name(s)
+
+
+register_plugin('pybtex.style.labels', 'linklabel', LinkLabelStyle)
+register_plugin('pybtex.style.formatting', 'customstyle', CustomStyle)

docs/source/community/channels.rst

@@ -14,7 +14,7 @@ about the development of the library and from time to time interesting discussio
 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
+The PROJ mailing list can be found at https://lists.osgeo.org/mailman/listinfo/proj
 
 
 GitHub
@@ -35,3 +35,12 @@ The PROJ GitHub page can be found at https://github.com/OSGeo/proj.4
     your questions about the use of PROJ on the mailing list instead.
 
 
+Gitter
+-------------------------------------------------------------------------------
+
+Gitter is the instant messaging alternative to the mailing list. PROJ has a
+room under the OSGeo organization. Most of the core developers stop by from
+time to time for an informal chat. You are more than welcome to join the
+discussion.
+
+The Gitter room can be found at https://gitter.im/OSGeo/proj.4

docs/source/community/contributing.rst

@@ -86,7 +86,7 @@ Write documentation
 
 PROJ is in dire need of better documentation. Any contributions of
 documentation are greatly appreciated. The PROJ documentation is
-available on `proj4.org <http://proj4.org>`__. The website is generated
+available on `proj4.org <https://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.
@@ -159,7 +159,7 @@ repository:
 Additional Resources
 --------------------
 
--  `General GitHub documentation <http://help.github.com/>`__
+-  `General GitHub documentation <https://help.github.com/>`__
 -  `GitHub pull request
    documentation <https://help.github.com/articles/about-pull-requests/>`__
 

docs/source/community/index.rst

@@ -14,3 +14,4 @@ contributor the community is always very welcoming.
    channels
    contributing
    code_contributions
+   rfc/index

docs/source/community/rfc/index.rst

@@ -0,0 +1,16 @@
+.. _rfcs:
+
+*****************************************************************************
+ Request for Comments
+*****************************************************************************
+
+A PROJ RFC describes a major change in the technological underpinnings of
+PROJ, major additions to functionality, or changes in the direction of
+the project.
+
+.. toctree::
+   :maxdepth: 1
+
+   rfc-1
+   rfc-2
+   rfc-3

docs/source/community/rfc/rfc-1.rst

@@ -0,0 +1,172 @@
+.. _rfc1:
+
+====================================================================
+PROJ RFC 1: Project Committee Guidelines
+====================================================================
+
+:Author: Frank Warmerdam, Howard Butler
+:Contact: howard@hobu.co
+:Status: Passed
+:Last Updated: 2018-06-08
+
+Summary
+-----------
+
+This document describes how the PROJ Project Steering Committee (PSC)
+determines membership, and makes decisions on all aspects of the
+PROJ project - both technical and non-technical.
+
+Examples of PSC management responsibilities:
+
+* setting the overall development road map
+* developing technical standards and policies (e.g. coding standards,
+  file naming conventions, etc...)
+* ensuring regular releases (major and maintenance) of PROJ software
+* reviewing RFC for technical enhancements to the software
+* project infrastructure (e.g. GitHub, continuous integration hosting options, etc...)
+* formalization of affiliation with external entities such as OSGeo
+* setting project priorities, especially with respect to project sponsorship
+* creation and oversight of specialized sub-committees (e.g. project
+  infrastructure, training)
+
+In brief the project team votes on proposals on the `proj mailing list`_.  Proposals are available for review for at least two days, and a single
+veto is sufficient delay progress though ultimately a majority of members can
+pass a proposal.
+
+.. _`proj mailing list`: http://lists.maptools.org/mailman/listinfo/proj
+
+List of PSC Members
+-------------------
+(up-to-date as of 2018-06)
+
+* Kristian Evers `@kbevers <https://github.com/kbevers>`_ (DK) **Chair**
+* Howard Butler `@hobu <https://github.com/hobu>`_ (USA)
+* Charles Karney `@cffk <https://github.com/cffk>`_ (USA)
+* Thomas Knudsen `@busstoptaktik <https://github.com/busstoptaktik>`_ (DK)
+* Even Rouault `@rouault <https://github.com/rouault>`_ (FR)
+* Kurt Schwehr `@schwehr <https://github.com/schwehr>`_ (USA)
+* Frank Warmerdam `@warmerdam <https://github.com/warmerdam>`_ (USA) **Emeritus**
+
+Detailed Process
+-----------------------
+
+* Proposals are written up and submitted on the `proj mailing list`_
+  for discussion and voting, by any interested party, not just
+  committee members.
+* Proposals need to be available for review for at least two business
+  days before a final decision can be made.
+* Respondents may vote "+1" to indicate support for the proposal and a
+  willingness to support implementation.
+* Respondents may vote "-1" to veto a proposal, but must provide clear
+  reasoning and alternate approaches to resolving the problem within
+  the two days.
+* A vote of -0 indicates mild disagreement, but has no effect.  A 0
+  indicates no opinion.  A +0 indicate mild support, but has no
+  effect.
+* Anyone may comment on proposals on the list, but only members of the
+  Project Steering Committee's votes will be counted.
+* A proposal will be accepted if it receives +2 (including the
+  author) and no vetoes (-1).
+* If a proposal is vetoed, and it cannot be revised to satisfy all
+  parties, then it can be resubmitted for an override vote in which a
+  majority of all eligible voters indicating +1 is sufficient to pass it.
+  Note that this is a majority of all committee members, not just those who
+  actively vote.
+* Upon completion of discussion and voting the author should announce
+  whether they are proceeding (proposal accepted) or are withdrawing
+  their proposal (vetoed).
+* The Chair gets a vote.
+* The Chair is responsible for keeping track of who is a member of the
+  Project Steering Committee (perhaps as part of a PSC file in CVS).
+* Addition and removal of members from the committee, as well as selection
+  of a Chair should be handled as a proposal to the committee.
+* The Chair adjudicates in cases of disputes about voting.
+
+RFC Origin
+.............
+
+PROJ RFC and Project Steering Committee is derived from similar governance
+bodies in both the `GDAL <https://trac.osgeo.org/gdal/wiki/rfc1_pmc>`__ and
+`MapServer <http://mapserver.org/development/rfc/ms-rfc-23.html>`__ software
+projects.
+
+When is Vote Required?
+-----------------------
+
+* Any change to committee membership (new members, removing inactive members)
+* Changes to project infrastructure (e.g. tool, location or substantive
+  configuration)
+* Anything that could cause backward compatibility issues.
+* Adding substantial amounts of new code.
+* Changing inter-subsystem APIs, or objects.
+* Issues of procedure.
+* When releases should take place.
+* Anything dealing with relationships with external entities such as OSGeo
+* Anything that might be controversial.
+
+Observations
+----------------
+
+* The Chair is the ultimate adjudicator if things break down.
+* The absolute majority rule can be used to override an obstructionist
+  veto, but it is intended that in normal circumstances vetoers need to be
+  convinced to withdraw their veto.  We are trying to reach consensus.
+
+Committee Membership
+---------------------
+
+The PSC is made up of individuals consisting of technical contributors
+(e.g. developers) and prominent members of the PROJ user community.
+There is no set number of members for the PSC although the initial desire
+is to set the membership at 6.
+
+Adding Members
+..............
+
+Any member of the `proj mailing list`_ may nominate someone for
+committee membership at any time. Only existing PSC committee members may
+vote on new members.  Nominees must receive a majority vote from existing
+members to be added to the PSC.
+
+Stepping Down
+.............
+
+If for any reason a PSC member is not able to fully participate then they
+certainly are free to step down.  If a member is not active (e.g. no
+voting, no IRC or email participation) for a period of two months then
+the committee reserves the right to seek nominations to fill that position.
+Should that person become active again (hey, it happens) then they would
+certainly be welcome, but would require a nomination.
+
+Membership Responsibilities
+-----------------------------
+
+Guiding Development
+...............................
+
+Members should take an active role guiding the development of new features
+they feel passionate about. Once a change request has been accepted
+and given a green light to proceed does not mean the members are free of
+their obligation. PSC members voting "+1" for a change request are
+expected to stay engaged and ensure the change is implemented and
+documented in a way that is most beneficial to users. Note that this
+applies not only to change requests that affect code, but also those
+that affect the web site, technical infrastructure, policies and standards.
+
+Mailing List Participation
+...............................
+
+PSC members are expected to be active on the
+`proj mailing list`_, subject to Open Source mailing list
+etiquette. Non-developer members of the PSC are not expected to respond
+to coding level questions on the developer mailing list, however they
+are expected to provide their thoughts and opinions on user level
+requirements and compatibility issues when RFC discussions take place.
+
+
+Updates
+---------
+
+**June 2018**
+
+RFC 1 was ratified by the following members

docs/source/community/rfc/rfc-2.rst

@@ -0,0 +1,933 @@
+.. _rfc2:
+
+====================================================================
+PROJ RFC 2: Initial integration of "GDAL SRS barn" work
+====================================================================
+
+:Author: Even Rouault
+:Contact: even.rouault at spatialys.com
+:Status: Adopted (not yet merged into master)
+:Initial version: 2018-10-09
+:Last Updated: 2018-10-31
+
+Summary
+-------
+
+This RFC is the result of a first phase of the `GDAL Coordinate System Barn Raising`_
+efforts. In its current state, this work mostly consists of:
+
+  - a C++ implementation of the ISO-19111:2018 / OGC Topic 2 "Referencing by
+    coordinates" classes to represent Datums, Coordinate systems, CRSs
+    (Coordinate Reference Systems) and Coordinate Operations.
+  - methods to convert between this C++ modeling and WKT1, WKT2 and PROJ string representations of those objects
+  - management and query of a SQLite3 database of CRS and Coordinate Operation definition
+  - a C API binding part of those capabilities
+
+.. _`GDAL Coordinate System Barn Raising`: https://gdalbarn.com/
+
+
+Related standards
+-----------------
+
+Consult `Applicable standards`_
+
+.. _`Applicable standards`: http://even.rouault.free.fr/proj_cpp_api/html/general_doc.html#standards
+
+(They will be linked from the PROJ documentation)
+
+
+Details
+-------
+
+Structure in packages / namespaces
+**********************************
+
+The C++ implementation of the (upcoming) ISO-19111:2018 / OGC Topic 2 "Referencing by
+coordinates" classes follows this abstract modeling as much as possible, using
+package names as C++ namespaces, abstract classes and method names. A new
+BoundCRS class has been added to cover the modeling of the WKT2 BoundCRS
+construct, that is a generalization of the WKT1 TOWGS84 concept. It is
+strongly recommended to have the ISO-19111 standard open to have an introduction
+for the concepts when looking at the code. A few classes have also been
+inspired by the GeoAPI
+
+The classes are organized into several namespaces:
+
+    - osgeo::proj::util
+        A set of base types from ISO 19103, GeoAPI and other PROJ "technical"
+        specific classes 
+
+        Template optional<T>, classes BaseObject, IComparable, BoxedValue,
+        ArrayOfBaseObject, PropertyMap, LocalName, NameSpace, GenericName,
+        NameFactory, CodeList, Exception, InvalidValueTypeException,
+        UnsupportedOperationException
+
+    - osgeo::proj::metadata:
+        Common classes from ISO 19115 (Metadata) standard 
+
+        Classes Citation, GeographicExtent, GeographicBoundingBox,
+        TemporalExtent, VerticalExtent, Extent, Identifier, PositionalAccuracy,
+
+    - osgeo::proj::common: 
+        Common classes: UnitOfMeasure, Measure, Scale, Angle, Length, DateTime,
+        DateEpoch, IdentifiedObject, ObjectDomain, ObjectUsage
+
+    - osgeo::proj::cs:
+        Coordinate systems and their axis 
+        
+        Classes AxisDirection, Meridian, CoordinateSystemAxis, CoordinateSystem,
+        SphericalCS, EllipsoidalCS, VerticalCS, CartesianCS, OrdinalCS,
+        ParametricCS, TemporalCS, DateTimeTemporalCS, TemporalCountCS,
+        TemporalMeasureCS
+
+    - osgeo::proj::datum:
+        Datum (the relationship of a coordinate system to the body) 
+
+        Classes Ellipsoid, PrimeMeridian, Datum, DatumEnsemble,
+        GeodeticReferenceFrame, DynamicGeodeticReferenceFrame,
+        VerticalReferenceFrame, DynamicVerticalReferenceFrame, TemporalDatum,
+        EngineeringDatum, ParametricDatum
+
+    - osgeo::proj::crs:
+        CRS = coordinate reference system = coordinate system with a datum
+
+        Classes CRS, GeodeticCRS, GeographicCRS, DerivedCRS, ProjectedCRS,
+        VerticalCRS, CompoundCRS, BoundCRS, TemporalCRS, EngineeringCRS,
+        ParametricCRS, DerivedGeodeticCRS, DerivedGeographicCRS,
+        DerivedProjectedCRS, DerivedVerticalCRS
+
+    - osgeo::proj::operation:
+        Coordinate operations (relationship between any two coordinate
+        reference systems) 
+
+        Classes CoordinateOperation, GeneralOperationParameter,
+        OperationParameter, GeneralParameterValue, ParameterValue,
+        OperationParameterValue, OperationMethod, InvalidOperation,
+        SingleOperation, Conversion, Transformation, PointMotionOperation,
+        ConcatenatedOperation 
+
+    - osgeo::proj::io:
+        I/O classes: WKTFormatter, PROJStringFormatter, FormattingException,
+        ParsingException, IWKTExportable, IPROJStringExportable, WKTNode,
+        WKTParser, PROJStringParser, DatabaseContext, AuthorityFactory,
+        FactoryException, NoSuchAuthorityCodeException
+
+What does what?
+***************
+
+The code to parse WKT and PROJ strings and build ISO-19111 objects is
+contained in `io.cpp`_
+
+The code to format WKT and PROJ strings from ISO-19111 objects is mostly
+contained in the related exportToWKT() and exportToPROJString() methods
+overridden in the applicable classes. `io.cpp`_ contains the general mechanics
+to build such strings.
+
+Regarding WKT strings, three variants are handled in import and export:
+
+    - WKT2_2018: variant corresponding to the upcoming ISO-19162:2018 standard
+
+    - WKT2_2015: variant corresponding to the current ISO-19162:2015 standard
+
+    - WKT1_GDAL: variant corresponding to the way GDAL understands the OGC
+      01-099 and OGC 99-049 standards
+
+Regarding PROJ strings, two variants are handled in import and export:
+
+    - PROJ5: variant used by PROJ >= 5, possibly using pipeline constructs,
+      and avoiding +towgs84 / +nadgrids legacy constructs. This variant honours
+      axis order and input/output units. That is the pipeline for the conversion
+      of EPSG:4326 to EPSG:32631 will assume that the input coordinates are in
+      latitude, longitude order, with degrees.
+
+    - PROJ4: variant used by PROJ 4.x
+
+The raw query of the proj.db database and the upper level construction of
+ISO-19111 objects from the database contents is done in `factory.cpp`_
+
+A few design principles
+***********************
+
+Methods generally take and return xxxNNPtr objects, that is non-null shared
+pointers (pointers with internal reference counting). The advantage of this
+approach is that the user has not to care about the life-cycle of the
+instances (and this makes the code leak-free by design). The only point of
+attention is to make sure no reference cycles are made. This is the case for
+all classes, except the CoordinateOperation class that point to CRS for
+sourceCRS and targetCRS members, whereas DerivedCRS point to a Conversion
+instance (which derives from CoordinateOperation). This issue was detected in
+the ISO-19111 standard. The solution adopted here is to use std::weak_ptr
+in the CoordinateOperation class to avoid the cycle. This design artifact is
+transparent to users.
+
+Another important design point is that all ISO19111 objects are immutable after
+creation, that is they only have getters that do not modify their states.
+Consequently they could possibly use in a thread-safe way. There are however
+classes like PROJStringFormatter, WKTFormatter, DatabaseContext, AuthorityFactory
+and CoordinateOperationContext whose instances are mutable and thus can not be
+used by multiple threads at once.
+
+Example how to build the EPSG:4326 / WGS84 Geographic2D definition from scratch:
+
+::
+
+    auto greenwich = PrimeMeridian::create(
+        util::PropertyMap()
+            .set(metadata::Identifier::CODESPACE_KEY,
+                metadata::Identifier::EPSG)
+            .set(metadata::Identifier::CODE_KEY, 8901)
+            .set(common::IdentifiedObject::NAME_KEY, "Greenwich"),
+        common::Angle(0));
+    // actually predefined as PrimeMeridian::GREENWICH constant
+
+    auto ellipsoid = Ellipsoid::createFlattenedSphere(
+        util::PropertyMap()
+            .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG)
+            .set(metadata::Identifier::CODE_KEY, 7030)
+            .set(common::IdentifiedObject::NAME_KEY, "WGS 84"),
+        common::Length(6378137),
+        common::Scale(298.257223563));
+    // actually predefined as Ellipsoid::WGS84 constant
+
+    auto datum = GeodeticReferenceFrame::create(
+        util::PropertyMap()
+            .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG)
+            .set(metadata::Identifier::CODE_KEY, 6326)
+            .set(common::IdentifiedObject::NAME_KEY, "World Geodetic System 1984");
+        ellipsoid
+        util::optional<std::string>(), // anchor
+        greenwich);
+    // actually predefined as GeodeticReferenceFrame::EPSG_6326 constant
+
+    auto geogCRS = GeographicCRS::create(
+        util::PropertyMap()
+            .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG)
+            .set(metadata::Identifier::CODE_KEY, 4326)
+            .set(common::IdentifiedObject::NAME_KEY, "WGS 84"),
+        datum,
+        cs::EllipsoidalCS::createLatitudeLongitude(scommon::UnitOfMeasure::DEGREE));
+    // actually predefined as GeographicCRS::EPSG_4326 constant
+
+Algorithmic focus
+*****************
+
+On the algorithmic side, a somewhat involved logic is the
+CoordinateOperationFactory::createOperations() in `coordinateoperation.cpp`_
+that takes a pair of source and target CRS and returns a set of possible
+`coordinate operations`_ (either single operations like a Conversion or a
+Transformation, or concatenated operations). It uses the intrinsinc structure
+of those objects to create the coordinate operation pipeline. That is, if
+going from a ProjectedCRS to another one, by doing first the inverse conversion
+from the source ProjectedCRS to its base GeographicCRS, then finding the
+appropriate transformation(s) from this base GeographicCRS to the base
+GeographicCRS of the target CRS, and then appyling the conversion from this
+base GeographicCRS to the target ProjectedCRS. At each step, it queries the
+database to find if one or several transformations are available. The
+resulting coordinate operations are filtered, and sorted, with user provided hints:
+
+    - desired accuracy
+    - area of use, defined as a bounding box in longitude, latitude space (its
+      actual CRS does not matter for the intended use)
+    - if no area of use is defined, if and how the area of use of the source
+      and target CRS should be used. By default, the smallest area of use is
+      used. The rationale is for example when transforming between a national
+      ProjectedCRS and a world-scope GeographicCRS to use the are of use of
+      this ProjectedCRS to select the appropriate datum shifts.
+    - how the area of use of the candidate transformations and the desired area of
+      use (either explicitly or implicitly defined, as explained above) are
+      compared. By default, only transformations whose area of use is fully
+      contained in the desired area of use are selected. It is also possible
+      to relax this test by specifying that only an intersection test must be used.
+    - whether `PROJ transformation grid`_ names should be susbstituted to the
+      official names, when a match is found in the `grid_alternatives` table
+      of the database. Defaults to true
+    - whether the availability of those grids should be used to filter and sort
+      the results. By default, the transformations using grids available in the
+      system will be presented first.
+
+The results are sorted, with the most relevant ones appearing first in the
+result vector. The criteria used are in that order
+
+    - grid actual availability: operations referencing grids not available will be
+      listed after ones with available grids
+    - grid potential availability: operation referencing grids not known at
+      all in the proj.db will be listed after operations with grids known, but
+      not available.
+    - known accuracy: operations with unknown accuracies will be listed
+      after operations with known accuracy
+    - area of use: operations with smaller area of use (the intersection of the
+      operation area of used with the desired area of use) will be listed after
+      the ones with larger area of use
+    - accuracy: operations with lower accuracy will be listed after operations
+      with higher accuracy (caution: lower accuracy actually means a higher numeric
+      value of the accuracy property, since it is a precision in metre)
+
+All those settings can be specified in the CoordinateOperationContext instance
+passed to createOperations().
+
+An interesting example to understand how those parameters play together is
+to use `projinfo -s EPSG:4267 -t EPSG:4326` (NAD27 to WGS84 conversions),
+and see how specifying desired area of use, spatial criterion, grid availability,
+etc. affects the results.
+
+The following command currently returns 78 results:
+
+::
+
+    projinfo -s EPSG:4267 -t EPSG:4326 --summary --spatial-test intersects
+
+The createOperations() algorithm also does a kind of "CRS routing".
+A typical example is if wanting to transform between CRS A and
+CRS B, but no direct transformation is referenced in proj.db between those.
+But if there are transformations between A <--> C and B <--> C, then it
+is possible to build a concatenated operation A --> C --> B. The typical
+example is when C is WGS84, but the implementation is generic and just finds
+a common pivot from the database. An example of finding a non-WGS84 pivot is
+when searching a transformation between EPSG:4326 and EPSG:6668 (JGD2011 -
+Japanese Geodetic Datum 2011), which has no direct transformation registered
+in the EPSG database . However there are transformations between those two
+CRS and JGD2000 (and also Tokyo datum, but that one involves less accurate
+transformations)
+
+::
+
+    projinfo -s EPSG:4326 -t EPSG:6668  --grid-check none --bbox 135.42,34.84,142.14,41.58 --summary
+
+    Candidate operations found: 7
+    unknown id, Inverse of JGD2000 to WGS 84 (1) + JGD2000 to JGD2011 (1), 1.2 m, Japan - northern Honshu
+    unknown id, Inverse of JGD2000 to WGS 84 (1) + JGD2000 to JGD2011 (2), 2 m, Japan excluding northern main province
+    unknown id, Inverse of Tokyo to WGS 84 (108) + Tokyo to JGD2011 (2), 9.2 m, Japan onshore excluding northern main province
+    unknown id, Inverse of Tokyo to WGS 84 (108) + Tokyo to JGD2000 (2) + JGD2000 to JGD2011 (1), 9.4 m, Japan - northern Honshu
+    unknown id, Inverse of Tokyo to WGS 84 (2) + Tokyo to JGD2011 (2), 13.2 m, Japan - onshore mainland and adjacent islands
+    unknown id, Inverse of Tokyo to WGS 84 (2) + Tokyo to JGD2000 (2) + JGD2000 to JGD2011 (1), 13.4 m, Japan - northern Honshu
+    unknown id, Inverse of Tokyo to WGS 84 (1) + Tokyo to JGD2011 (2), 29.2 m, Asia - Japan and South Korea
+
+
+.. _`coordinate operations`: https://proj4.org/operations/index.html
+
+.. _`PROJ transformation grid`: https://proj4.org/resource_files.html#transformation-grids
+
+
+Code repository
+---------------
+
+The current state of the work can be found in the
+`iso19111 branch of rouault/proj.4 repository`_ , and is also available as
+a GitHub pull request at https://github.com/OSGeo/proj.4/pull/1040
+
+Here is a not-so-usable `comparison with a fixed snapshot of master branch`_
+
+.. _`iso19111 branch of rouault/proj.4 repository`: https://github.com/rouault/proj.4/tree/iso19111
+
+.. _`comparison with a fixed snapshot of master branch`: https://github.com/OSGeo/proj.4/compare/iso19111_dev...rouault:iso19111
+
+
+Database
+--------
+
+Content
+*******
+
+The database contains CRS and coordinate operation definitions from the `EPSG`_
+database (IOGP’s EPSG Geodetic Parameter Dataset) v9.5.3,
+`IGNF registry`_ (French National Geographic Institute), ESRI database, as well
+as a few customizations.
+
+.. _`EPSG`: http://www.epsg.org/
+.. _`IGNF registry`: https://geodesie.ign.fr/index.php?page=documentation#titre3
+
+Building (for PROJ developers creating the database)
+****************************************************
+
+The building of the database is a several stage process:
+
+Construct SQL scripts for EPSG
+++++++++++++++++++++++++++++++
+
+The first stage consists in constructing .sql scripts mostly with
+CREATE TABLE and INSERT statements to create the database structure and
+populate it. There is one .sql file for each database table, populated
+with the content of the EPSG database, automatically
+generated with the `build_db.py`_ script, which processes the PostgreSQL
+dumps issued by IOGP. A number of other scripts are dedicated to manual
+editing, for example `grid_alternatives.sql`_ file that binds official
+grid names to PROJ grid names
+
+Concert UTF8 SQL to sqlite3 db
+++++++++++++++++++++++++++++++
+
+The second stage is done automatically by the make process. It pipes the
+.sql script, in the right order, to the sqlite3 binary to generate a
+first version of the proj.db SQLite3 database.
+
+Add extra registries
+++++++++++++++++++++
+
+The third stage consists in creating additional .sql files from the
+content of other registries. For that process, we need to bind some
+definitions of those registries to those of the EPSG database, to be
+able to link to existing objects and detect some boring duplicates.
+The `ignf.sql`_ file has been generated using
+the `build_db_create_ignf.py`_ script from the current data/IGNF file
+that contains CRS definitions (and implicit transformations to WGS84)
+as PROJ.4 strings.
+The `esri.sql`_ file has been generated using the `build_db_from_esri.py`_
+script, from the .csv files in
+https://github.com/Esri/projection-engine-db-doc/tree/master/csv
+
+Finalize proj.db
+++++++++++++++++
+
+The last stage runs make again to incorporate the new .sql files generated
+in the previous stage (so the process of building the database involves
+a kind of bootstrapping...)
+
+Building (for PROJ users)
+*************************
+
+The make process just runs the second stage mentionned above from the .sql
+files. The resulting proj.db is currently 5.3 MB large.
+
+Structure
+*********
+
+The database is structured into the following tables and views. They generally
+match a ISO-19111 concept, and is generally close to the general structure of
+the EPSG database. Regarding identification of objects, where the EPSG database
+only contains a 'code' numeric column, the PROJ database identifies objects
+with a (auth_name, code) tuple of string values, allowing several registries to
+be combined together.
+
+- Technical:
+    - `authority_list`: view enumerating the authorities present in the database. Currently: EPSG, IGNF, PROJ
+    - `metadata`: a few key/value pairs, for example to indicate the version of the registries imported in the database
+    - `object_view`: synthetic view listing objects (ellipsoids, datums, CRS, coordinate operations...) code and name, and the table name where they are further described
+    - `alias_names`: list possible alias for the `name` field of object table
+    - `link_from_deprecated_to_non_deprecated`: to handle the link between old ESRI to new ESRI/EPSG codes
+
+- Commmon:
+    - `unit_of_measure`: table with UnitOfMeasure definitions.
+    - `area`: table with area-of-use (bounding boxes) applicable to CRS and coordinate operations.
+
+- Coordinate systems:
+    - `axis`: table with CoordinateSystemAxis definitions.
+    - `coordinate_system`: table with CoordinateSystem definitions.
+
+- Ellipsoid and datums:
+    - `ellipsoid`: table with ellipsoid definitions.
+    - `prime_meridian`: table with PrimeMeridian definitions.
+    - `geodetic_datum`: table with GeodeticReferenceFrame definitions.
+    - `vertical_datum`: table with VerticalReferenceFrame definitions.
+
+- CRS:
+    - `geodetic_crs`: table with GeodeticCRS and GeographicCRS definitions.
+    - `projected_crs`: table with ProjectedCRS definitions.
+    - `vertical_crs`: table with VerticalCRS definitions.
+    - `compound_crs`: table with CompoundCRS definitions.
+
+- Coordinate operations:
+    - `coordinate_operation_view`: view giving a number of common attributes shared by the concrete tables implementing CoordinateOperation
+    - `conversion`: table with definitions of Conversion (mostly parameter and values of Projection)
+    - `concatenated_operation`: table with definitions of ConcatenatedOperation.
+    - `grid_transformation`: table with all grid-based transformations.
+    - `grid_packages`: table listing packages in which grids can be found. ie "proj-datumgrid", "proj-datumgrid-europe", ...
+    - `grid_alternatives`: table binding official grid names to PROJ grid names. e.g "Und_min2.5x2.5_egm2008_isw=82_WGS84_TideFree.gz" --> "egm08_25.gtx"
+    - `helmert_transformation`: table with all Helmert-based transformations.
+    - `other_transformation`: table with other type of transformations.
+
+The main departure with the structure of the EPSG database is the split of
+the various coordinate operations over several tables. This was done mostly
+for human-readability as the EPSG organization of coordoperation,
+coordoperationmethod, coordoperationparam, coordoperationparamusage,
+coordoperationparamvalue tables makes it hard to grasp at once all the
+parameters and values for a given operation.
+
+
+Utilities
+---------
+
+A new `projinfo` utility has been added. It enables the user to enter a CRS or
+coordinate operation by a AUTHORITY:CODE, PROJ string or WKT string, and see
+it translated in the different flavors of PROJ and WKT strings.
+It also enables to build coordinate operations between two CRSs.
+
+Usage
+*****
+
+::
+
+    usage: projinfo [-o formats] [-k crs|operation] [--summary] [-q]
+                    [--bbox min_long,min_lat,max_long,max_lat] 
+                    [--spatial-test contains|intersects]
+                    [--crs-extent-use none|both|intersection|smallest]
+                    [--grid-check none|discard_missing|sort]
+                    [--boundcrs-to-wgs84]
+                    {object_definition} | (-s {srs_def} -t {srs_def})
+
+    -o: formats is a comma separated combination of: all,default,PROJ4,PROJ,WKT_ALL,WKT2_2015,WKT2_2018,WKT1_GDAL
+        Except 'all' and 'default', other format can be preceded by '-' to disable them
+
+Examples
+********
+
+Specify CRS by AUTHORITY:CODE
++++++++++++++++++++++++++++++
+
+::
+
+    $ projinfo EPSG:4326
+
+    PROJ string: 
+    +proj=pipeline +step +proj=longlat +ellps=WGS84 +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1
+
+    WKT2_2015 string: 
+    GEODCRS["WGS 84",
+        DATUM["World Geodetic System 1984",
+            ELLIPSOID["WGS 84",6378137,298.257223563,
+                LENGTHUNIT["metre",1]]],
+        PRIMEM["Greenwich",0,
+            ANGLEUNIT["degree",0.0174532925199433]],
+        CS[ellipsoidal,2],
+            AXIS["geodetic latitude (Lat)",north,
+                ORDER[1],
+                ANGLEUNIT["degree",0.0174532925199433]],
+            AXIS["geodetic longitude (Lon)",east,
+                ORDER[2],
+                ANGLEUNIT["degree",0.0174532925199433]],
+        AREA["World"],
+        BBOX[-90,-180,90,180],
+        ID["EPSG",4326]]
+
+
+Specify CRS by PROJ string and specify output formats
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+::
+
+    $ projinfo -o PROJ4,PROJ,WKT1_GDAL,WKT2_2018 "+title=IGN 1972 Nuku Hiva - UTM fuseau 7 Sud +proj=tmerc +towgs84=165.7320,216.7200,180.5050,-0.6434,-0.4512,-0.0791,7.420400 +a=6378388.0000 +rf=297.0000000000000 +lat_0=0.000000000 +lon_0=-141.000000000 +k_0=0.99960000 +x_0=500000.000 +y_0=10000000.000 +units=m +no_defs"
+
+    PROJ string: 
+    Error when exporting to PROJ string: BoundCRS cannot be exported as a PROJ.5 string, but its baseCRS might
+
+    PROJ.4 string: 
+    +proj=utm +zone=7 +south +ellps=intl +towgs84=165.732,216.72,180.505,-0.6434,-0.4512,-0.0791,7.4204
+
+    WKT2_2018 string: 
+    BOUNDCRS[
+        SOURCECRS[
+            PROJCRS["IGN 1972 Nuku Hiva - UTM fuseau 7 Sud",
+                BASEGEOGCRS["unknown",
+                    DATUM["unknown",
+                        ELLIPSOID["International 1909 (Hayford)",6378388,297,
+                            LENGTHUNIT["metre",1,
+                                ID["EPSG",9001]]]],
+                    PRIMEM["Greenwich",0,
+                        ANGLEUNIT["degree",0.0174532925199433],
+                        ID["EPSG",8901]]],
+                CONVERSION["unknown",
+                    METHOD["Transverse Mercator",
+                        ID["EPSG",9807]],
+                    PARAMETER["Latitude of natural origin",0,
+                        ANGLEUNIT["degree",0.0174532925199433],
+                        ID["EPSG",8801]],
+                    PARAMETER["Longitude of natural origin",-141,
+                        ANGLEUNIT["degree",0.0174532925199433],
+                        ID["EPSG",8802]],
+                    PARAMETER["Scale factor at natural origin",0.9996,
+                        SCALEUNIT["unity",1],
+                        ID["EPSG",8805]],
+                    PARAMETER["False easting",500000,
+                        LENGTHUNIT["metre",1],
+                        ID["EPSG",8806]],
+                    PARAMETER["False northing",10000000,
+                        LENGTHUNIT["metre",1],
+                        ID["EPSG",8807]]],
+                CS[Cartesian,2],
+                    AXIS["(E)",east,
+                        ORDER[1],
+                        LENGTHUNIT["metre",1,
+                            ID["EPSG",9001]]],
+                    AXIS["(N)",north,
+                        ORDER[2],
+                        LENGTHUNIT["metre",1,
+                            ID["EPSG",9001]]]]],
+        TARGETCRS[
+            GEOGCRS["WGS 84",
+                DATUM["World Geodetic System 1984",
+                    ELLIPSOID["WGS 84",6378137,298.257223563,
+                        LENGTHUNIT["metre",1]]],
+                PRIMEM["Greenwich",0,
+                    ANGLEUNIT["degree",0.0174532925199433]],
+                CS[ellipsoidal,2],
+                    AXIS["latitude",north,
+                        ORDER[1],
+                        ANGLEUNIT["degree",0.0174532925199433]],
+                    AXIS["longitude",east,
+                        ORDER[2],
+                        ANGLEUNIT["degree",0.0174532925199433]],
+                ID["EPSG",4326]]],
+        ABRIDGEDTRANSFORMATION["Transformation from unknown to WGS84",
+            METHOD["Position Vector transformation (geog2D domain)",
+                ID["EPSG",9606]],
+            PARAMETER["X-axis translation",165.732,
+                ID["EPSG",8605]],
+            PARAMETER["Y-axis translation",216.72,
+                ID["EPSG",8606]],
+            PARAMETER["Z-axis translation",180.505,
+                ID["EPSG",8607]],
+            PARAMETER["X-axis rotation",-0.6434,
+                ID["EPSG",8608]],
+            PARAMETER["Y-axis rotation",-0.4512,
+                ID["EPSG",8609]],
+            PARAMETER["Z-axis rotation",-0.0791,
+                ID["EPSG",8610]],
+            PARAMETER["Scale difference",1.0000074204,
+                ID["EPSG",8611]]]]
+
+    WKT1_GDAL: 
+    PROJCS["IGN 1972 Nuku Hiva - UTM fuseau 7 Sud",
+        GEOGCS["unknown",
+            DATUM["unknown",
+                SPHEROID["International 1909 (Hayford)",6378388,297],
+                TOWGS84[165.732,216.72,180.505,-0.6434,-0.4512,-0.0791,7.4204]],
+            PRIMEM["Greenwich",0,
+                AUTHORITY["EPSG","8901"]],
+            UNIT["degree",0.0174532925199433,
+                AUTHORITY["EPSG","9122"]],
+            AXIS["Longitude",EAST],
+            AXIS["Latitude",NORTH]],
+        PROJECTION["Transverse_Mercator"],
+        PARAMETER["latitude_of_origin",0],
+        PARAMETER["central_meridian",-141],
+        PARAMETER["scale_factor",0.9996],
+        PARAMETER["false_easting",500000],
+        PARAMETER["false_northing",10000000],
+        UNIT["metre",1,
+            AUTHORITY["EPSG","9001"]],
+        AXIS["Easting",EAST],
+        AXIS["Northing",NORTH]]
+
+
+Find transformations between 2 CRS
+++++++++++++++++++++++++++++++++++
+
+Between "Poland zone I" (based on Pulkovo 42 datum) and "UTM WGS84 zone 34N"
+
+Summary view:
+
+::
+
+    $ projinfo -s EPSG:2171 -t EPSG:32634 --summary
+
+    Candidate operations found: 1
+    unknown id, Inverse of Poland zone I + Pulkovo 1942(58) to WGS 84 (1) + UTM zone 34N, 1 m, Poland - onshore
+
+Display of pipelines:
+
+::
+
+    $ PROJ_LIB=data src/projinfo -s EPSG:2171 -t EPSG:32634 -o PROJ
+
+    PROJ string: 
+    +proj=pipeline +step +proj=axisswap +order=2,1 +step +inv +proj=sterea +lat_0=50.625 +lon_0=21.0833333333333 +k=0.9998 +x_0=4637000 +y_0=5647000 +ellps=krass +step +proj=cart +ellps=krass +step +proj=helmert +x=33.4 +y=-146.6 +z=-76.3 +rx=-0.359 +ry=-0.053 +rz=0.844 +s=-0.84 +convention=position_vector +step +inv +proj=cart +ellps=WGS84 +step +proj=utm +zone=34 +ellps=WGS84
+
+
+Impacted files
+--------------
+
+New files (excluding makefile.am, CMakeLists.txt and other build infrastructure
+artifacts):
+
+    * include/proj/: Public installed C++ headers
+        - `common.hpp`_: declarations of osgeo::proj::common namespace.
+        - `coordinateoperation.hpp`_:  declarations of osgeo::proj::operation namespace.
+        - `coordinatesystem.hpp`_:  declarations of osgeo::proj::cs namespace.
+        - `crs.hpp`_:  declarations of osgeo::proj::crs namespace.
+        - `datum.hpp`_:  declarations of osgeo::proj::datum namespace.
+        - `io.hpp`_:  declarations of osgeo::proj::io namespace.
+        - `metadata.hpp`_: declarations of osgeo::proj::metadata namespace.
+        - `util.hpp`_: declarations of osgeo::proj::util namespace.
+        - `nn.hpp`_: Code from https://github.com/dropbox/nn to manage Non-nullable pointers for C++
+
+    .. _`common.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/common.hpp
+    .. _`coordinateoperation.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinateoperation.hpp
+    .. _`coordinatesystem.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinatesystem.hpp
+    .. _`crs.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/crs.hpp
+    .. _`datum.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/datum.hpp
+    .. _`io.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/io.hpp
+    .. _`metadata.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/metadata.hpp
+    .. _`nn.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/nn.hpp
+    .. _`util.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/util.hpp
+
+    * include/proj/internal: Private non-installed C++ headers
+        - `coordinateoperation_internal.hpp`_: classes InverseCoordinateOperation, InverseConversion, InverseTransformation, PROJBasedOperation, and functions to get conversion mappings between WKT and PROJ syntax
+        - `coordinateoperation_constants.hpp`_: Select subset of conversion/transformation EPSG names and codes for the purpose of translating them to PROJ strings
+        - `coordinatesystem_internal.hpp`_: classes AxisDirectionWKT1, AxisName and AxisAbbreviation
+        - `internal.hpp`_: a few helper functions, mostly to do string-based operations
+        - `io_internal.hpp`_: class WKTConstants
+        - `helmert_constants.hpp`_: Helmert-based transformation & parameters names and codes.
+        - `lru_cache.hpp`_: code from https://github.com/mohaps/lrucache11 to have a generic Least-Recently-Used cache of objects
+
+    .. _`coordinateoperation_internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinateoperation_internal.hpp
+    .. _`coordinatesystem_internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinatesystem_internal.hpp
+    .. _`internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/internal.hpp
+    .. _`io_internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/io_internal.hpp
+    .. _`coordinateoperation_constants.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinateoperation_constants.hpp
+    .. _`helmert_constants.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/helmert_constants.hpp
+    .. _`lru_cache.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/lru_cache.hpp
+
+    * src/:
+        - `c_api.cpp`_: C++ API mapped to C functions
+        - `common.cpp`_: implementation of `common.hpp`_
+        - `coordinateoperation.cpp`_: implementation of `coordinateoperation.hpp`_
+        - `coordinatesystem.cpp`_: implementation of `coordinatesystem.hpp`_
+        - `crs.cpp`_: implementation of `crs.hpp`_
+        - `datum.cpp`_: implementation of `datum.hpp`_
+        - `factory.cpp`_: implementation of AuthorityFactory class (from `io.hpp`_)
+        - `internal.cpp`_: implementation of `internal.hpp`_
+        - `io.cpp`_: implementation of `io.hpp`_
+        - `metadata.cpp`_: implementation of `metadata.hpp`_
+        - `static.cpp`_: a number of static constants (like pre-defined well-known ellipsoid, datum and CRS), put in the right order for correct static initializations
+        - `util.cpp`_: implementation of `util.hpp`_
+        - `projinfo.cpp`_: new 'projinfo' binary
+        - `general.dox`_: generic introduction documentation.
+
+    .. _`c_api.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/c_api.cpp
+    .. _`common.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/common.cpp
+    .. _`coordinateoperation.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/coordinateoperation.cpp
+    .. _`coordinatesystem.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/coordinatesystem.cpp
+    .. _`crs.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/crs.cpp
+    .. _`datum.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/datum.cpp
+    .. _`factory.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/factory.cpp
+    .. _`internal.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/internal.cpp
+    .. _`io.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/io.cpp
+    .. _`metadata.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/metadata.cpp
+    .. _`projinfo.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/projinfo.cpp
+    .. _`static.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/static.cpp
+    .. _`util.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/util.cpp
+    .. _`general.dox`: https://github.com/rouault/proj.4/blob/iso19111/src/general.dox
+
+    * data/sql/:
+        - `area.sql`_: generated by `build_db.py`_
+        - `axis.sql`_: generated by `build_db.py`_
+        - `begin.sql`_: hand generated (trivial)
+        - `commit.sql`_: hand generated (trivial)
+        - `compound_crs.sql`_: generated by `build_db.py`_
+        - `concatenated_operation.sql`_: generated by `build_db.py`_
+        - `conversion.sql`_: generated by `build_db.py`_
+        - `coordinate_operation.sql`_: generated by `build_db.py`_
+        - `coordinate_system.sql`_: generated by `build_db.py`_
+        - `crs.sql`_: generated by `build_db.py`_
+        - `customizations.sql`_: hand generated (empty)
+        - `ellipsoid.sql`_: generated by `build_db.py`_
+        - `geodetic_crs.sql`_: generated by `build_db.py`_
+        - `geodetic_datum.sql`_: generated by `build_db.py`_
+        - `grid_alternatives.sql`_: hand-generated. Contains links between official registry grid names and PROJ ones
+        - `grid_transformation.sql`_: generated by `build_db.py`_
+        - `grid_transformation_custom.sql`_: hand-generated
+        - `helmert_transformation.sql`_: generated by `build_db.py`_
+        - `ignf.sql`_: generated by `build_db_create_ignf.py`_
+        - `esri.sql`_: generated by `build_db_from_esri.py`_
+        - `metadata.sql`_: hand-generated
+        - `other_transformation.sql`_: generated by `build_db.py`_
+        - `prime_meridian.sql`_: generated by `build_db.py`_
+        - `proj_db_table_defs.sql`_: hand-generated. Database structure: CREATE TABLE / CREATE VIEW / CREATE TRIGGER
+        - `projected_crs.sql`_: generated by `build_db.py`_
+        - `unit_of_measure.sql`_: generated by `build_db.py`_
+        - `vertical_crs.sql`_: generated by `build_db.py`_
+        - `vertical_datum.sql`_: generated by `build_db.py`_
+
+    .. _`area.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/area.sql
+    .. _`axis.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/axis.sql
+    .. _`begin.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/begin.sql
+    .. _`commit.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/commit.sql
+    .. _`compound_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/compound_crs.sql
+    .. _`concatenated_operation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/concatenated_operation.sql
+    .. _`conversion.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/conversion.sql
+    .. _`coordinate_operation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/coordinate_operation.sql
+    .. _`coordinate_system.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/coordinate_system.sql
+    .. _`crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/crs.sql
+    .. _`customizations.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/customizations.sql
+    .. _`ellipsoid.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/ellipsoid.sql
+    .. _`geodetic_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/geodetic_crs.sql
+    .. _`geodetic_datum.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/geodetic_datum.sql
+    .. _`grid_alternatives.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_alternatives.sql
+    .. _`grid_transformation_custom.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_transformation_custom.sql
+    .. _`grid_transformation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_transformation.sql
+    .. _`helmert_transformation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/helmert_transformation.sql
+    .. _`ignf.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/ignf.sql
+    .. _`esri.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/esri.sql
+    .. _`metadata.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/metadata.sql
+    .. _`other_transformation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/other_transformation.sql
+    .. _`prime_meridian.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/prime_meridian.sql
+    .. _`proj_db_table_defs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/proj_db_table_defs.sql
+    .. _`projected_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/projected_crs.sql
+    .. _`unit_of_measure.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/unit_of_measure.sql
+    .. _`vertical_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/vertical_crs.sql
+    .. _`vertical_datum.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/vertical_datum.sql
+
+    * scripts/:
+        - `build_db.py`_ : generate .sql files from EPSG database dumps
+        - `build_db_create_ignf.py`_: generates data/sql/`ignf.sql`_
+        - `build_db_from_esri.py`_: generates data/sql/`esri.sql`_
+        - `doxygen.sh`_: generates Doxygen documentation
+        - `gen_html_coverage.sh`_: generates HTML report of the coverage for --coverage build
+        - `filter_lcov_info.py`_: utility used by gen_html_coverage.sh
+        - `reformat.sh`_: used by reformat_cpp.sh
+        - `reformat_cpp.sh`_: reformat all .cpp/.hpp files according to LLVM-style formatting rules
+
+    .. _`build_db.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py
+    .. _`build_db_create_ignf.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_create_ignf.py
+    .. _`build_db_from_esri.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_from_esri.py
+    .. _`doxygen.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/doxygen.sh
+    .. _`gen_html_coverage.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/gen_html_coverage.sh
+    .. _`filter_lcov_info.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/filter_lcov_info.py
+    .. _`reformat.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/reformat.sh
+    .. _`reformat_cpp.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/reformat_cpp.sh
+
+    * tests/unit/
+        - `test_c_api.cpp`_: test of src/c_api.cpp
+        - `test_common.cpp`_: test of src/common.cpp
+        - `test_util.cpp`_: test of src/util.cpp
+        - `test_crs.cpp`_: test of src/crs.cpp
+        - `test_datum.cpp`_: test of src/datum.cpp
+        - `test_factory.cpp`_: test of src/factory.cpp
+        - `test_io.cpp`_: test of src/io.cpp
+        - `test_metadata.cpp`_: test of src/metadata.cpp
+        - `test_operation.cpp`_: test of src/operation.cpp
+
+    .. _`test_c_api.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_c_api.cpp
+    .. _`test_common.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_common.cpp
+    .. _`test_util.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_util.cpp
+    .. _`test_crs.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_crs.cpp
+    .. _`test_datum.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_datum.cpp
+    .. _`test_factory.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_factory.cpp
+    .. _`test_io.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_io.cpp
+    .. _`test_metadata.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_metadata.cpp
+    .. _`test_operation.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_operation.cpp
+
+C API
+-----
+
+`proj.h`_ has been extended to bind a number of C++ classes/methods to a C API.
+
+The main structure is an opaque PJ_OBJ* roughly encapsulating a osgeo::proj::BaseObject,
+that can represent a CRS or a CoordinateOperation object. A number of the
+C functions will work only if the right type of underlying C++ object is used
+with them. Misuse will be properly handled at runtime. If a user passes
+a PJ_OBJ* representing a coordinate operation to a pj_obj_crs_xxxx() function,
+it will properly error out. This design has been chosen over creating a
+dedicate PJ_xxx object for each C++ class, because such an approach would
+require adding many conversion and free functions for little benefit.
+
+This C API is incomplete. In particular, it does not allow to
+build ISO19111 objects at hand. However it currently permits a number of
+actions:
+
+    - building CRS and coordinate operations from WKT and PROJ strings, or
+      from the proj.db database
+    - exporting CRS and coordinate operations as WKT and PROJ strings
+    - querying main attributes of those objects
+    - finding coordinate operations between two CRS.
+
+`test_c_api.cpp`_ should demonstrates simple usage of the API (note:
+for the conveniency of writing the tests in C++, test_c_api.cpp wraps the C PJ_OBJ*
+instances in C++ 'keeper' objects that automatically call the pj_obj_unref()
+function at function end. In a pure C use, the caller must use pj_obj_unref()
+to prevent leaks.)
+
+.. _`proj.h`: http://even.rouault.free.fr/proj_cpp_api/html/proj_8h.html
+
+
+Documentation
+-------------
+
+All public C++ classes and methods and C functions are documented with
+Doxygen.
+
+`Current snapshot of Class list`_
+
+`Spaghetti inheritance diagram`_
+
+.. _`Current snapshot of Class list`: http://even.rouault.free.fr/proj_cpp_api/html/annotated.html
+.. _`Spaghetti inheritance diagram`: http://even.rouault.free.fr/proj_cpp_api/html/inherits.html
+
+A basic integration of the Doxygen XML output into the general PROJ
+documentation (using reStructuredText format) has been done with the the
+Sphinx extension `Breathe`_, producing:
+
+    * `One section with the C++ API`_
+    * `One section with the C API`_
+
+.. _`Breathe`: https://breathe.readthedocs.io/en/latest/
+.. _`One section with the C++ API`: http://even.rouault.free.fr/proj_cpp_api/rst_generated/html/development/reference/cpp/index.html
+.. _`One section with the C API`: http://even.rouault.free.fr/proj_cpp_api/rst_generated/html/development/reference/functions.html#c-api-for-iso-19111-functionality
+
+Testing
+-------
+
+Nearly all exported methods are tested by a unit test. Global line coverage
+of the new files is 92%. Those tests represent 16k lines of codes.
+
+
+Build requirements
+------------------
+
+The new code leverages on a number of C++11 features (auto keyword, constexpr,
+initializer list, std::shared_ptr, lambda functions, etc.), which means that
+a C++11-compliant compiler must be used to generate PROJ:
+
+    * gcc >= 4.8
+    * clang >= 3.3
+    * Visual Studio >= 2015.
+
+Compilers tested by the Travis-CI and AppVeyor continuous integration
+environments:
+
+    * GCC 4.8
+    * mingw-w64-x86-64 4.8
+    * clang 5.0
+    * Apple LLVM version 9.1.0 (clang-902.0.39.2)
+    * MSVC 2015 32 and 64 bit
+    * MSVC 2017 32 and 64 bit
+
+The libsqlite3 >= 3.7 development package must also be available. And the sqlite3
+binary must be available to build the proj.db files from the .sql files.
+
+Runtime requirements
+--------------------
+
+* libc++/libstdc++/MSVC runtime consistent with the compiler used
+* libsqlite3 >= 3.7
+
+
+Backward compatibility
+----------------------
+
+At this stage, no backward compatibility issue is foreseen, as no
+existing functional C code has been modified to use the new capabilities
+
+Future work
+-----------
+
+The work described in this RFC will be pursued in a number of directions.
+Non-exhaustively:
+
+  - Support for ESRI WKT1 dialect (PROJ currently ingest the ProjectedCRS in
+    `esri.sql`_ in that dialect, but there is no mapping between it and EPSG
+    operation and parameter names, so conversion to PROJ strings does not
+    always work.
+
+  - closer integration with the existing code base. In particular, the +init=dict:code
+    syntax should now go first to the database (then the `epsg` and `IGNF`
+    files can be removed). Similarly proj_create_crs_to_crs() could use the
+    new capabilities to find an appropriate coordinate transformation.
+
+  - and whatever else changes are needed to address GDAL and libgeotiff needs
+
+
+Adoption status
+---------------
+
+The RFC has been adopted with support from PSC members Kurt Schwehr, Kristian
+Evers, Howard Butler and Even Rouault.

docs/source/community/rfc/rfc-3.rst

@@ -0,0 +1,151 @@
+.. _rfc3:
+
+====================================================================
+PROJ RFC 3: Dependency management
+====================================================================
+
+:Author: Kristian Evers
+:Contact: kreve@sdfe.dk
+:Status: Adopted
+:Last Updated: 2019-01-16
+
+Summary
+-------------------------------------------------------------------------------
+
+This document defines a set of guidelines for dependency management in PROJ.
+With PROJ being a core component in many downstream software packages clearly
+stating which dependencies the library has is of great value. This document
+concern both programming language standards as well as minimum required
+versions of library dependencies and build tools.
+
+It is proposed to adopt a rolling update scheme that ensures that PROJ is
+sufficiently accessible, even on older systems, as well as keeping up with the
+technological evolution. The scheme is divided in two parts, one concerning
+versions of used programming languages within PROJ and the other concerning
+software packages that PROJ depend on.
+
+With adoption of this RFC, versions used for
+
+1. programming languages will always be at least two revisions behind the most
+   recent standard
+2. software packages will always be at least two years old
+   (patch releases are exempt)
+
+A change in programming language standard can only be introduced with a new
+major version release of PROJ. Changes for software package dependencies can be
+introduced with minor version releases of PROJ. Changing the version
+requirements for a dependency needs to be approved by the PSC.
+
+Following the above rule set will ensure that all but the most conservative
+users of PROJ will be able to build and use the most recent version of the
+library.
+
+In the sections below details concerning programming languages and software
+dependencies are outlined. The RFC is concluded with a bootstrapping section
+that details the state of dependencies after the accept of the RFC.
+
+
+Background
+-------------------------------------------------------------------------------
+
+PROJ has traditionally been written in C89. Until recently, no formal
+requirements of e.g. build systems has been defined and formally accepted by
+the project. :ref:RFC2 <rfc2>` formally introduces dependencies on C++11 and
+SQLite 3.7.
+
+In this RFC a rolling update of version or standard requirements is described.
+The reasoning behind a rolling update scheme is that it has become increasingly
+evident that C89 is becoming outdated and creating a less than optimal
+development environment for contributors. It has been noted that the most
+commonly used compilers all now support more recent versions of C, so the
+strict usage of C89 is no longer as critical as it used to be.
+
+Similarly, rolling updates to other tools and libraries that PROJ depend on
+will ensure that the code base can be kept modern and in line with the rest of
+the open source software ecosphere.
+
+
+C and C++
+-------------------------------------------------------------------------------
+
+Following :ref:`RFC2 <rfc2>` PROJ is written in both C and C++. At the time of
+writing the core library is C based and the code described in RFC2 is written
+in C++. While the core library is mostly written in C it is compiled as C++.
+Minor sections of PROJ, like the geodesic algorithms are still compiled as C
+since there is no apparent benefit of compiling with a C++ compiler. This may
+change in the future.
+
+Both the C and C++ standards are updated with regular intervals. After an
+update of a standard it takes time for compiler manufacturers to implement the
+standards fully, which makes adaption of new standards potentially troublesome
+if done too soon. On the other hand, waiting too long to adopt new standards
+will eventually make the code base feel old and new contributors are more
+likely to stay away because they don't want to work using tools of the past.
+With a rolling update scheme both concerns can be managed by always staying
+behind the most recent standard, but not so far away that potential
+contributors are scared away. Keeping a policy of always lagging behind be two
+iterations of the standard is thought to be the best comprise between the two
+concerns.
+
+C comes in four ISO standardised varieties: C89, C99, C11, C18. In this
+document we refer to their informal names for ease of reading. C++ exists in
+five varieties: C++98, C++03, C++11, C++14, C++17. Before adoption of this RFC
+PROJ uses C89 and C++11. For C, that means that the used standard is three
+iterations behind the most recent standard. C++ is two iterations behind.
+Following the rules in this RFC the required C standard used in PROJ is at
+allowed to be two iterations behind the most recent standard. That means that a
+change to C99 is possible, as long as the PROJ PSC aknowledges such a change.
+
+When a new standard for either C or C++ is released PROJ should consider
+changing its requirement to the next standard in the line. For C++ that means a
+change in standard roughly every three years, for C the periods between
+standard updates is expected to be longer. Adaptation of new programming
+language standards should be coordinated with a major version release of PROJ.
+
+
+Software dependencies
+-------------------------------------------------------------------------------
+
+At the time of writing PROJ is dependent on very few external packages. In
+fact only one runtime dependency is present: SQLite. Building PROJ also
+requires one of two external dependencies for configuration: Autotools or
+CMake.
+
+As with programming language standards it is preferable that software
+dependencies are a bit behind the most recent development. For this reason it
+is required that the minimum version supported in PROJ dependencies is at least
+two years old, preferably more. It is not a requirement that the minimum
+version of dependencies is always kept strictly two years behind current
+development, but it is allowed in case future development of PROJ warrants an
+update. Changes in minimum version requirements are allowed to happen with
+minor version releases of PROJ.
+
+At the time of writing the minimum version requried for SQLite it 3.7 which was
+released in 2010. CMake currently is required to be at least at version 2.8.3
+which was also released in 2010.
+
+
+Bootstrapping
+-------------------------------------------------------------------------------
+
+This RFC comes with a set of guidelines for handling dependencies for PROJ in
+the future. Up until now dependencies hasn't been handled consistently,  with
+some dependencies not being approved formally by the projects governing body.
+Therefore minimum versions of PROJ dependencies is proposed so that at the
+acception of this RFC PROJ will have the following external requirements:
+
+* C99 (was C89)
+* C++11 (already approved in :ref:`RFC2 <rfc2>`)
+* SQLite 3.7 (already approved in :ref:`RFC2 <rfc2>`)
+* CMake 3.5 (was 2.8.3)
+
+
+Adoption status
+-------------------------------------------------------------------------------
+
+The RFC was adopted on 2018-01-19 with +1's from the following PSC members
+
+* Kristian Evers
+* Even Rouault
+* Thomas Knudsen
+* Howard Butler

docs/source/conf.py

@@ -14,12 +14,13 @@
 
 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
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
+
+import bibstyle
 
 # -- General configuration ------------------------------------------------
 
@@ -31,11 +32,15 @@ import datetime
 # ones.
 extensions = [
     'sphinx.ext.mathjax',
+    'sphinxcontrib.bibtex',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# BibTeX configuration
+bibtex_bibfiles = ['references.bib']
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
@@ -55,34 +60,30 @@ project = 'PROJ.4'
 # See CITATION file
 title = 'PROJ coordinate transformation software library'
 author = 'PROJ contributors'
-
-now = datetime.datetime.now()
-copyright = u'1983-{0}'.format(now.year)
+copyright = u'1983-2018'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-version = '5.0.1'
-
-# use same |release| as |version|
-release = version
+version = '5.2'
+release = '5.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#today = ''
+today = 'September 2018'
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['operations/options/*.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -152,10 +153,16 @@ html_theme_options = {}
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+htm_css_files = [
+    'theme_overrides.css',  # override wide tables in RTD theme
+]
+
 html_context = {
-    'css_files': [
-        '_static/theme_overrides.css',  # override wide tables in RTD theme
-    ],
+    'display_github': True,
+    'theme_vcs_pageview_mode': 'edit',
+    'github_user': 'OSGeo',
+    'github_repo': 'PROJ',
+    'github_version': '/5.2/docs/source/',
 }
 
 # Add any extra paths that contain custom files (such as robots.txt or
@@ -228,6 +235,8 @@ preamble = r"""
 \ifdefined\DeclareUnicodeCharacter
   \DeclareUnicodeCharacter{2032}{$'$}% prime
 \fi
+
+\usepackage[notbib,notindex]{tocbibind}
 """
 
 latex_elements = {
@@ -239,7 +248,7 @@ latex_elements = {
 
 # Additional stuff for the LaTeX preamble.
 'preamble': preamble,
-'inputenc':'\usepackage[utf8]{inputenc}'
+'inputenc': r'\usepackage[utf8]{inputenc}',
 
 # Latex figure (float) alignment
 #'figure_align': 'htbp',

docs/source/development/bindings.rst

@@ -8,14 +8,14 @@ PROJ bindings are available for a number of different development platforms.
 
 Python
 ======
-`pyproj <http://pypi.python.org/pypi/pyproj>`_:
+`pyproj <https://pypi.python.org/pypi/pyproj>`_:
 Python interface (wrapper for PROJ)
 
 
 Ruby
 =======
 
-`proj4rb <http://proj4rb.rubyforge.org>`_:
+`proj4rb <https://github.com/cfis/proj4rb>`_:
 Bindings for PROJ in ruby
 
 TCL
@@ -26,7 +26,7 @@ Bindings for PROJ in tcl (critcl source)
 MySQL
 =====
 
-`fProj4 <http://sourceforge.net/projects/mysqlscientific/files/fPROJ4/>`_:
+`fProj4 <https://sourceforge.net/projects/mysqlscientific/files/fPROJ4/>`_:
 Bindings for PROJ in MySQL
 
 
@@ -41,3 +41,9 @@ Visual Basic
 
 `PROJ VB Wrappers <http://ftp.dfg.ca.gov/Public/BDB/Tools/proj4/proj_api.zip>`_:
 By Eric G. Miller.
+
+Fortran
+=======
+
+`Fortran-Proj <https://gitlab.com/likeno/fortran-proj>`_:
+Bindings for PROJ in Fortran (By João Macedo @likeno)

docs/source/development/index.rst

@@ -19,3 +19,27 @@ PROJ project or using the library in their own software.
    cmake
    bindings
    migration
+
+
+.. 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.
+
+.. attention::
+
+    With the introduction of PROJ 5, behavioural changes has been made to
+    existing functionality. Consult :ref:`differences` for the details.

docs/source/development/migration.rst

@@ -109,8 +109,8 @@ The same program implemented using PROJ v. 5:
             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.lp.lam = proj_torad(c.lp.lam);
+            c.lp.phi = proj_torad(c.lp.phi);
             c = proj_trans(P, PJ_FWD, c);
             printf("%.2f\t%.2f\n", c.xy.x, c.xy.y);
         }

docs/source/development/reference/functions.rst

@@ -32,6 +32,10 @@ Transformation setup
 
         PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel");
 
+    If creation of the transformation object fails, the function returns `0` and
+    the PROJ error number is updated. The error number can be read with
+    :c:func:`proj_errno` or :c:func:`proj_context_errno`.
+
     The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
 
     :param PJ_CONTEXT* ctx: Threading context.
@@ -51,6 +55,10 @@ Transformation setup
         char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"};
         PJ* P = proj_create_argv(0, 3, args);
 
+    If creation of the transformation object fails, the function returns `0` and
+    the PROJ error number is updated. The error number can be read with
+    :c:func:`proj_errno` or :c:func:`proj_context_errno`.
+
     The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
 
     :param PJ_CONTEXT* ctx: Threading context
@@ -81,6 +89,11 @@ Transformation setup
 
         PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0);
 
+    If creation of the transformation object fails, the function returns `0` and
+    the PROJ error number is updated. The error number can be read with
+    :c:func:`proj_errno` or :c:func:`proj_context_errno`.
+
+
     The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
 
     :param PJ_CONTEXT* ctx: Threading context.
@@ -212,12 +225,25 @@ Error reporting
 
     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.
+    transformation. In cases :c:data:`P` is `0` the error number of the default
+    context is read. A text representation of the error number can be retrieved
+    with :c:func:`proj_errno_string`.
 
     :param: PJ* P: Transformation object.
 
     :returns: :c:type:`int`
 
+.. c:function:: int proj_context_errno(PJ_CONTEXT *ctx)
+
+    Get a reading of the current error-state of :c:data:`ctx`. An non-zero error
+    codes indicates an error either with the transformation setup or during a
+    transformation. A text representation of the error number can be retrieved
+    with :c:func:`proj_errno_string`.
+
+    :param: PJ_CONTEXT* ctx: threading context.
+
+    :returns: :c:type:`int`
+
 .. c:function:: void proj_errno_set(PJ *P, int err)
 
 Change the error-state of :c:data:`P` to `err`.
@@ -268,15 +294,14 @@ Change the error-state of :c:data:`P` to `err`.
 
 .. c:function:: const char* proj_errno_string(int err)
 
+    .. versionadded:: 5.1.0
+
     Get a text representation of an error number.
 
     :param int err: Error number.
 
     :returns: :c:type:`const char*` String with description of error.
 
-    .. note:: Available from version 5.1.0.
-
-
 Logging
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -551,7 +576,7 @@ Various
 
 .. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir)
 
-   Check if an operation returns angular output.
+    Check if an operation returns angular output.
 
     :param `P`: Transformation object
     :type `P`: const PJ*

docs/source/download.rst

@@ -13,23 +13,29 @@ distribution of the source code and various resource files archives. See
 Current Release
 --------------------------------------------------------------------------------
 
-* **2018-04-01** `proj-5.0.1.tar.gz`_ (`md5`_)
-* **2018-03-01** `proj-datumgrid-1.7.zip`_
-* **2018-03-01** `proj-datumgrid-europe-1.0.zip`_
-* **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_
+* **2018-09-15** `proj-5.2.0.tar.gz`_ (`md5`_)
+* **2018-09-15** `proj-datumgrid-1.8.zip`_
+* **2018-09-15** `proj-datumgrid-europe-1.1.zip`_
+* **2018-09-15** `proj-datumgrid-north-america-1.1.zip`_
 * **2018-03-01** `proj-datumgrid-oceania-1.0.zip`_
-* **PDF Manual** `proj.pdf`_
 
 Past Releases
 --------------------------------------------------------------------------------
 
+* **2018-06-01** `proj-5.1.0.tar.gz`_
+* **2018-04-01** `proj-5.0.1.tar.gz`_
 * **2018-03-01** `proj-5.0.0.tar.gz`_
 * **2016-09-02** `proj-4.9.3.tar.gz`_
 * **2015-09-13** `proj-4.9.2.tar.gz`_
 * **2015-03-04** `proj-4.9.1.tar.gz`_
 
 * **2016-09-11** `proj-datumgrid-1.6.zip`_
+* **2018-03-01** `proj-datumgrid-1.7.zip`_
+* **2018-03-01** `proj-datumgrid-europe-1.0.zip`_
+* **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_
 
+.. _`proj-5.2.0.tar.gz`: http://download.osgeo.org/proj/proj-5.2.0.tar.gz
+.. _`proj-5.1.0.tar.gz`: http://download.osgeo.org/proj/proj-5.1.0.tar.gz
 .. _`proj-5.0.1.tar.gz`: http://download.osgeo.org/proj/proj-5.0.1.tar.gz
 .. _`proj-5.0.0.tar.gz`: http://download.osgeo.org/proj/proj-5.0.0.tar.gz
 .. _`proj-4.9.1.tar.gz`: http://download.osgeo.org/proj/proj-4.9.1.tar.gz
@@ -37,8 +43,10 @@ Past Releases
 .. _`proj-4.9.3.tar.gz`: http://download.osgeo.org/proj/proj-4.9.3.tar.gz
 .. _`proj-datumgrid-1.6.zip`: http://download.osgeo.org/proj/proj-datumgrid-1.6.zip
 .. _`proj-datumgrid-1.7.zip`: http://download.osgeo.org/proj/proj-datumgrid-1.7.zip
+.. _`proj-datumgrid-1.8.zip`: http://download.osgeo.org/proj/proj-datumgrid-1.8.zip
 .. _`proj-datumgrid-europe-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.0.zip
+.. _`proj-datumgrid-europe-1.1.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.1.zip
 .. _`proj-datumgrid-north-america-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.0.zip
+.. _`proj-datumgrid-north-america-1.1.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.1.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
-.. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf
+.. _`md5`: http://download.osgeo.org/proj/proj-5.2.0.tar.gz.md5

docs/source/faq.rst

@@ -15,33 +15,23 @@ FAQ
 Where can I find the list of projections and their arguments?
 --------------------------------------------------------------------------------
 
-There is no simple single location to find all the required information. The
-!PostScript/PDF documents listed on the [http://trac.osgeo.org/proj/wiki main]
-PROJ page under documentation are the authoritative source but projections
-and options are spread over several documents in a form more related to their
-order of implementation than anything else.
+:doc:`Here<../operations/projections/index>`.
 
-The '''proj''' command itself can report the list of projections using the
-'''-lp''' option, the list of ellipsoids with the '''-le''' option, the list of
-units with the '''-lu''' option, and the list of built-in datums with the
-'''-ld''' option.
+Additinoally, the ``proj`` command itself can report the list of projections
+using the ``-lp`` option, the list of ellipsoids with the ``-le`` option,
+the list of units with the ``-lu`` option, and the list of built-in datums with
+the ``-ld`` option.
 
-The [http://www.remotesensing.org/geotiff/proj_list/ GeoTIFF Projections Pages]
-include most of the common PROJ projections, and a definition of the
-projection specific options for each.
+How do I do datum shifts between NAD27 and NAD83?
+--------------------------------------------------------------------------------
 
-* How do I do datum shifts between NAD27 and NAD83?
-
-While the '''nad2nad''' program can be used in some cases, the '''cs2cs''' is
-now the preferred mechanism.   The following example demonstrates using the
+Using the ``cs2cs`` application.  The following example demonstrates using the
 default shift parameters for NAD27 to NAD83:
 
-
 ::
 
     % cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 -117 30
 
-
 producing:
 
 ::
@@ -49,8 +39,8 @@ producing:
     117d0'2.901"W   30d0'0.407"N 0.000
 
 In order for datum shifting to work properly the various grid shift files must
-be available.  See below.  More details are available in the
-[wiki:GenParms#nadgrids-GridBasedDatumAdjustments General Parameters] document.
+be available. See below. More details are available in the
+section on :doc:`resource files<resource_files>`.
 
 How do I build/configure PROJ to support datum shifting?
 --------------------------------------------------------------------------------
@@ -64,7 +54,7 @@ On Windows the extra nadshift target must be used.  For instance
 
 A default build and install on Unix will normally build knowledge of the
 directory where the grid shift files are installed into the PROJ library
-(usually /usr/local/share/proj).  On Windows the library is normally built
+(usually ``/usr/local/share/proj``).  On Windows the library is normally built
 thinking that C:\PROJ\NAD is the installed directory for the grid shift files.
 If the built in concept of the PROJ data directory is incorrect, the ``PROJ_LIB``
 environment can be defined with the correct directory.
@@ -72,24 +62,24 @@ environment can be defined with the correct directory.
 How do I debug problems with NAD27/NAD83 datum shifting?
 --------------------------------------------------------------------------------
 
-1. Verify that you have the binary files (eg. /usr/local/share/proj/conus)
+1. Verify that you have the binary files (eg. ``/usr/local/share/proj/conus``)
    installed on your system.  If not, see the previous question.
-2. Try a datum shifting operation in relative isolation, such as with the cs2cs
+2. Try a datum shifting operation in relative isolation, such as with the :program:`cs2cs`
    command listed above.  Do you get reasonable results?  If not it is likely
    the grid shift files aren't being found.  Perhaps you need to define
-   PROJ_LIB?
-3. The cs2cs command and the underlying pj_transform() API know how to do a
+   :envvar:`PROJ_LIB`?
+3. The :program:`cs2cs` command and the underlying :c:func:`pj_transform()` API know how to do a
    grid shift as part of a more complex coordinate transformation; however, it
    is imperative that both the source and destination coordinate system be
    defined with appropriate datum information.  That means that implicitly or
-   explicitly there must be a +datum= clause, a +nadgrids= clause or a
-   +towgs84= clause.  For instance
+   explicitly there must be a ``+datum=`` clause, a ``+nadgrids=`` clause or a
+   ``+towgs84=`` clause.  For instance
    ``cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +ellps=WGS84`` won't work because defining the output
    coordinate system as using the ellipse WGS84 isn't the same as defining it
-   to use the datum WGS84 (use +datum=WGS84).  If either the input or output
+   to use the datum WGS84 (use ``+datum=WGS84``).  If either the input or output
    are not identified as having a datum, the datum shifting (and ellipsoid
    change) step is just quietly skipped!
-4. The ``PROJ_DEBUG`` environment can be defined (any value) to force extra output
+4. The :envvar:`PROJ_DEBUG` environment can be defined (any value) to force extra output
    from the PROJ library to stderr (the text console normally) with
    information on what data files are being opened and in some cases why a
    transformation fails.
@@ -103,16 +93,16 @@ How do I debug problems with NAD27/NAD83 datum shifting?
    .. note::
         ``PROJ_DEBUG`` support is not yet very mature in the PROJ library.
 
-5. The ``-v`` flag to cs2cs can be useful in establishing more detail on what
+5. The :option:`-v` flag to :program:`cs2cs` can be useful in establishing more detail on what
    parameters being used internally for a coordinate system.  This will include
-   expanding the definition of +datum clause.
+   expanding the definition of ``+datum`` clause.
 
 How do I use EPSG coordinate system codes with PROJ?
 --------------------------------------------------------------------------------
 
-There is somewhat imperfect translation between 2d geographic and projected
+There is somewhat imperfect translation between 2D geographic and projected
 coordinate system codes and PROJ descriptions of the coordinate system
-available in the epsg definition file that normally lives in the proj/nad
+available in the ``epsg`` definition file that normally lives in the ``proj/nad``
 directory.  If installed (it is installed by default on Unix), it is possible
 to use EPSG numbers like this:
 
@@ -136,26 +126,28 @@ to use EPSG numbers like this:
 The proj/nad/epsg file can be browsed and searched in a text editor for
 coordinate systems.  There are known to be problems with some coordinate
 systems, and any coordinate systems with odd axes, a non-greenwich prime
-meridian or other quirkiness are unlikely to work properly.  Caveat Emptor!
+meridian or other quirkiness are unlikely to work properly. Caveat Emptor!
 
 How do I use 3 parameter and 7 parameter datum shifting
 --------------------------------------------------------------------------------
 
-Datum shifts can be approximated with 3 and 7 parameter transformations.  Their
-use is more fully described in the
-[wiki:GenParms#towgs84-DatumtransformationtoWGS84 towgs84] parameter
-discussion.
+Datum shifts can be approximated with 3 and 7 parameter transformations. Their
+use with :program:`cs2cs` is more fully described in the
+:ref:`geodetic tranformation<cs2cs_specific_options>` section.
+
+More generically, the :ref:`helmert` can be used with :program:`cct`.
+
 
 Does PROJ work in different international numeric locales?
 --------------------------------------------------------------------------------
 
-No.  PROJ makes extensive use of sprintf() and atof() internally to translate
-numeric values.  If a locale is in effect that modifies formatting of numbers,
-altering the role of commas and periods in numbers, then PROJ will not work.
-This problem is common in some European locales.
+No. PROJ makes extensive use of the :c:func:`sprintf()` and :c:func:`atof()` C functions
+internally to translate numeric values.  If a locale is in effect that modifies
+formatting of numbers, altering the role of commas and periods in numbers, then
+PROJ will not work. This problem is common in some European locales.
 
-On unix-like platforms, this problem can be avoided by forcing the use of the
-default numeric locale by setting the LC_NUMERIC environment variable to C.
+On UNIX-like platforms, this problem can be avoided by forcing the use of the
+default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable to C.
 
 ::
 
@@ -189,7 +181,7 @@ But, if you do something like:
                        +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs
 
 to convert between WGS84 and mercator on the sphere there will be substantial
-shifts in the Y mercator coordinates.  This is because internally cs2cs is
+shifts in the Y mercator coordinates.  This is because internally :program:`cs2cs` is
 having to adjust the lat/long coordinates from being on the sphere to being on
 the WGS84 datum which has a quite differently shaped ellipsoid.
 
@@ -207,7 +199,7 @@ your spherical lat/long coordinates to WGS84.
         +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 \
         +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs
 
-Note the strategic addition of +nadgrids=@null to the spherical projection
+Note the strategic addition of ``+nadgrids=@null`` to the spherical projection
 definition.
 
 Similar issues apply with many other datasets distributed with projections
@@ -215,7 +207,7 @@ 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 string will be preserved
-in the WKT representation (otherwise key parameters like `+nadgrids=@null` will
+in the WKT representation (otherwise key parameters like ``+nadgrids=@null`` will
 be dropped):
 
 ::
@@ -223,17 +215,6 @@ be dropped):
     +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0
                +units=m +nadgrids=@null +wktext  +no_defs
 
-Why do I get different results with 4.5.0 and 4.6.0?
---------------------------------------------------------------------------------
-
-The default datum application behavior changed with the 4.6.0 release.  PROJ
-will now only apply a datum shift if both the source and destination coordinate
-system have valid datum shift information.
-
-From the PROJ 4.6.0 Release Notes (in NEWS):
- * MAJOR: Rework pj_transform() to avoid applying ellipsoid to ellipsoid
-   transformations as a datum shift when no datum info is available.
-
 
 How do I calculate distances/directions on the surface of the earth?
 --------------------------------------------------------------------------------
@@ -241,80 +222,18 @@ How do I calculate distances/directions on the surface of the earth?
 These are called geodesic calculations. There is a page about it here:
 :ref:`geodesic`.
 
-What is the HEALPix projection and how can I use it?
---------------------------------------------------------------------------------
-
-.. figure::
-    ../images/rhealpix.png
-    :scale: 40%
-    :align: left
-
-The HEALPix projection is area preserving and can be used with a
-spherical and ellipsoidal model.  It was initially developed for mapping cosmic
-background microwave radiation.  The image below is the graphical
-representation of the mapping and consists of eight isomorphic triangular
-interrupted map graticules.  The north and south contains four in which
-straight meridians converge polewards to a point and unequally spaced
-horizontal parallels.  HEALPix provides a mapping in which points of equal
-latitude and equally spaced longitude are mapped to points of equal latitude
-and equally spaced longitude with the module of the polar interruptions. ||
-
-To run a forward HEALPix projection on a unit sphere model, use the following command:
-
-::
-
-    proj +proj=healpix +lon_0=0 +a=1 -E <<EOF
-    0 0
-    EOF
-
-Output of the above command.
-
-::
-
-    0 0 0.00 0.00
-
-What is the rHEALPix projection and how can I use it?
---------------------------------------------------------------------------------
-
-.. figure::
-    ../images/healpix.png
-    :scale: 40%
-    :align: left
-
-rHEALPix is a projection based on the HEALPix projection.  The implementation
-of rHEALPix uses the HEALPix projection.  The rHEALPix combines the peaks of
-the HEALPix into a square.  The square's position can be translated and rotated
-across the x-axis which is a novel approach for the rHEALPix projection.  The
-initial intention of using rHEALPix in the Spatial Computation Engine Science
-Collaboration Environment (SCENZGrid).
-
-To run a inverse rHEALPix projection on a WGS84 ellipsoidal model, use the following command:
-
-::
-
-    proj +proj=rhealpix -f '%.2f' -I +lon_0=0 +a=1 +ellps=WGS84 +npole=0 +spole=0 -E <<EOF
-    0 0.7853981633974483
-    EOF
-
-Where spole and npole are integers from the range of 0 to 3 inclusive and represent the positions of the north polar and south polar squares.
-
-Output of above command:
-
-::
-
-    0 0.7853981633974483 0.00 41.94
 
 What options does PROJ allow for the shape of the Earth (geodesy)?
 --------------------------------------------------------------------------------
 
-See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c
+See https://github.com/OSGeo/proj.4/blob/5.2/src/pj_ellps.c
 for possible ellipse options. For example, putting ``+ellps=WGS84`` uses
 the ``WGS84`` Earth shape.
 
 What if I want a spherical Earth?
 --------------------------------------------------------------------------------
 
-Use ``+ellps=sphere``.  See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c
+Use ``+ellps=sphere``.  See https://github.com/OSGeo/proj.4/blob/5.2/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 for work on Mars?

docs/source/geodesic.rst

@@ -152,10 +152,11 @@ catalog of those cases:
 Background
 ----------
 
-The algorithms implemented by this package are given in [Karney2013]_
-and are based on [Bessel1825]_ and [Helmert1880]_; the algorithm for
-areas is based on [Danielsen1989]_.  These improve on the work of
-[Vincenty1975]_ in the following respects:
+The algorithms implemented by this package are given in :cite:`Karney2013`
+(`addenda <https://geographiclib.sourceforge.io/geod-addenda.html>`_)
+and are based on :cite:`Bessel1825` and :cite:`Helmert1880`; the algorithm for
+areas is based on :cite:`Danielsen1989`.  These improve on the work of
+:cite:`Vincenty1975` in the following respects:
 
 * The results are accurate to round-off for terrestrial ellipsoids (the
   error in the distance is less then 15 nanometers, compared to 0.1 mm
@@ -166,5 +167,8 @@ areas is based on [Danielsen1989]_.  These improve on the work of
   geodesic.  This allows, for example, the area of a geodesic polygon to
   be computed.
 
-Additional background material is provided in [GeodesicBib]_,
-[GeodesicWiki]_, and [Karney2011]_.
+Additional background material is provided in GeographicLib's `geodesic
+bibliography <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_,
+Wikipedia's article "`Geodesics on an ellipsoid
+<https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid>`_", and :cite:`Karney2011`
+(`errata <https://geographiclib.sourceforge.io/geod-addenda.html#geod-errata>`_).

docs/source/index.rst

@@ -8,6 +8,7 @@ PROJ
    :hidden:
 
    about
+   news
    download
    install
    usage/index
@@ -23,305 +24,24 @@ PROJ
 
 .. 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.
-
-    .. attention::
-
-        With the introduction of PROJ 5, behavioural changes has been made to
-        existing functionality. Consult :ref:`differences` for the details.
-
-
-
-    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>`_)
-
-    * Fixed memory leak in General Oblique Transformation. (`#497 <https://github.com/OSGeo/proj.4/issues/497>`_)
-
-    * Equations for meridian convergence and partial derivatives have
-      been corrected for non-conformal projections. (`#526 <https://github.com/OSGeo/proj.4/issues/526>`_)
-
-    * 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>`_
+    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.
+
+    You can download the source code for PROJ on the :ref:`download section<download>`
+    and find links to prepackaged executables in the
+    :ref:`installation section<install>`.

docs/source/install.rst

@@ -32,7 +32,7 @@ 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 pull osgeo/proj
 
 .. _`Docker`: https://docker.org
 .. _`DockerHub`: https://hub.docker.com/r/osgeo/proj.4/

docs/source/news.rst

@@ -0,0 +1,397 @@
+.. _news:
+
+News
+###############################################################################
+
+PROJ 5.2.0
+++++++++++++++++++++++++++++++++++++++++
+*September 15th 2018*
+
+UPDATES
+-------
+
+* Added support for deg, rad and grad in unitconvert (`#1054 <https://github.com/OSGeo/proj.4/issues/1054>`_)
+
+* Assume :option:`+t_epoch` as time input when not otherwise specified (`#1065 <https://github.com/OSGeo/proj.4/issues/1065>`_)
+
+* Added inverse Lagrange projection (`#1058 <https://github.com/OSGeo/proj.4/issues/1058>`_)
+
+* Added :option:`+multiplier` option to vgridshift (`#1072 <https://github.com/OSGeo/proj.4/issues/1072>`_)
+
+* Added Equal Earth projection (`#1085 <https://github.com/OSGeo/proj.4/issues/1085>`_)
+
+* Added "require_grid" option to gie (`#1088 <https://github.com/OSGeo/proj.4/issues/1088>`_)
+
+* Replace :option:`+transpose` option of Helmert transform with :option:`+convention`.
+  From now on the convention used should be explicitly written. An
+  error will be returned when using the +transpose option (`#1091 <https://github.com/OSGeo/proj.4/issues/1091>`_)
+
+* Improved numerical precision of inverse spherical Mercator
+  projection (`#1105 <https://github.com/OSGeo/proj.4/issues/1105>`_)
+
+* :program:`cct` will now forward text after coordinate input to output
+  stream (`#1111 <https://github.com/OSGeo/proj.4/issues/1111>`_)
+
+
+BUG FIXES
+------------
+
+* Do not pivot over WGS84 when doing cs2cs-emulation with geocent (`#1026 <https://github.com/OSGeo/proj.4/issues/1026>`_)
+
+* Do not scan past the end of the read data in :c:func:`pj_ctx_fgets` (`#1042 <https://github.com/OSGeo/proj.4/issues/1042>`_)
+
+* Make sure :c:func:`proj_errno_string()` is available in DLL (`#1050 <https://github.com/OSGeo/proj.4/issues/1050>`_)
+
+* Respect `+to_meter` setting when doing cs2cs-emulation (`#1053 <https://github.com/OSGeo/proj.4/issues/1053>`_)
+
+* Fixed unit conversion factors for :program:`geod` (`#1075 <https://github.com/OSGeo/proj.4/issues/1075>`_)
+
+* Fixed test failures related to GCC 8 (`#1084 <https://github.com/OSGeo/proj.4/issues/1084>`_)
+
+* Improved handling of `+geoc` flag (`#1093 <https://github.com/OSGeo/proj.4/issues/1093>`_)
+
+* Calculate correct projection factors for Webmercator (`#1095 <https://github.com/OSGeo/proj.4/issues/1095>`_)
+
+* :program:`cs2cs` now always outputs degrees when transformed coordinates are
+  in angular units (`#1112 <https://github.com/OSGeo/proj.4/issues/1112>`_)
+
+
+PROJ 5.1.0
+++++++++++++++++++++++++++++++++++++++++
+*June 1st 2018*
+
+
+UPDATES
+-------
+
+* Function :c:func:`proj_errno_string()` added to ``proj.h`` API (`#847 <https://github.com/OSGeo/proj.4/issues/847>`_)
+
+* Validate units between pipeline steps and ensure transformation
+  sanity (`#906 <https://github.com/OSGeo/proj.4/issues/906>`_)
+
+* Print help when calling :program:`cct` and :program:`gie` without arguments (`#907 <https://github.com/OSGeo/proj.4/issues/907>`_)
+
+* `CITATION` file added to source distribution (`#914 <https://github.com/OSGeo/proj.4/issues/914>`_)
+
+* Webmercator operation added (`#925 <https://github.com/OSGeo/proj.4/issues/925>`_)
+
+* Enhanced numerical precision of forward spherical Mercator near
+  the Equator (`#928 <https://github.com/OSGeo/proj.4/issues/928>`_)
+
+* Added ``--skip-lines`` option to :program:`cct` (`#923 <https://github.com/OSGeo/proj.4/issues/923>`_)
+
+* Consistently return ``NaN`` values on ``NaN`` input (`#949 <https://github.com/OSGeo/proj.4/issues/949>`_)
+
+* Removed unused ``src/org_proj4_Projections.h`` file (`#956 <https://github.com/OSGeo/proj.4/issues/956>`_)
+
+* Java Native Interface bindings updated (`#957 <https://github.com/OSGeo/proj.4/issues/957>`_, `#969 <https://github.com/OSGeo/proj.4/issues/969>`_)
+
+* Horizontal and vertical gridshift operations extended to
+  the temporal domain (`#1015 <https://github.com/OSGeo/proj.4/issues/1015>`_)
+
+
+BUG FIXES
+------------
+
+* Handle ``NaN`` float cast overflow in ``PJ_robin.c`` and ``nad_intr.c`` (`#887 <https://github.com/OSGeo/proj.4/issues/887>`_)
+
+* Avoid overflow when Horner order is unreasonably large (`#893 <https://github.com/OSGeo/proj.4/issues/893>`_)
+
+* Avoid unwanted NaN conversions in etmerc (`#899 <https://github.com/OSGeo/proj.4/issues/899>`_)
+
+* Avoid memory failure in :program:`gie` when not specifying x,y,z in gie files (`#902 <https://github.com/OSGeo/proj.4/issues/902>`_)
+
+* Avoid memory failure when :option:`+sweep` is initialized incorrectly in geos (`#908 <https://github.com/OSGeo/proj.4/issues/908>`_)
+
+* Return ``HUGE_VAL`` on erroneous input in ortho (`#912 <https://github.com/OSGeo/proj.4/issues/912>`_)
+
+* Handle commented lines correctly in cct (`#933 <https://github.com/OSGeo/proj.4/issues/933>`_)
+
+* Avoid segmentation fault when transformation coordinates outside grid
+  area in deformation (`#934 <https://github.com/OSGeo/proj.4/issues/934>`_)
+
+* Avoid doing false easting/northing adjustments on cartesian
+  coordinates (`#936 <https://github.com/OSGeo/proj.4/issues/936>`_)
+
+* Thread-safe creation of proj mutex (`#954 <https://github.com/OSGeo/proj.4/issues/954>`_)
+
+* Avoid errors when setting up geos with +lat_0!=0 (`#986 <https://github.com/OSGeo/proj.4/issues/986>`_)
+
+* Reset errno when running :program:`proj` in verbose mode (`#988 <https://github.com/OSGeo/proj.4/issues/988>`_)
+
+* Do not interpolate node values at nodata value in vertical
+  grid shifts (`#1004 <https://github.com/OSGeo/proj.4/issues/1004>`_)
+
+* Restrict Horner degrees to positive integer values to avoid
+  memory allocation issues (`#1005 <https://github.com/OSGeo/proj.4/issues/1005>`_)
+
+
+
+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>`_)
+
+* Fixed memory leak in General Oblique Transformation. (`#497 <https://github.com/OSGeo/proj.4/issues/497>`_)
+
+* Equations for meridian convergence and partial derivatives have
+  been corrected for non-conformal projections. (`#526 <https://github.com/OSGeo/proj.4/issues/526>`_)
+
+* 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>`_

docs/source/operations/conversions/cart.rst

@@ -1,23 +1,36 @@
 .. _cart:
 
 ================================================================================
-Cartesian to geodetic conversion
+Geodetic to cartesian conversion
 ================================================================================
 
 .. versionadded:: 5.0.0
 
-Convert geodetic coordinates to cartesian coordinates.
+Convert geodetic coordinates to cartesian coordinates (in the forward path).
 
 +---------------------+--------------------------------------------------------+
 | **Alias**           | cart                                                   |
 +---------------------+--------------------------------------------------------+
 | **Domain**          | 3D                                                     |
 +---------------------+--------------------------------------------------------+
-| **Input type**      | Cartesian coordinates                                  |
+| **Input type**      | Geodetic coordinates                                   |
 +---------------------+--------------------------------------------------------+
-| **Output type**     | Cartesian coordinates                                  |
+| **Output type**     | Geocentric cartesian coordinates                       |
 +---------------------+--------------------------------------------------------+
 
+This conversion converts geodetic coordinate values (longitude, latitude,
+elevation above ellipsoid) to their geocentric (X, Y, Z) representation, where
+the first axis (X) points from the Earth centre to the point of longitude=0,
+latitude=0, the second axis (Y) points from the Earth centrer to the point of
+longitude=90, latitude=0 and the third axis (Z) points to the North pole.
+
+Usage
+################################################################################
+
+Convert geodetic coordinates to GRS80 cartesian coordinates::
+
+    echo 17.7562015132 45.3935192042 133.12 2017.8 | cct +proj=cart +ellps=GRS80
+    4272922.1553   1368283.0597  4518261.3501     2017.8000
 
 Parameters
 ################################################################################

docs/source/operations/conversions/geoc.rst

@@ -0,0 +1,75 @@
+.. _geoc:
+
+================================================================================
+Geocentric Latitude
+================================================================================
+
+.. versionadded:: 5.0.0
+
+Convert from Geodetic Latitude to Geocentric Latitude (in the forward path).
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | geoc                                                   |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 2D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                   |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Geocentric angular coordinates                         |
++---------------------+--------------------------------------------------------+
+
+The geodetic (or geographic) latitude (also called planetographic latitude
+in the context of non-Earth bodies) is the angle between the equatorial plane
+and the normal (vertical) to the ellipsoid surface at the considered point.
+The geodetic latitude is what is normally used everywhere in PROJ when angular
+coordinates are expected or produced.
+
+The geocentric latitude (also called planetocentric latitude in the context of
+non-Earth bodies) is the angle between the equatorial plane and a line joining
+the body centre to the considered point.
+
+.. image:: ./images/geocentric_latitude.png
+   :align: center
+   :scale: 100%
+   :alt:   Geocentric latitude
+
+
+.. note::
+
+    This conversion must be distinguished fom the :ref:`cart`
+    which converts geodetic coordinates to geocentric coordinates in the cartesian
+    domain.
+
+Mathematical definition
+#######################
+
+The formulas describing the conversion are taken from :cite:`Snyder1987`
+(equation 3-28)
+
+Let :math:`\phi'` to be the geocentric latitude and :math:`\phi`  the
+geodetic latitude, then
+
+.. math::
+
+  \phi' = \arctan \left[ (1 - e^2) \tan \left( \phi \right) \right]
+
+The geocentric latitude is consequently lesser (in absolute value) than the geodetic
+latitude, except at the equator and the poles where they are equal.
+
+On a sphere, they are always equal.
+
+Usage
+################################################################################
+
+Converting from geodetic latitude to geocentric latitude::
+
+    +proj=geoc +ellps=GRS80
+
+Converting from geocentric latitude to geodetic latitude::
+
+    +proj=pipeline +step +proj=geoc +inv +ellps=GRS80
+
+Parameters
+################################################################################
+
+.. include:: ../options/ellps.rst

docs/source/operations/conversions/images/geocentric_latitude.svg

@@ -0,0 +1,222 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="140mm"
+   height="80mm"
+   viewBox="0 0 496.06299 283.46457"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="geocentric_latitude.svg"
+   inkscape:export-filename="/home/even/geocentric_latitude.png"
+   inkscape:export-xdpi="90"
+   inkscape:export-ydpi="90">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.4"
+     inkscape:cx="-24.364532"
+     inkscape:cy="179.59147"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1920"
+     inkscape:window-height="1004"
+     inkscape:window-x="0"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Calque 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-147.57144,-187.04048)">
+    <ellipse
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:2;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="path3336"
+       cx="360"
+       cy="335.21933"
+       rx="210"
+       ry="118.57143" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 150.01742,328.40826 419.30163,-0.75019"
+       id="path3338"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.96771652px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 363.32468,217.04313 0.16174,236.75597"
+       id="path3340"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 362.28019,328.82684 500.94901,247.46623"
+       id="path3342"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 444.633,218.67689 110.86424,56.316"
+       id="path3346"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 458.01752,327.77337 70.2056,-130.05715"
+       id="path3348"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 504.232,242.92055 5.05076,2.27284 -2.77792,4.79823"
+       id="path3350"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 478.21428,328.07649 c 0,0 3.34873,-9.57295 -10.49045,-17.89492"
+       id="path4172"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.71625429px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 381.31112,328.6754 c 0,0 1.06694,-7.99101 -5.65105,-7.9116"
+       id="path4172-3"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 468.62412,315.90407 -0.75761,-5.55584 5.80838,-0.25253"
+       id="path4189"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 376.70024,324.23783 0.25254,-3.78807 5.3033,-0.25254"
+       id="path4191"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="458.19504"
+       y="341.07974"
+       id="text4193"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4195"
+         x="458.19504"
+         y="341.07974">Geodetic</tspan><tspan
+         sodipodi:role="line"
+         x="458.19504"
+         y="356.70474"
+         id="tspan4197">latitude</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:15px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="366.77863"
+       y="341.95016"
+       id="text4193-6"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4195-7"
+         x="366.77863"
+         y="341.95016"
+         style="font-size:12.5px">Geocentric</tspan><tspan
+         sodipodi:role="line"
+         x="366.77863"
+         y="357.57516"
+         id="tspan4197-5"
+         style="font-size:12.5px">latitude</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:15px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="478.72565"
+       y="317.92438"
+       id="text4220"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4222"
+         x="478.72565"
+         y="317.92438">φ</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:15px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="394.50311"
+       y="322.51547"
+       id="text4220-3"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4222-5"
+         x="394.50311"
+         y="322.51547">φ'</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="159.38527"
+       y="340.53079"
+       id="text4193-62"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         x="159.38527"
+         y="340.53079"
+         id="tspan4197-1">Equatorial plane</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:12.5px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="331.11118"
+       y="209.21098"
+       id="text4193-62-2"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         x="331.11118"
+         y="209.21098"
+         id="tspan4197-1-0">North pole</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-weight:normal;font-size:10px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       x="526.23138"
+       y="211.77133"
+       id="text4193-62-9"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         x="526.23138"
+         y="211.77133"
+         id="tspan4197-1-3">Normal to</tspan><tspan
+         sodipodi:role="line"
+         x="526.23138"
+         y="224.27133"
+         id="tspan4306">the ellipsoid</tspan><tspan
+         sodipodi:role="line"
+         x="526.23138"
+         y="236.77133"
+         id="tspan4308">surface</tspan></text>
+  </g>
+</svg>

docs/source/operations/conversions/index.rst

@@ -13,5 +13,6 @@ conversions.
 
    axisswap
    cart
+   geoc
    latlon
    unitconvert

docs/source/operations/conversions/unitconvert.rst

@@ -6,7 +6,7 @@ Unit conversion
 
 .. versionadded:: 5.0.0
 
-Convert between various distance and time units.
+Convert between various distance, angular and time units.
 
 +---------------------+--------------------------------------------------------+
 | **Alias**           | unitconvert                                            |
@@ -27,7 +27,7 @@ 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=tmerc +lat_0=42.5 +lon_0=-72.5 +k_0=0.999964286 +x_0=500000.00001016 +y_0=0
     +step +proj=unitconvert +xy_in=m +xy_out=us-ft
 
 Often when working with GNSS data the timestamps are presented in GPS-weeks,
@@ -35,30 +35,38 @@ 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=unitconvert +t_in=gps_week +t_out=decimalyear
     +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ...
 
 Parameters
 ################################################################################
 
-.. option:: +xy_in=<unit>
+.. option:: +xy_in=<unit> or <conversion_factor>
 
-    Horizontal input units. See :ref:`distance_units` for a list of available
+    Horizontal input units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units. `<conversion_factor>` is the conversion factor
+    from the input unit to metre for linear units, or to radian for angular
     units.
 
-.. option:: +xy_out=<unit>
+.. option:: +xy_out=<unit> or <conversion_factor>
 
-    Horizontal output units. See :ref:`distance_units` for a list of available
+    Horizontal output units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units. `<conversion_factor>` is the conversion factor
+    from the output unit to metre for linear units, or to radian for angular
     units.
 
-.. option:: +z_in=<unit>
+.. option:: +z_in=<unit> or <conversion_factor>
 
-    Vertical output units. See :ref:`distance_units` for a list of available
+    Vertical output units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units. `<conversion_factor>` is the conversion factor
+    from the input unit to metre for linear units, or to radian for angular
     units.
 
-.. option:: +z_out=<unit>
+.. option:: +z_out=<unit> or <conversion_factor>
 
-    Vertical output units. See :ref:`distance_units` for a list of available
+    Vertical output units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units.  `<conversion_factor>` is the conversion factor
+    from the output unit to metre for linear units, or to radian for angular
     units.
 
 .. option:: +t_in=<unit>
@@ -74,7 +82,7 @@ Parameters
 Distance units
 ###############################################################################
 
-In the table below all distance units supported by PROJ is listed.
+In the table below all distance units supported by PROJ are listed.
 The same list can also be produced on the command line with :program:`proj` or
 :program:`cs2cs`, by adding the `-lu` flag when calling the utility.
 
@@ -124,12 +132,31 @@ The same list can also be produced on the command line with :program:`proj` or
 | ind-ch   | Indian Chain                    |
 +----------+---------------------------------+
 
+.. _angular_units:
+
+Angular units
+###############################################################################
+
+.. versionadded:: 5.2.0
+
+In the table below all angular units supported by PROJ `unitconvert` are listed.
+
++----------+---------------------------------+
+| **Label**| **Name**                        |
++----------+---------------------------------+
+|    deg   | Degree                          |
++----------+---------------------------------+
+|   grad   | Grad                            |
++----------+---------------------------------+
+|    rad   | Radian                          |
++----------+---------------------------------+
+
 .. _time_units:
 
 Time units
 ###############################################################################
 
-In the table below all time units supported by PROJ is listed.
+In the table below all time units supported by PROJ are listed.
 
 +--------------+-----------------------------+
 | **label**    | **Name**                    |

docs/source/operations/projections/aea.rst

@@ -20,10 +20,13 @@ Albers Equal Area
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/aea.png
-   :scale: 50%
+.. figure:: ./images/aea.png
+   :width: 500 px
+   :align: center
    :alt:   Albers Equal Area
 
+   proj-string: ``+proj=aea``
+
 Options
 ################################################################################
 

docs/source/operations/projections/aeqd.rst

@@ -18,10 +18,13 @@ Azimuthal Equidistant
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/aeqd.png
-   :scale: 50%
+.. figure:: ./images/aeqd.png
+   :width: 500 px
+   :align: center
    :alt:   Azimuthal Equidistant
 
+   proj-string: ``+proj=aeqd``
+
 
 Options
 ################################################################################

docs/source/operations/projections/airy.rst

@@ -26,10 +26,13 @@ within the small or great circle defined by an angular distance,
 
 
 
-.. image:: ./images/airy.png
-   :scale: 50%
+.. figure:: ./images/airy.png
+   :width: 500 px
+   :align: center
    :alt:   Airy
 
+   proj-string: ``+proj=airy``
+
 Options
 ################################################################################
 

docs/source/operations/projections/aitoff.rst

@@ -19,10 +19,13 @@ Aitoff
 | **Output type**     | Projected coordinates                                    |
 +---------------------+----------------------------------------------------------+
 
-.. image:: ./images/aitoff.png
-   :scale: 50%
+.. figure:: ./images/aitoff.png
+   :width: 500 px
+   :align: center
    :alt:   Aitoff
 
+   proj-string: ``+proj=aitoff``
+
 Parameters
 ################################################################################
 

docs/source/operations/projections/alsk.rst

@@ -20,10 +20,13 @@ Modified Stererographics of Alaska
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/alsk.png
-   :scale: 50%
+.. figure:: ./images/alsk.png
+   :width: 500 px
+   :align: center
    :alt:   Mod. Stererographics of Alaska
 
+   proj-string: ``+proj=alsk``
+
 Options
 ################################################################################
 
@@ -34,5 +37,3 @@ Options
 .. include:: ../options/y_0.rst
 
 .. include:: ../options/ellps.rst
-
-.. include:: ../options/R.rst

docs/source/operations/projections/apian.rst

@@ -21,10 +21,13 @@ Apian Globular I
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/apian.png
-   :scale: 50%
+.. figure:: ./images/apian.png
+   :width: 500 px
+   :align: center
    :alt:   Apian Globular I
 
+   proj-string: ``+proj=apian``
+
 Options
 ################################################################################
 

docs/source/operations/projections/august.rst

@@ -4,7 +4,22 @@
 August Epicycloidal
 ********************************************************************************
 
-.. image:: ./images/august.png
-   :scale: 50%
-   :alt:   August Epicycloidal  
+.. figure:: ./images/august.png
+   :width: 500 px
+   :align: center
+   :alt:   August Epicycloidal
 
+   proj-string: ``+proj=august``
+
+Parameters
+################################################################################
+
+.. note:: All options are optional for the August Epicycloidal projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/bacon.rst

@@ -4,7 +4,22 @@
 Bacon Globular
 ********************************************************************************
 
-.. image:: ./images/bacon.png
-   :scale: 50%
-   :alt:   Bacon Globular  
+.. figure:: ./images/bacon.png
+   :width: 500 px
+   :align: center
+   :alt:   Bacon Globular
 
+   proj-string: ``+proj=bacon``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Bacon Globular projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/bipc.rst

@@ -4,7 +4,26 @@
 Bipolar conic of western hemisphere
 ********************************************************************************
 
-.. image:: ./images/bipc.png
-   :scale: 50%
-   :alt:   Bipolar conic of western hemisphere  
+.. figure:: ./images/bipc.png
+   :width: 500 px
+   :align: center
+   :alt:   Bipolar conic of western hemisphere
 
+   proj-string: ``+proj=bipc +ns``
+
+Parameters
+################################################################################
+
+.. note:: All options are optional for the Bipolar Conic projection.
+
+.. option:: +ns
+
+    Return non-skewed cartesian coordinates.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/boggs.rst

@@ -4,7 +4,22 @@
 Boggs Eumorphic
 ********************************************************************************
 
-.. image:: ./images/boggs.png
-   :scale: 50%
-   :alt:   Boggs Eumorphic  
+.. figure:: ./images/boggs.png
+   :width: 500 px
+   :align: center
+   :alt:   Boggs Eumorphic
 
+   proj-string: ``+proj=boggs``
+
+Parameters
+################################################################################
+
+.. note:: All options are optional for the Boggs Eumorphic projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/bonne.rst

@@ -4,7 +4,30 @@
 Bonne (Werner lat_1=90)
 ********************************************************************************
 
-.. image:: ./images/bonne.png
-   :scale: 50%
-   :alt:   Bonne (Werner lat_1=90)  
+.. figure:: ./images/bonne.png
+   :width: 500 px
+   :align: center
+   :alt:   Bonne (Werner lat_1=90)
 
+   proj-string: ``+proj=bonne +lat_1=10``
+
+Parameters
+################################################################################
+
+Required
+--------------------------------------------------------------------------------
+
+.. include:: ../options/lat_1.rst
+
+Optional
+--------------------------------------------------------------------------------
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/calcofi.rst

@@ -26,7 +26,7 @@ California Cooperative Oceanic Fisheries Investigations program, known as CalCOF
 
 
 .. image:: ../../../images/calcofi.png
-   :scale: 50%
+   :width: 500 px
    :align: center
    :alt:   Cal Coop Ocean Fish Invest Lines/Stations
 
@@ -82,8 +82,8 @@ Options
 Mathematical definition
 ################################################################################
 
-The algorithm used to make conversions is described in [EberHewitt1979]_ with
-a few corrections reported in [WeberMoore2013]_.
+The algorithm used to make conversions is described in :cite:`EberHewitt1979` with
+a few corrections reported in :cite:`WeberMoore2013`.
 
 
 Further reading

docs/source/operations/projections/cass.rst

@@ -23,14 +23,17 @@ Although the Cassini projection has been largely replaced by the Transverse Merc
 +---------------------+-------------------------------------------------------------------------+
 
 
-.. image:: ./images/cass.png
-   :scale: 50%
+.. figure:: ./images/cass.png
+   :width: 500 px
+   :align: center
    :alt:   Cassini
 
+   proj-string: ``+proj=cass``
+
 Usage
 #####
 
-There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century [Steers1970]_.
+There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century :cite:`Steers1970`.
 Many of these maps were prepared at a scale of 1:2,500.
 The Cassini-Soldner was also used for the detailed mapping of many German states during the same period.
 
@@ -67,7 +70,7 @@ Options
 Mathematical definition
 #######################
 
-The formulas describing the Cassini projection are taken from Snyder's [Snyder1987]_.
+The formulas describing the Cassini projection are taken from :cite:`Snyder1987`.
 
 :math:`\phi_0` is the latitude of origin that match the center of the map (default to 0). It can be set with ``+lat_0``.
 
@@ -162,5 +165,4 @@ Further reading
 ###############
 
 #. `Wikipedia <https://en.wikipedia.org/wiki/Equirectangular_projection>`_
-#. [Snyder1987]_
 #. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas  <http://www.ihsenergy.com/epsg/guid7.pdf>`_

docs/source/operations/projections/cc.rst

@@ -4,7 +4,22 @@
 Central Cylindrical
 ********************************************************************************
 
-.. image:: ./images/cc.png
-   :scale: 50%
-   :alt:   Central Cylindrical  
+.. figure:: ./images/cc.png
+   :width: 500 px
+   :align: center
+   :alt:   Central Cylindrical
 
+   proj-string: ``+proj=cc``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Central Cylindricla projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/ccon.rst

@@ -26,10 +26,12 @@ latitude, identical with ``conic()`` projection from ``mapproj`` R package.
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/ccon.png
-   :scale: 50%
+.. figure:: ./images/ccon.png
+   :width: 500 px
+   :align: center
    :alt:   Central Conic
 
+   proj-string: ``+proj=ccon +lat_1=52 +lon_0=19``
 
 Usage
 ########
@@ -39,7 +41,7 @@ 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
+Jagiellonian University, Krakow, Poland in 1970s :cite:`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
@@ -51,7 +53,7 @@ The ATPOL coordinates can be achieved with with the following parameters:
 
    +proj=ccon +lat_1=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000
 
-For more information see [Komsta2016]_ and [Verey2017]_.
+For more information see :cite:`Komsta2016` and :cite:`Verey2017`.
 
 Parameters
 ################################################################################

docs/source/operations/projections/cea.rst

@@ -4,7 +4,28 @@
 Equal Area Cylindrical
 ********************************************************************************
 
-.. image:: ./images/cea.png
-   :scale: 50%
-   :alt:   Equal Area Cylindrical  
+.. figure:: ./images/cea.png
+   :width: 500 px
+   :align: center
+   :alt:   Equal Area Cylindrical
 
+   proj-string: ``+proj=cea``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Equal Area Cylindrical projection.
+
+.. include:: ../options/lat_ts.rst
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/k_0.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/chamb.rst

@@ -4,7 +4,50 @@
 Chamberlin Trimetric
 ********************************************************************************
 
-.. image:: ./images/chamb.png
-   :scale: 50%
-   :alt:   Chamberlin Trimetric  
+.. figure:: ./images/chamb.png
+   :width: 500 px
+   :align: center
+   :alt:   Chamberlin Trimetric
 
+   proj-string: ``+proj=chamb +lat_1=10 +lon_1=30 +lon_2=40``
+
+Parameters
+################################################################################
+
+Required
+--------------------------------------------------------------------------------
+
+.. option:: +lat_1=<value>
+
+    Latitude of the first control point.
+
+.. option:: +lon_1=<value>
+
+    Longitude of the first control point.
+
+.. option:: +lat_2=<value>
+
+    Latitude of the second control point.
+
+.. option:: +lon_2=<value>
+
+    Longitude of the second control point.
+
+.. option:: +lat_3=<value>
+
+    Latitude of the third control point.
+
+.. option:: +lon_3=<value>
+
+    Longitude of the third control point.
+
+Optional
+--------------------------------------------------------------------------------
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/collg.rst

@@ -4,7 +4,23 @@
 Collignon
 ********************************************************************************
 
-.. image:: ./images/collg.png
-   :scale: 50%
-   :alt:   Collignon  
+.. figure:: ./images/collg.png
+   :width: 500 px
+   :align: center
+   :alt:   Collignon
+
+   proj-string: ``+proj=collg``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Collignon projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst
 

docs/source/operations/projections/crast.rst

@@ -4,7 +4,23 @@
 Craster Parabolic (Putnins P4)
 ********************************************************************************
 
-.. image:: ./images/crast.png
-   :scale: 50%
-   :alt:   Craster Parabolic (Putnins P4)  
+.. figure:: ./images/crast.png
+   :width: 500 px
+   :align: center
+   :alt:   Craster Parabolic (Putnins P4)
+
+   proj-string: ``+proj=crast``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Craster Parabolic projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst
 

docs/source/operations/projections/denoy.rst

@@ -4,7 +4,22 @@
 Denoyer Semi-Elliptical
 ********************************************************************************
 
-.. image:: ./images/denoy.png
-   :scale: 50%
-   :alt:   Denoyer Semi-Elliptical  
+.. figure:: ./images/denoy.png
+   :width: 500 px
+   :align: center
+   :alt:   Denoyer Semi-Elliptical
 
+   proj-string: ``+proj=denoy``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Denoyer Semi-Elliptical projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eck1.rst

@@ -4,10 +4,13 @@
 Eckert I
 ********************************************************************************
 
-.. image:: ./images/eck1.png
-   :scale: 50%
+.. figure:: ./images/eck1.png
+   :width: 500 px
+   :align: center
    :alt:   Eckert I
 
+   proj-string: ``+proj=eck1``
+
 
 .. math::
 
@@ -15,4 +18,15 @@ Eckert I
 
     y &= 2 \sqrt{2/3\pi}\phi
 
+Parameters
+################################################################################
 
+.. note:: All parameters are optional for the Eckert I projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eck2.rst

@@ -4,7 +4,22 @@
 Eckert II
 ********************************************************************************
 
-.. image:: ./images/eck2.png
-   :scale: 50%
-   :alt:   Eckert II  
+.. figure:: ./images/eck2.png
+   :width: 500 px
+   :align: center
+   :alt:   Eckert II
 
+   proj-string: ``+proj=eck2``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Eckert II projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eck3.rst

@@ -4,7 +4,22 @@
 Eckert III
 ********************************************************************************
 
-.. image:: ./images/eck3.png
-   :scale: 50%
-   :alt:   Eckert III  
+.. figure:: ./images/eck3.png
+   :width: 500 px
+   :align: center
+   :alt:   Eckert III
 
+   proj-string: ``+proj=eck3``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Eckert III projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eck4.rst

@@ -4,10 +4,12 @@
 Eckert IV
 ********************************************************************************
 
-.. image:: ./images/eck4.png
-   :scale: 50%
+.. figure:: ./images/eck4.png
+   :width: 500 px
+   :align: center
    :alt:   Eckert IV
 
+   proj-string: ``+proj=eck4``
 
 .. math::
 
@@ -16,4 +18,15 @@ Eckert IV
 .. math::
     y = 2 \phi / \sqrt { 2 + \pi }
 
+Parameters
+################################################################################
 
+.. note:: All parameters are optional for the Eckert IV projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eck5.rst

@@ -4,7 +4,22 @@
 Eckert V
 ********************************************************************************
 
-.. image:: ./images/eck5.png
-   :scale: 50%
-   :alt:   Eckert V  
+.. figure:: ./images/eck5.png
+   :width: 500 px
+   :align: center
+   :alt:   Eckert V
 
+   proj-string: ``+proj=eck5``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Eckert V projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eck6.rst

@@ -4,7 +4,22 @@
 Eckert VI
 ********************************************************************************
 
-.. image:: ./images/eck6.png
-   :scale: 50%
-   :alt:   Eckert VI  
+.. figure:: ./images/eck6.png
+   :width: 500 px
+   :align: center
+   :alt:   Eckert VI
 
+   proj-string: ``+proj=eck6``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Eckert VI projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eqc.rst

@@ -23,10 +23,13 @@ The simplest of all projections. Standard parallels (0° when omitted) may be sp
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/eqc.png
-   :scale: 50%
+.. figure:: ./images/eqc.png
+   :width: 500 px
+   :align: center
    :alt:   Equidistant Cylindrical (Plate Carrée)
 
+   proj-string: ``+proj=eqc``
+
 Usage
 ########
 
@@ -89,7 +92,7 @@ Parameters
 Mathematical definition
 #######################
 
-The formulas describing the Equidistant Cylindrical projection are all taken from Snyder's [Snyder1987]_.
+The formulas describing the Equidistant Cylindrical projection are all taken from :cite:`Snyder1987`.
 
 :math:`\phi_{ts}` is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set with ``+lat_ts``.
 

docs/source/operations/projections/eqdc.rst

@@ -4,7 +4,32 @@
 Equidistant Conic
 ********************************************************************************
 
-.. image:: ./images/eqdc.png
-   :scale: 50%
-   :alt:   Equidistant Conic  
+.. figure:: ./images/eqdc.png
+   :width: 500 px
+   :align: center
+   :alt:   Equidistant Conic
 
+   proj-string: ``+proj=eqdc +lat_1=55 +lat_2=60``
+
+Parameters
+################################################################################
+
+Required
+--------------------------------------------------------------------------------
+
+.. include:: ../options/lat_1.rst
+
+.. include:: ../options/lat_2.rst
+
+Optional
+--------------------------------------------------------------------------------
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/eqearth.rst

@@ -0,0 +1,68 @@
+.. _eqearth:
+
+********************************************************************************
+Equal Earth
+********************************************************************************
+
+.. versionadded:: 5.2.0
+
++---------------------+-----------------------------------------------------------+
+| **Classification**  | Pseudo cylindrical                                        |
++---------------------+-----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical and ellipsoidal projection |
++---------------------+-----------------------------------------------------------+
+| **Defined area**    | Global                                                    |
++---------------------+-----------------------------------------------------------+
+| **Alias**           | eqearth                                                   |
++---------------------+-----------------------------------------------------------+
+| **Domain**          | 2D                                                        |
++---------------------+-----------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                      |
++---------------------+-----------------------------------------------------------+
+| **Output type**     | Projected coordinates                                     |
++---------------------+-----------------------------------------------------------+
+
+
+
+.. figure:: ./images/eqearth.png
+   :width: 500 px
+   :align: center
+   :alt:   Equal Earth
+
+   proj-string: ``+proj=eqearth``
+
+
+The Equal Earth projection is intended for making world maps. Equal Earth is a 
+projection inspired by the Robinson projection, but unlike
+the Robinson projection retains the relative size of areas. The projection
+was designed in 2018 by Bojan Savric, Tom Patterson and Bernhard Jenny :cite:`Savric2018`.
+
+
+Usage
+###############################################################################
+
+The Equal Earth projection has no special options. Here is
+an example of an forward projection on a sphere with a radius of 1 m::
+
+    $ echo 122 47 | src/proj +proj=eqearth +R=1
+    1.55	0.89
+
+Parameters
+################################################################################
+
+.. note:: All parameters for the projection are optional.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst
+
+Further reading
+################################################################################
+
+#. Bojan Savric, Tom Patterson & Bernhard Jenny (2018). `The Equal Earth map projection <https://www.researchgate.net/profile/Bojan_Savric2/publication/326879978_The_Equal_Earth_map_projection/links/5b69d0ae299bf14c6d951b77/The-Equal-Earth-map-projection.pdf>`_, International Journal of Geographical Information Science

docs/source/operations/projections/etmerc.rst

@@ -4,7 +4,29 @@
 Extended Transverse Mercator
 ********************************************************************************
 
-.. image:: ./images/etmerc.png
-   :scale: 50%
-   :alt:   Extended Transverse Mercator  
+.. figure:: ./images/etmerc.png
+   :width: 500 px
+   :align: center
+   :alt:   Extended Transverse Mercator
+
+   proj-string: ``+proj=etmerc +lon_0=-40``
+
+Parameters
+################################################################################
+
+.. note:: All parameters for the projection are optional.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/lat_0.rst
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/k_0.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst
 

docs/source/operations/projections/euler.rst

@@ -4,7 +4,31 @@
 Euler
 ********************************************************************************
 
-.. image:: ./images/euler.png
-   :scale: 50%
-   :alt:   Euler  
+.. figure:: ./images/euler.png
+   :width: 500 px
+   :align: center
+   :alt:   Euler
 
+   proj-string: ``+proj=euler +lat_1=67 +lat_2=75``
+
+
+Parameters
+################################################################################
+
+Required
+--------------------------------------------------------------------------------
+
+.. include:: ../options/lat_1.rst
+
+.. include:: ../options/lat_2.rst
+
+Optional
+--------------------------------------------------------------------------------
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/fahey.rst

@@ -4,7 +4,22 @@
 Fahey
 ********************************************************************************
 
-.. image:: ./images/fahey.png
-   :scale: 50%
-   :alt:   Fahey  
+.. figure:: ./images/fahey.png
+   :width: 500 px
+   :align: center
+   :alt:   Fahey
 
+   proj-string: ``+proj=fahey``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Fahey projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/fouc.rst

@@ -4,7 +4,22 @@
 Foucaut
 ********************************************************************************
 
-.. image:: ./images/fouc.png
-   :scale: 50%
-   :alt:   Foucaut  
+.. figure:: ./images/fouc.png
+   :width: 500 px
+   :align: center
+   :alt:   Foucaut
 
+   proj-string: ``+proj=fouc``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Foucaut projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/fouc_s.rst

@@ -4,10 +4,13 @@
 Foucaut Sinusoidal
 ********************************************************************************
 
-.. image:: ./images/fouc_s.png
-   :scale: 50%
+.. figure:: ./images/fouc_s.png
+   :width: 500 px
+   :align: center
    :alt:   Foucaut Sinusoidal
 
+   proj-string: ``+proj=fouc_s``
+
 
 The `y`-axis is based upon a weighted mean of the cylindrical equal-area and
 the sinusoidal projections. Parameter :math:`n=n` is the weighting factor where
@@ -23,3 +26,21 @@ For the inverse, the Newton-Raphson method can be used to determine
 :math:`\phi` from the equation for :math:`y` above. As :math:`n \rightarrow 0` and
 :math:`\phi \rightarrow \pi/2`, convergence is slow but for :math:`n = 0`, :math:`\phi =
 \sin^1y`
+
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Foucaut Sinusoidal projection.
+
+.. option:: +n=<value>
+
+    Weighting factor. Value should be in the interval 0-1.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/gall.rst

@@ -24,10 +24,13 @@ It is neither equal-area nor conformal but instead tries to balance the distorti
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/gall.png
-   :scale: 50%
+.. figure:: ./images/gall.png
+   :width: 500 px
+   :align: center
    :alt:   Gall (Gall Stereographic)
 
+   proj-string: ``+proj=gall``
+
 Usage
 #####
 
@@ -69,7 +72,7 @@ Parameters
 Mathematical definition
 #######################
 
-The formulas describing the Gall Stereographical are all taken from Snyder's [Snyder1993]_.
+The formulas describing the Gall Stereographical are all taken from :cite:`Snyder1993`.
 
 Spherical form
 **************

docs/source/operations/projections/geos.rst

@@ -24,10 +24,12 @@ scanning angle intervals.
 +---------------------+----------------------------------------------------------+
 
 
-.. image:: ./images/geos.png
-   :scale: 50%
+.. figure:: ./images/geos.png
+   :width: 500 px
+   :align: center
    :alt:   Geostationary Satellite View
 
+   proj-string: ``+proj=geos +h=35785831.0 +lon_0=-60 +sweep=y``
 
 Usage
 ###############################################################################
@@ -54,7 +56,8 @@ 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
-   :scale: 50%
+   :width: 500 px
+   :align: center
    :alt:   Gimbal geometry
 
 In the image above, the outer-gimbal axis, or sweep-angle axis, is the N/S axis (``y``)
@@ -66,8 +69,8 @@ E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle
 
 The sweep argument is used to tell PROJ 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.
+scanning geometry of the Meteosat series satellite should take sweep as y, and
+GOES should take sweep as x.
 
 Parameters
 ################################################################################

docs/source/operations/projections/gins8.rst

@@ -4,7 +4,22 @@
 Ginsburg VIII (TsNIIGAiK)
 ********************************************************************************
 
-.. image:: ./images/gins8.png
-   :scale: 50%
-   :alt:   Ginsburg VIII (TsNIIGAiK)  
+.. figure:: ./images/gins8.png
+   :width: 500 px
+   :align: center
+   :alt:   Ginsburg VIII (TsNIIGAiK)
 
+   proj-string: ``+proj=gins8``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Ginsburg VIII projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/gn_sinu.rst

@@ -4,7 +4,23 @@
 General Sinusoidal Series
 ********************************************************************************
 
-.. image:: ./images/gn_sinu.png
-   :scale: 50%
-   :alt:   General Sinusoidal Series  
+.. figure:: ./images/gn_sinu.png
+   :width: 500 px
+   :align: center
+   :alt:   General Sinusoidal Series
 
+   proj-string: ``+proj=gn_sinu +m=2 +n=3``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the General Sinusoidal Series
+          projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/gnom.rst

@@ -4,7 +4,22 @@
 Gnomonic
 ********************************************************************************
 
-.. image:: ./images/gnom.png
-   :scale: 50%
-   :alt:   Gnomonic  
+.. figure:: ./images/gnom.png
+   :width: 500 px
+   :align: center
+   :alt:   Gnomonic
 
+   proj-string: ``+proj=gnom +lat_0=90 +lon_0=-50``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Gnomomic projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/goode.rst

@@ -4,7 +4,22 @@
 Goode Homolosine
 ********************************************************************************
 
-.. image:: ./images/goode.png
-   :scale: 50%
-   :alt:   Goode Homolosine  
+.. figure:: ./images/goode.png
+   :width: 500 px
+   :align: center
+   :alt:   Goode Homolosine
 
+   proj-string: ``+proj=goode``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the Goode Homolosine projection.
+
+.. include:: ../options/lon_0.rst
+
+.. include:: ../options/R.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/gs48.rst

@@ -4,7 +4,20 @@
 Mod. Stererographics of 48 U.S.
 ********************************************************************************
 
-.. image:: ./images/gs48.png
-   :scale: 50%
+.. figure:: ./images/gs48.png
+   :width: 500 px
+   :align: center
    :alt:   Mod. Stererographics of 48 U.S.  
 
+   proj-string: ``+proj=gs48``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the projection.
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst

docs/source/operations/projections/gs50.rst

@@ -4,7 +4,20 @@
 Mod. Stererographics of 50 U.S.
 ********************************************************************************
 
-.. image:: ./images/gs50.png
-   :scale: 50%
-   :alt:   Mod. Stererographics of 50 U.S.  
+.. figure:: ./images/gs50.png
+   :width: 500 px
+   :align: center
+   :alt:   Mod. Stererographics of 50 U.S.
 
+   proj-string: ``+proj=gs50``
+
+Parameters
+################################################################################
+
+.. note:: All parameters are optional for the projection.
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst