Merge remote-tracking branch 'osgeo/master' into doc-improvements

16 files changed, 290 insertions, 26 deletions

diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
index b82d2881..4e612939 100644
--- a/docs/source/_static/theme_overrides.css
+++ b/docs/source/_static/theme_overrides.css
@@ -55,3 +55,16 @@ div.math {
     overflow-x: auto;
     overflow-y: hidden;
 }
+
+/* Override style of versionmodified directives */
+.versionadded {
+    font-style: italic;
+}
+
+.versionchanged {
+    font-style: italic;
+}
+
+.deprecated {
+    font-style: italic;
+}
diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst
index dc2944f2..20aec06c 100644
--- a/docs/source/apps/cct.rst
+++ b/docs/source/apps/cct.rst
@@ -44,6 +44,13 @@ The following control parameters can  appear  in any order:
 
     Specify a fixed observation height to be used for all input data.
 
+.. option:: s <n>, --skip-lines=<n>
+
+    .. versionadded:: 5.1.0
+
+    Skip the first *n* lines of input. This applies to any kind of input, wether
+    it comes from ``STDIN``, a file or interactive user input.
+
 .. option:: -v, --verbose
 
     Write non-essential, but potentially useful, information to stderr.
diff --git a/docs/source/apps/gie.rst b/docs/source/apps/gie.rst
index eee0e22d..777c5833 100644
--- a/docs/source/apps/gie.rst
+++ b/docs/source/apps/gie.rst
@@ -260,6 +260,46 @@ gie command language
 
     See ``gie -l`` for a list of error codes that can be ignored.
 
+.. option:: echo <text>
+
+    Add user defined text to the output stream. See the example below.
+
+    .. code-block:: console
+
+        <gie>
+        echo ** Mercator projection tests **
+        operation +proj=merc
+        accept  0   0
+        expect  0   0
+        </gie>
+
+    which returns
+
+    .. code-block:: console
+
+        -------------------------------------------------------------------------------
+        Reading file 'test.gie'
+        ** Mercator projection test **
+        -------------------------------------------------------------------------------
+        total:  1 tests succeeded,  0 tests skipped,  0 tests failed.
+        -------------------------------------------------------------------------------
+
+.. option:: skip
+
+    Skip any test after the first occurence of :option:`skip`. In the example below only
+    the first test will be performed. The second test is skipped. This feature is mostly
+    relevant for debugging when writing new test cases.
+
+    .. code-block:: console
+
+        <gie>
+        operation proj=merc
+        accept  0   0
+        expect  0   0
+        skip
+        accept  0   1
+        expect  0   110579.9
+        </gie>
 
 Background
 **********
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 3a93fb81..b57e0f36 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# PROJ.4 documentation build configuration file, created by
+# PROJ documentation build configuration file, created by
 # sphinx-quickstart on Wed Feb 24 10:47:15 2016.
 #
 # This file is execfile()d with the current directory set to its
@@ -48,19 +48,24 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'PROJ.4'
+
+# Keep legacy project name
+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)
-author = u'Gerald Evenden, Frank Warmerdam, and others'
 
 # 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.
-#
-# The short X.Y version.
-version = u'5.0.0'
-# The full version, including alpha/beta/rc tags.
-release = u'5.0.0'
+version = '5.0.1'
+
+# use same |release| as |version|
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -97,6 +102,9 @@ exclude_patterns = []
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# Specify default language for syntax highlighting.
+highlight_language = 'none'
+
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
@@ -211,12 +219,15 @@ html_show_sourcelink = False
 #html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'proj4doc'
+htmlhelp_basename = 'projdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
 
 preamble = r"""
+\ifdefined\DeclareUnicodeCharacter
+  \DeclareUnicodeCharacter{2032}{$'$}% prime
+\fi
 """
 
 latex_elements = {
@@ -228,7 +239,7 @@ latex_elements = {
 
 # Additional stuff for the LaTeX preamble.
 'preamble': preamble,
-'inputenc':'\usepackage[utf8x]{inputenc}'
+'inputenc':'\usepackage[utf8]{inputenc}'
 
 # Latex figure (float) alignment
 #'figure_align': 'htbp',
@@ -238,8 +249,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'proj4.tex', u'PROJ.4 Documentation',
-     u'Gerald Evenden', 'manual', False),
+    (master_doc, 'proj.tex', title, author, 'manual'),
 ]
 
 latex_toplevel_sectioning = 'chapter'
@@ -317,8 +327,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'proj4', u'PROJ.4 Documentation',
-     author, 'proj4', 'One line description of project.',
+    (master_doc, 'proj', title, author, 'proj',
+     'Cartographic projections software library.',
      'Miscellaneous'),
 ]
 
diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst
index 8966923a..2a335a15 100644
--- a/docs/source/development/reference/datatypes.rst
+++ b/docs/source/development/reference/datatypes.rst
@@ -744,3 +744,53 @@ Info structures
     .. c:member:: char PJ_INIT_INFO.lastupdate
 
         Date of last update of the init-file.
+
+
+Logging
+-------------------------------------------------------------------------------
+
+.. c:type:: PJ_LOG_LEVEL
+
+    Enum of logging levels in PROJ. Used to set the logging level in PROJ.
+    Usually using :c:func:`proj_log_level`.
+
+    .. c:member:: PJ_LOG_NONE
+
+        Don't log anything.
+
+    .. c:member:: PJ_LOG_ERROR
+
+        Log only errors.
+
+    .. c:member:: PJ_LOG_DEBUG
+
+        Log errors and additional debug information.
+
+    .. c:member:: PJ_LOG_TRACE
+
+        Highest logging level. Log everything including very detailed debug
+        information.
+
+    .. c:member:: PJ_LOG_TELL
+
+        Special logging level that when used in :c:func:`proj_log_level`
+        will return the current logging level set in PROJ.
+
+    .. versionadded:: 5.1.0
+
+.. c:type:: PJ_LOG_FUNC
+
+    Function prototype for the logging function used by PROJ.
+    Defined as
+
+    .. code-block:: C
+
+        typedef void (*PJ_LOG_FUNCTION)(void *, int, const char *);
+
+    where the :c:type:`void` pointer references a data structure used by the
+    calling application, the :c:type:`int` is used to set the logging level
+    and the :c:type:`const char` pointer is the string that will be logged
+    by the function.
+
+
+    .. versionadded:: 5.1.0
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index 3d141ae2..52f801e5 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -276,6 +276,34 @@ Change the error-state of :c:data:`P` to `err`.
 
     .. note:: Available from version 5.1.0.
 
+
+Logging
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. c:function::  PJ_LOG_LEVEL proj_log_level (PJ_CONTEXT *ctx, PJ_LOG_LEVEL level)
+
+    Get and set logging level for a given context. Changes the log level to
+    :c:data:`level` and returns the previous logging level. If called with
+    :c:data:`level` set to :c:type:`PJ_LOG_TELL` the function returns the current
+    logging level without changing it.
+
+    :param PJ_CONTEXT* ctx: Threading context.
+    :param PJ_LOG_LEVEL level: New logging level.
+
+    :returns: :c:type:`PJ_LOG_LEVEL`
+
+    .. versionadded:: 5.1.0
+
+.. c:function::  void proj_log_func (PJ_CONTEXT *ctx, void *app_data, PJ_LOG_FUNCTION logf)
+
+    Override the internal log function of PROJ.
+
+    :param PJ_CONTEXT* ctx: Threading context.
+    :param void* app_data: Pointer to data structure used by the calling application.
+    :param PJ_LOG_FUNCTION logf: Log function that overrides the PROJ log function.
+
+    .. versionadded:: 5.1.0
+
 Info functions
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
diff --git a/docs/source/download.rst b/docs/source/download.rst
index 784bb756..d7c60d63 100644
--- a/docs/source/download.rst
+++ b/docs/source/download.rst
@@ -15,7 +15,7 @@ Release Notes
 Current Release
 --------------------------------------------------------------------------------
 
-* **2018-03-01** `proj-5.0.0.tar.gz`_ (`md5`_)
+* **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`_
@@ -24,12 +24,14 @@ Current Release
 Past Releases
 --------------------------------------------------------------------------------
 
+* **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`_
 
+.. _`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
 .. _`proj-4.9.2.tar.gz`: http://download.osgeo.org/proj/proj-4.9.2.tar.gz
@@ -39,7 +41,7 @@ Past Releases
 .. _`proj-datumgrid-europe-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.0.zip
 .. _`proj-datumgrid-north-america-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.0.zip
 .. _`proj-datumgrid-oceania-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip
-.. _`md5`: http://download.osgeo.org/proj/proj-5.0.0.tar.gz.md5
+.. _`md5`: http://download.osgeo.org/proj/proj-5.0.1.tar.gz.md5
 
 Binaries
 --------------------------------------------------------------------------------
diff --git a/docs/source/geodesic.rst b/docs/source/geodesic.rst
index d54212ca..8f6f5bbe 100644
--- a/docs/source/geodesic.rst
+++ b/docs/source/geodesic.rst
@@ -10,8 +10,8 @@ Geodesic calculations
 Introduction
 ------------
 
-Consider a ellipsoid of revolution with equatorial radius :math:`a`, polar
-semi-axis :math:`b`, and flattening :math:`f=(a−b)/a`.  Points on
+Consider an ellipsoid of revolution with equatorial radius :math:`a`, polar
+semi-axis :math:`b`, and flattening :math:`f=(a-b)/a`.  Points on
 the surface of the ellipsoid are characterized by their latitude :math:`\phi`
 and longitude :math:`\lambda`.  (Note that latitude here means the
 *geographical latitude*, the angle between the normal to the ellipsoid
diff --git a/docs/source/index.rst b/docs/source/index.rst
index bf8e1c90..72bf1600 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -27,8 +27,10 @@ own software. PROJ is maintained on `GitHub <http://github.com/OSGeo/proj.4/>`_.
     .. |coverals| image:: https://coveralls.io/repos/OSGeo/proj.4/badge.svg?branch=master
                         :target: https://coveralls.io/r/OSGeo/proj.4?branch=master
 
-Full documentation is available as a single PDF at
-https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj4.pdf
+.. only:: not latex
+
+   Full documentation is available as a single PDF at
+   https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf
 
 Documentation
 =================
diff --git a/docs/source/operations/conversions/unitconvert.rst b/docs/source/operations/conversions/unitconvert.rst
index 50ac832c..bc422afb 100644
--- a/docs/source/operations/conversions/unitconvert.rst
+++ b/docs/source/operations/conversions/unitconvert.rst
@@ -109,4 +109,6 @@ In the table below all time units supported by PROJ is listed.
 +--------------+-----------------------------+
 | gps_week     | GPS Week                    |
 +--------------+-----------------------------+
+| yyyymmdd     | Date in yyyymmdd format     |
++--------------+-----------------------------+
 
diff --git a/docs/source/operations/projections/aeqd.rst b/docs/source/operations/projections/aeqd.rst
index 32165e49..d4baa8b6 100644
--- a/docs/source/operations/projections/aeqd.rst
+++ b/docs/source/operations/projections/aeqd.rst
@@ -12,7 +12,10 @@ Azimuthal Equidistant
 +---------------------+----------------------------------------------------------+
 | **Options**                                                                    |
 +---------------------+----------------------------------------------------------+
-| `+guam`             |  Use Guam elliptical formulas. Defaults to false.        |
+| `+guam`             | Use Guam elliptical formulas. Only accurate near the     |
+|                     | Island of Guam (:math:`\lambda\approx 144.5^{\circ}`,    |
+|                     | :math:`\phi\approx 13.5^{\circ}`)                        |
+|                     | Defaults to false.                                       |
 +---------------------+----------------------------------------------------------+
 
 
diff --git a/docs/source/operations/projections/airy.rst b/docs/source/operations/projections/airy.rst
index d2730592..eefda4e9 100644
--- a/docs/source/operations/projections/airy.rst
+++ b/docs/source/operations/projections/airy.rst
@@ -3,6 +3,11 @@
 ********************************************************************************
 Airy
 ********************************************************************************
+
+The Airy projection is an azimuthal minimum error projection for the region
+within the small or great circle defined by an angular distance,
+:math:`\phi_b`, from the tangency point of the plane :math:`( \lambda_0, \phi_0 )`.
+
 +---------------------+----------------------------------------------------------+
 | **Classification**  |                                                          |
 +---------------------+----------------------------------------------------------+
@@ -14,7 +19,10 @@ Airy
 +---------------------+----------------------------------------------------------+
 | **Options**                                                                    |
 +---------------------+----------------------------------------------------------+
-| `+lat_b`            |                                                          |
+| `+lat_b`            | Angular distance from tangency point of the plane        |
+|                     | :math:`( \lambda_0, \phi_0 )` where the error is kept at |
+|                     | minimum. Defaults to :math:`90^{\circ}` which is         |
+|                     | suitable for hemispherical maps.                         |
 +---------------------+----------------------------------------------------------+
 | `+no_cut`           | Do not cut at hemisphere limit                           |
 +---------------------+----------------------------------------------------------+
diff --git a/docs/source/operations/projections/eqc.rst b/docs/source/operations/projections/eqc.rst
index be431977..5833bd61 100644
--- a/docs/source/operations/projections/eqc.rst
+++ b/docs/source/operations/projections/eqc.rst
@@ -64,9 +64,8 @@ Example using EPSG 32662 (WGS84 Plate Carrée)::
 
 Example using Plate Carrée projection with true scale at latitude 30° and central meridian 90°W::
 
-    $ echo -88 30 | proj +proj=eqc +lat_ts=30 +lat_0=90w
-    -8483684.61     13358338.90
-
+    $ echo -88 30 | proj +proj=eqc +lat_ts=30 +lon_0=90w
+    192811.01       3339584.72
 
 Mathematical definition
 #######################
diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst
index 9255d9fd..77decd6c 100644
--- a/docs/source/operations/projections/index.rst
+++ b/docs/source/operations/projections/index.rst
@@ -141,6 +141,7 @@ Projections map the spherical 3D space to a flat 2D space.
    wag5
    wag6
    wag7
+   webmerc
    weren
    wink1
    wink2
diff --git a/docs/source/operations/projections/nsper.rst b/docs/source/operations/projections/nsper.rst
index 4a8651fc..d204305b 100644
--- a/docs/source/operations/projections/nsper.rst
+++ b/docs/source/operations/projections/nsper.rst
@@ -4,7 +4,28 @@
 Near-sided perspective
 ********************************************************************************
 
+The near-sided perspective projection simulates a view from a height
+:math:`h` similar to how a satellite in orbit would see it.
+
++---------------------+-------------------------------------------------------------+
+| **Classification**  | Azimuthal. Neither conformal nor equal area.                |
++---------------------+-------------------------------------------------------------+
+| **Available forms** | Forward and inverse spherical projection                    |
++---------------------+-------------------------------------------------------------+
+| **Defined area**    | Global, although for one hemisphere at a time.              |
++---------------------+-------------------------------------------------------------+
+| **Options**                                                                       |
++---------------------+-------------------------------------------------------------+
+| `+h`                | Height of the view point above the Earth and must be in     |
+|                     | the same units as the radius of the sphere. Required.       |
++---------------------+-------------------------------------------------------------+
+| `+lat_0`            | Latitude (in degrees) of the view position. Defaults to 0.  |
++---------------------+-------------------------------------------------------------+
+| `+lon_0`            | Longitude (in degrees) of the view position. Defaults to 0. |
++---------------------+-------------------------------------------------------------+
+
+
 .. image:: ./images/nsper.png
    :scale: 50%
-   :alt:   Near-sided perspective  
+   :alt:   Near-sided perspective
 
diff --git a/docs/source/operations/projections/webmerc.rst b/docs/source/operations/projections/webmerc.rst
new file mode 100644
index 00000000..0c465afc
--- /dev/null
+++ b/docs/source/operations/projections/webmerc.rst
@@ -0,0 +1,78 @@
+.. _webmerc:
+
+********************************************************************************
+Web Mercator / Pseudo Mercator
+********************************************************************************
+
+The Web Mercator / Pseudo Mercator projection is a cylindrical map projection.
+This is a variant of the regular :ref:`merc` projection, except that the computation
+is done on a sphere, using the semi-major axis of the ellipsoid.
+
+From `Wikipedia <https://en.wikipedia.org/wiki/Web_Mercator>`_:
+
+    This projection is widely used by the Web Mercator, Google Web Mercator,
+    Spherical Mercator, WGS 84 Web Mercator[1] or WGS 84/Pseudo-Mercator is a
+    variant of the Mercator projection and is the de facto standard for Web
+    mapping applications. [...]
+    It is used by virtually all major online map providers [...]
+    Its official EPSG identifier is EPSG:3857, although others have been used
+    historically.
+
+
++---------------------+----------------------------------------------------------+
+| **Classification**  | Cylindrical (non conformant if used with ellipsoid)      |
++---------------------+----------------------------------------------------------+
+| **Version**         | Added in proj 5.1.0                                      |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical projection                |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global, but best used near the equator                   |
++---------------------+----------------------------------------------------------+
+| **Options**         | Neither lat_0, lon_0, lat_ts or k_0 should be used.      |
++---------------------+----------------------------------------------------------+
+
+Usage
+########
+
+Example::
+
+    $ echo 2 49 | proj +proj=webmerc +datum=WGS84
+    222638.98       6274861.39
+
+Mathematical definition
+#######################
+
+The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals [Evenden2005]_.
+
+Forward projection
+==================
+
+.. math::
+
+    x = \lambda
+
+.. math::
+
+    y = \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right]
+
+
+Inverse projection
+==================
+
+.. math::
+
+    \lambda = {x}
+
+.. math::
+
+    \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y} \right]
+
+
+
+Further reading
+###############
+
+#. `Wikipedia <https://en.wikipedia.org/wiki/Web_Mercator>`_
+
+
+