From 97d491d8e2d56ce49aca57c6cf6aa3e5d4306598 Mon Sep 17 00:00:00 2001
From: Kristian Evers <kristianevers@gmail.com>
Date: Sat, 17 Mar 2018 21:07:24 +0100
Subject: Move application docs to top level.

The 'Applications' chapter is moved to the top level of the website in
order to make it easier for users to find the pages quickly instead of
having to search through sub-sections in other chapters.
---
 docs/source/apps/cct.rst   | 165 +++++++++++++++++++++++++++++++
 docs/source/apps/cs2cs.rst | 187 +++++++++++++++++++++++++++++++++++
 docs/source/apps/geod.rst  | 214 ++++++++++++++++++++++++++++++++++++++++
 docs/source/apps/index.rst |  21 ++++
 docs/source/apps/proj.rst  | 236 +++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 823 insertions(+)
 create mode 100644 docs/source/apps/cct.rst
 create mode 100644 docs/source/apps/cs2cs.rst
 create mode 100644 docs/source/apps/geod.rst
 create mode 100644 docs/source/apps/index.rst
 create mode 100644 docs/source/apps/proj.rst

(limited to 'docs/source/apps')

diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst
new file mode 100644
index 00000000..9153e29b
--- /dev/null
+++ b/docs/source/apps/cct.rst
@@ -0,0 +1,165 @@
+.. _cct:
+
+================================================================================
+cct
+================================================================================
+
+.. Index:: cct
+
+.. only:: html
+
+    Coordinate Conversion and Transformation.
+
+Synopsis
+********
+
+       **cct** [ **-cotvz** [ args ] ] *+opts[=arg]*  file[s]
+
+Description
+***********
+
+:program:`cct` a 4D equivalent to the :program:`proj` projection program,
+performs transformation coordinate systems on a set of input points.  The
+coordinate system transformation can include  translation  between projected
+and geographic coordinates as well as the application of datum shifts.
+
+
+The following control parameters can  appear  in any order:
+
+.. program:: cct
+
+.. option:: -c <x,y,z,t>
+
+    Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4.
+
+.. option:: -o <output file name>, --output=<output file name>
+
+    Specify the name of the output file.
+
+.. option:: -t <time>, --time=<time>
+
+    Specify a fixed observation time to be used for all input data.
+
+.. option:: -z <height>, --height=<height>
+
+    Specify a fixed observation height to be used for all input data.
+
+.. option:: -v, --verbose
+
+    Write non-essential, but potentially useful, information to stderr.
+    Repeat for additional information (``-vv``, ``-vvv``, etc.)
+
+The *+args* arguments are associated with coordinate operation parameters.
+Usage varies with operation.
+
+.. only:: html
+
+    For a complete description consult the :ref:`projection pages <projections>`.
+
+
+:program:`cct` is an acronym meaning *Coordinate Conversion and Transformation*.
+
+The acronym refers to definitions given in the OGC 08-015r2/ISO-19111
+standard "Geographical Information -- Spatial Referencing by Coordinates",
+which defines two different classes of *coordinate operations*:
+
+*Coordinate Conversions*, which are coordinate operations where input
+and output datum are identical (e.g. conversion from geographical to
+cartesian coordinates) and
+
+*Coordinate Transformations*, which are coordinate operations where
+input and output datums differ (e.g. change of reference frame).
+
+Examples
+********
+
+1. The operator specs describe the action to be performed by :program:`cct`. So
+   the following script
+
+.. code-block:: console
+
+     echo 12 55 0 0 | cct +proj=utm +zone=32 +ellps=GRS80
+
+will transform the input geographic coordinates into UTM zone 32 coordinates.
+Hence, the command
+
+.. code-block:: console
+
+      echo 12 55 | cct -z0 -t0 +proj=utm +zone=32 +ellps=GRS80
+
+Should give results comparable to the classic proj command
+
+.. code-block:: console
+
+      echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80
+
+2. Convert geographical input to UTM zone 32 on the GRS80 ellipsoid:
+
+.. code-block:: console
+
+      cct +proj=utm +ellps=GRS80 +zone=32
+
+3. Roundtrip accuracy check for the case above:
+
+.. code-block:: console
+
+      cct +proj=pipeline +proj=utm +ellps=GRS80 +zone=32 +step +step +inv
+
+4. As (2) but specify input columns for longitude, latitude, height and time:
+
+.. code-block:: console
+
+      cct -c 5,2,1,4  +proj=utm +ellps=GRS80 +zone=32
+
+5. As (2) but specify fixed height and time, hence needing only 2 cols in
+   input:
+
+.. code-block:: console
+
+      cct -t 0 -z 0  +proj=utm  +ellps=GRS80  +zone=32
+
+
+Background
+**********
+
+:program:`cct` also refers to Carl Christian Tscherning (1942--2014),
+professor of Geodesy at the University of Copenhagen, mentor and advisor
+for a generation of Danish geodesists, colleague and collaborator for
+two generations of global geodesists, Secretary General for the
+International Association of Geodesy, IAG (1995--2007), fellow of the
+American Geophysical Union (1991), recipient of the IAG Levallois Medal
+(2007), the European Geosciences Union Vening Meinesz Medal (2008), and
+of numerous other honours.
+
+*cct*, or Christian, as he was known to most of us, was recognized for his
+good mood, his sharp wit, his tireless work, and his great commitment to
+the development of geodesy -- both through his scientific contributions,
+comprising more than 250 publications, and by his mentoring and teaching
+of the next generations of geodesists.
+
+As Christian was an avid Fortran programmer, and a keen Unix connoisseur,
+he would have enjoyed to know that his initials would be used to name a
+modest Unix style transformation filter, hinting at the tireless aspect
+of his personality, which was certainly one of the reasons he accomplished
+so much, and meant so much to so many people.
+
+Hence, in honour of *cct* (the geodesist) this is :program:`cct` (the program).
+
+
+.. only:: man
+
+    See also
+    ********
+
+    **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)**
+
+    Bugs
+    ****
+
+    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    where new bug reports can be submitted to.
+
+    Home page
+    *********
+
+    http://proj4.org/
diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
new file mode 100644
index 00000000..ba77aadf
--- /dev/null
+++ b/docs/source/apps/cs2cs.rst
@@ -0,0 +1,187 @@
+.. _cs2cs:
+
+================================================================================
+cs2cs
+================================================================================
+
+.. only:: html
+
+    Cartographic coordinate system filter.
+
+Synopsis
+********
+
+   **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s]
+
+Description
+***********
+
+:program:`cs2cs` performs transformation between the source and destination
+cartographic  coordinate  system on a set of input points.  The coordinate
+system transformation can include  translation  between projected  and
+geographic coordinates as well as the application of datum shifts.
+
+The following control parameters can  appear  in any order:
+
+.. program:: cs2cs
+
+.. option:: -I
+
+    method to specify inverse translation, convert from *+to* coordinate system to
+    the primary coordinate system defined.
+
+.. option:: -t<a>
+
+    A specifies a character employed as the first character to denote a control
+    line to  be passed through without processing. This option  applicable  to
+    ascii  input only. (# is the default value).
+
+.. option:: -e <string>
+
+    String is an arbitrary string to be output if an error is detected  during
+    data transformations. The  default value is: *\t*. Note that if the -b, -i
+    or -o options are employed, an error is returned as HUGE_VAL value for both
+    return values.
+
+.. option:: -E
+
+    causes the input coordinates to be copied to the output line prior to
+    printing  the converted values.
+
+.. option:: -l<[=id]>
+
+    List projection identifiers that can be selected with *+proj*. ``cs2cs -l=id``
+    gives expanded description of projection id, e.g. ``cs2cs -l=merc``.
+
+.. option:: -lp
+
+    List of all projection id that can be used with the *+proj* parameter.
+    Equivalent to ``cs2cs -l``.
+
+.. option:: -lP
+
+    Expanded description of all projections that can be used with the *+proj*
+    parameter.
+
+.. option:: -le
+
+    List of all ellipsoids that can be selected with the *+ellps* parameters.
+
+.. option:: -lu
+
+    List of all distance units that can be selected with the *+units* parameter.
+
+.. option:: -ld
+
+    List of datums that can be selected with the *+datum* parameter.
+
+.. option:: -r
+
+    This options reverses the order of the expected input from
+    longitude-latitude or x-y to latitude-longitude or y-x.
+
+.. option:: -s
+
+    This options reverses the order of the output from x-y or longitude-latitude
+    to y-x or latitude-longitude.
+
+.. option:: -f <format>
+
+    Format is a printf format string to control the form of the output values.
+    For inverse projections, the output will be in degrees when this option is
+    employed.  If a format is specified for inverse projection the output data
+    will be in deci- mal  degrees. The default format is "%.2f" for forward
+    projection and DMS for inverse.
+
+.. option:: -[w|W]<n>
+
+    N is the number of significant fractional digits to employ for seconds
+    output (when the option is not specified, -w3 is assumed). When -W is
+    employed the fields will be constant width and with leading zeroes.
+
+.. option:: -v
+
+    causes a listing of cartographic control parameters tested for and used by
+    the program to be printed prior to input data.
+
+
+.. only:: man
+
+    The *+args* run-line arguments are associated with cartographic
+    parameters.
+
+.. only:: html
+
+    The *+args* run-line arguments are associated with cartographic
+    parameters.  Usage varies with projection and for a complete description
+    consult the :ref:`projection pages <projections>`.
+
+The :program:`cs2cs` program requires two coordinate system definitions.  The first (or
+primary  is  defined based on all projection parameters not appearing after the
+*+to* argument.  All projection  parameters appearing  after the *+to* argument
+are considered the definition of the second  coordinate system.  If there is no
+second coordinate system defined, a geographic coordinate system based on the
+datum and ellipsoid of the source coordinate system is assumed.  Note  that  the
+source  and destination  coordinate  system can both be projections, both be
+geographic, or one of each and may have the same or different datums.
+
+Additional  projection control parameters may be contained in two auxiliary
+control  files:  the first   is   optionally   referenced   with  the
+*+init=file:id* and the second is always processed after the name of the
+projection has been established from either the run-line or the  contents of
+*+init*   file.   The  environment  parameter PROJ_LIB establishes the default
+directory for a file  reference  without an absolute path.  This is 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
+input.  If no files are  specified,  the  input  is  assumed to be from stdin.
+For 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 portions
+of the input line are appended to the output line.
+
+Input geographic data (longitude  and  latitude) must  be  in  DMS  or decimal
+degrees format and input cartesian data must be in units consistent with  the
+ellipsoid major axis or sphere radius units.  Output geographic coordinates will
+normally be in DMS format (use ``-f %.12f`` for decimal degrees with 12 decimal
+places), while projected (cartesian)   coordinates   will  be  in  linear
+(meter, feet) units.
+
+
+Example
+*******
+
+The following script
+
+::
+
+     cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10  +datum=NAD27 -r
+     <<EOF 45d15'33.1"   111.5W 45d15.551666667N   -111d30 +45.25919444444
+     111d30'000w EOF
+
+will  transform the input NAD83 geographic coordinates into NAD27 coordinates in
+the  UTM  projection  with  zone 10 selected.  The geographic values of this
+example are equivalent and  meant as  examples of various forms of DMS input.
+The x-y output data will appear as three lines of:
+
+::
+
+     1402285.99      5076292.42 0.000
+
+.. only:: man
+
+    See also
+    ********
+
+    **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**
+
+    Bugs
+    ****
+
+    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    where new bug reports can be submitted to.
+
+    Home page
+    *********
+
+    http://proj4.org/
diff --git a/docs/source/apps/geod.rst b/docs/source/apps/geod.rst
new file mode 100644
index 00000000..3b60f461
--- /dev/null
+++ b/docs/source/apps/geod.rst
@@ -0,0 +1,214 @@
+.. _geod:
+
+================================================================================
+geod
+================================================================================
+
+Synopsis
+********
+
+       **geod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s]
+
+       **invgeod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args  ]  ]  [ *+args*  ] file[s]
+
+Description
+***********
+
+:program:`geod`  (direct)  and  :program:`invgeod` (inverse) perform geodesic
+(Great Circle) computations for determining latitude,  longitude  and back
+azimuth  of  a terminus point given a initial point latitude, longitude,
+azimuth and distance (direct) or  the  forward and  back azimuths and distance
+between an initial and terminus point latitudes and  longitudes  (inverse).
+The  results  are accurate  to  round  off for :math:`|f| < 1/50`, where
+:math:`f` is flattening.
+
+
+:program:`invgeod` may not be available on all  platforms;  in  this  case
+use :option:`geod -I` instead.
+
+The following command-line options can appear in any order:
+
+
+.. program:: geod
+
+
+.. option:: -I
+
+    Specifies that the inverse geodesic computation is to be performed. May be
+    used with execution of geod as an alternative to invgeod execution.
+
+.. option:: -a
+
+    Latitude and longitudes of the initial and terminal points, forward and
+    back azimuths and distance are  output.
+
+.. option:: -ta
+
+    A specifies a character employed as the first character to denote a control
+    line to be passed through without processing.
+
+.. option:: -le
+
+    Gives a listing of all the ellipsoids that may be selected with the
+    *+ellps=* option.
+
+.. option:: -lu
+
+    Gives a listing of all the units that  may  be  selected with the *+units=*
+    option.
+
+.. option:: -f <format>
+
+    Format is a printf format string to control the output form of the
+    geographic coordinate values. The default mode is DMS for geographic
+    coordinates and "%.3f" for distance.
+
+.. option:: -F <format>
+
+    Format is a printf format string to control the output form of the distance
+    value (``-F``). The default mode is DMS for geographic coordinates and
+    "%.3f" for distance.
+
+.. option:: -w<n>
+
+    N is the number of significant fractional digits to employ for seconds
+    output (when the option is not specified, ``-w3`` is assumed).
+
+.. option:: -W<n>
+
+    N is the number of significant fractional digits to employ for seconds
+    output. When ``-W`` is employed the fields will be constant width
+    with leading zeroes.
+
+.. option:: -p
+
+    This option causes the azimuthal values to be output as unsigned DMS
+    numbers between 0 and 360 degrees. Also note :option:`-f`.
+
+The  *+args*  command-line  options  are associated with geodetic
+parameters for specifying the ellipsoidal  or  sphere  to  use.
+controls.  The options are processed in  left  to  right  order
+from  the  command  line.  Reentry of an option is ignored with
+the first occurrence assumed to be the desired value.
+
+.. only:: html
+
+    See  :ref:`projections_intro` for full
+    list of these parameters and controls.
+
+.. only:: man
+
+    See the PROJ documentation for a full list of these parameters and
+    controls.
+
+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 input.  If no files are  specified,
+the input is assumed to be from stdin.
+
+For  direct determinations input data must be in latitude, longitude,
+azimuth and distance order and output will be latitude,
+longitude  and  back  azimuth of the terminus point.  Latitude,
+longitude of the initial and terminus point are input  for  the
+inverse  mode  and respective forward and back azimuth from the
+initial and terminus points are output along with the  distance
+between the points.
+
+Input  geographic  coordinates  (latitude  and  longitude)  and
+azimuthal data must be in decimal degrees  or  DMS  format  and
+input distance data must be in units consistent with the ellipsoid
+major axis or sphere radius units.  The latitude must  lie
+in the range [-90d,90d].  Output geographic coordinates will be
+in DMS (if the :option:`-f` switch is not employed) to 0.001" with trailing,
+zero-valued minute-second fields deleted.  Output distance
+data will be in the same  units  as  the  ellipsoid  or  sphere
+radius.
+
+The Earth's ellipsoidal figure may be selected in the same manner
+as program :program:`proj` by using *+ellps=*, *+a=*, *+es=*, etc.
+
+Geod may also be used to determine  intermediate  points  along
+either  a  geodesic  line between two points or along an arc of
+specified distance from a geographic point.  In both  cases  an
+initial  point must be specified with *+lat_1=lat* and *+lon_1=lon*
+parameters  and  either  a  terminus   point   *+lat_2=lat*   and
+*+lon_2=lon*  or  a  distance  and azimuth from the initial point
+with *+S=distance* and *+A=azimuth* must be specified.
+
+If points along a geodesic are to  be  determined  then  either
+*+n_S=integer*  specifying  the  number  of  intermediate  points
+and/or  *+del_S=distance*  specifying  the  incremental  distance
+between points must be specified.
+
+To  determine  points along an arc equidistant from the initial
+point both *+del_A=angle*  and  *+n_A=integer*  must  be  specified
+which determine the respective angular increments and number of
+points to be determined.
+
+Examples
+********
+
+The following script determines the geodesic azimuths and  distance in U.S.
+statute miles from Boston, MA, to Portland, OR:
+
+.. code-block:: console
+
+     geod +ellps=clrk66 <<EOF -I +units=us-mi
+     42d15'N 71d07'W 45d31'N 123d41'W
+     EOF
+
+which gives the results:
+
+.. code-block:: console
+
+     -66d31'50.141" 75d39'13.083" 2587.504
+
+where the first two values are the azimuth from Boston to Portland,
+the back azimuth from Portland to Boston followed by the distance.
+
+An  example  of forward geodesic use is to use the Boston location
+and determine Portland's location by azimuth and distance:
+
+.. code-block:: console
+
+     geod +ellps=clrk66 <<EOF +units=us-mi
+     42d15'N 71d07'W -66d31'50.141" 2587.504
+     EOF
+
+which gives:
+
+.. code-block:: console
+
+     45d31'0.003"N 123d40'59.985"W 75d39'13.094"
+
+.. note::
+    Lack  of precision in the distance value compromises the
+    precision of the Portland location.
+
+Further reading
+***************
+
+#. `GeographicLib <https://geographiclib.sourceforge.io>`_.
+
+#. C. F. F. Karney, `Algorithms for Geodesics <https://doi.org/10.1007/s00190-012-0578-z>`_, J. Geodesy **87**\ (1), 43–55 (2013);
+   `addenda <https://geographiclib.sourceforge.io/geod-addenda.html>`_.
+
+#. `A geodesic bibliography <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_.
+
+.. only:: man
+
+    See also
+    ********
+
+    **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**
+
+    Bugs
+    ****
+
+    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    where new bug reports can be submitted to.
+
+    Home page
+    *********
+
+    http://proj4.org/
diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst
new file mode 100644
index 00000000..5ee58248
--- /dev/null
+++ b/docs/source/apps/index.rst
@@ -0,0 +1,21 @@
+.. _apps:
+
+================================================================================
+Applications
+================================================================================
+
+Bundled with PROJ comes a set of small command line utilities. The
+``proj`` program is limited to converting between geographic and projection
+coordinates within one datum. The ``cs2cs`` program operates similarly, but
+allows translation between any pair of definable coordinate systems, including
+support for basic datum translation. The ``geod`` program provides the ability
+to do geodesic (great circle) computations.
+
+.. toctree::
+   :maxdepth: 1
+
+   proj
+   cct
+   cs2cs
+   geod
+
diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst
new file mode 100644
index 00000000..dee4ea89
--- /dev/null
+++ b/docs/source/apps/proj.rst
@@ -0,0 +1,236 @@
+.. _proj:
+
+================================================================================
+proj
+================================================================================
+
+.. only:: html
+
+    Cartographic projection filter.
+
+.. Index:: proj
+
+Synopsis
+********
+    **proj** [ **-bceEfiIlmorsStTvVwW** ] [ args ] ] [ *+args* ] file[s]
+
+    **invproj** [ **-bceEfiIlmorsStTwW** ] [ args ] ] [ *+args* ] file[s]
+
+
+Description
+***********
+:program:`proj` and :program:`invproj` perform respective forward  and inverse
+transformation  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
+use :option:`proj -I` instead.
+
+The  following  control parameters can appear in any order
+
+.. program:: proj
+
+.. option:: -b
+
+    Special option for binary coordinate data input and output through standard
+    input and standard output. Data is assumed to be in system type double
+    floating point words. This option is to be used when proj is a son process
+    and allows bypassing formatting operations.
+
+.. option:: -i
+
+    Selects binary input only (see :option:`-b`).
+
+.. option:: -I
+
+    alternate method to specify inverse projection. Redundant when used with
+    invproj.
+
+.. option:: -o
+
+    Selects binary output only (see :option:`-b`).
+
+.. option:: -t<a>
+
+    *a* specifies a character employed as the first character to denote a
+    control line to be passed through without  processing. This  option
+    applicable to ascii input only. (# is the default value).
+
+.. option:: -e <string>
+
+      String is an arbitrary string to be output if an error is detected during
+      data transformations. The default value is: *\t*. Note that if the
+      :option:`-b`, :option:`-i` or :option:`-o` options are employed, an error
+      is returned as HUGE_VAL value for both return values.
+
+.. option:: -E
+
+    causes the input coordinates to be copied to the output line prior to
+    printing the converted values.
+
+.. option:: -l<[=id]>
+
+    List projection identifiers that can be selected with *+proj*. ``proj -l=id``
+    gives expanded description of projection id, e.g. ``proj -l=merc``.
+
+.. option:: -lp
+
+    List of all projection id that can be used with the *+proj* parameter.
+    Equivalent to ``proj -l``.
+
+.. option:: -lP
+
+    Expanded description of all projections that can be used with the *+proj*
+    parameter.
+
+.. option:: -le
+
+    List of all ellipsoids that can be selected with the *+ellps* parameters.
+
+.. option:: -lu
+
+    List of all distance units that can be selected with the *+units* parameter.
+
+.. option:: -ld
+
+    List of datums that can be selected with the *+datum* parameter.
+
+
+.. option:: -r
+
+    This options reverses the order of the expected input from
+    longitude-latitude or x-y to latitude-longitude or y-x.
+
+.. option:: -s
+
+    This options reverses the order of the output from x-y or longitude-latitude
+    to y-x or latitude-longitude.
+
+.. option:: -S
+
+    Causes estimation of meridional and parallel scale factors, area scale
+    factor and angular distortion, and maximum and minimum scale factors to be
+    listed between <> for each input point. For conformal projections meridional
+    and parallel scales factors will be equal and angular distortion zero. Equal
+    area projections will have an area factor of 1.
+
+.. option:: -m <mult>
+
+    The cartesian data may be scaled by the mult parameter. When processing data
+    in a forward projection mode the cartesian output values are multiplied by
+    mult otherwise the input cartesian values are divided by mult before inverse
+    projection.  If the first two characters of mult are 1/ or 1: then the
+    reciprocal value of mult is employed.
+
+.. option:: -f <format>
+
+    Format is a printf format string to control the form of the output values.
+    For inverse projections, the output will be in degrees when this option is
+    employed.  The  default format is "%.2f" for forward projection and DMS for
+    inverse.
+
+.. option:: -[w|W]<n>
+
+    N is the number of significant fractional digits to employ for seconds
+    output (when the  option  is  not  specified, ``-w3`` is assumed). When ``-W``
+    is employed the fields will be constant width and  with  leading zeroes.
+
+.. option:: -v
+
+    causes a listing of cartographic control parameters tested for and used by
+    the program to be printed prior to input data. Should not be used with the
+    :option:`-T` option.
+
+.. option:: -V
+
+    This option causes an expanded annotated listing of the characteristics of
+    the projected point. :option:`-v` is implied with this option.
+
+.. option:: -T <ulow,uhi,vlow,vhi,res[,umax,vmax]>
+
+    This option creates a set of bivariate Chebyshev polynomial coefficients
+    that approximate the selected  cartographic projection on stdout. The values
+    low and hi denote the range of the input where the u or v prefixes apply to
+    respective longitude-x or latitude-y depending upon whether a forward or
+    inverse projection is selected. Res is an integer number specifying the
+    power of 10 precision of the approximation. For example, a res of -3
+    specifies an approximation with an accuracy better than .001. Umax, and vmax
+    specify maximum degree of the polynomials (default: 15).
+
+
+
+The *+args* run-line arguments are associated with cartographic parameters.
+Additional projection control parameters may  be contained  in  two  auxiliary
+control files: the first  is   optionally   referenced   with   the
+*+init=file:id* and the second is always processed after the name of the
+projection has been established from either the run-line or the contents of
++init  file.   The   environment   parameter :envvar:`PROJ_LIB` establishes the
+default directory for a file reference without an absolute  path.   This is
+also  used  for  supporting files like datum shift files.
+
+.. only:: html
+
+    Usage of *+args* varies with projection and for a complete description
+    consult the :ref:`projection pages <projections>`.
+
+
+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
+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
+portions of the input line are appended to the output line.
+
+Input  geographic  data (longitude and latitude) must be in DMS format and input
+cartesian  data must  be  in units consistent with the ellipsoid major axis or
+sphere radius units.  Output geographic  coordinates  will  be in DMS (if the
+``-w`` switch is not employed) and  precise  to  0.001" with  trailing, zero-valued
+minute-second fields deleted.
+
+Example
+*******
+The following script
+
+.. code-block:: console
+
+     proj +proj=utm  +lon_0=112w  +ellps=clrk66
+     -r <<EOF
+     45d15'33.1"   111.5W
+     45d15.551666667N   -111d30
+     +45.25919444444    111d30'000w
+     EOF
+
+will perform UTM forward projection with a standard UTM  central  meridian
+nearest  longitude 112W.  The geographic values of this example are equivalent
+and  meant  as  examples  of  various forms  of  DMS  input.  The x-y output
+data will appear as three lines of::
+
+    460769.27     5011648.45
+
+.. only:: man
+
+    Other programs
+    **************
+
+    The :program:`proj` program is limited to converting between geographic and
+    projected coordinates within one datum.
+
+    The :program:`cs2cs` program operates similarly, but allows translation
+    between any paor of definable coordinate reference systems, including
+    support for datum translation.
+
+    See also
+    ********
+
+    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**
+
+    Bugs
+    ****
+
+    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    where new bug reports can be submitted to.
+
+    Home page
+    *********
+
+    http://proj4.org/
-- 
cgit v1.2.3


From aa98657fe98c64ba635c1c0b0387f825e9e917f9 Mon Sep 17 00:00:00 2001
From: Kristian Evers <kristianevers@gmail.com>
Date: Sat, 17 Mar 2018 21:13:12 +0100
Subject: Add documentation for the gie program

---
 docs/source/apps/gie.rst   | 311 +++++++++++++++++++++++++++++++++++++++++++++
 docs/source/apps/index.rst |  15 ++-
 2 files changed, 319 insertions(+), 7 deletions(-)
 create mode 100644 docs/source/apps/gie.rst

(limited to 'docs/source/apps')

diff --git a/docs/source/apps/gie.rst b/docs/source/apps/gie.rst
new file mode 100644
index 00000000..f94c1171
--- /dev/null
+++ b/docs/source/apps/gie.rst
@@ -0,0 +1,311 @@
+.. _gie:
+
+================================================================================
+gie
+================================================================================
+
+.. Index:: gie
+
+.. only:: html
+
+       The Geospatial Integrity Investigation Environment
+
+Synopsis
+********
+
+    **gie** [ **-hovql** [ args ] ] file[s]
+
+Description
+***********
+
+:program:`gie`, the Geospatial Integrity Investigation Environment, is a
+regression testing environment for the PROJ transformation library. Its primary
+design goal is to be able to perform regression testing of code that are a part
+of PROJ, while not requiring any other kind of tooling than the same C compiler
+already employed for compiling the library.
+
+.. option:: -h, --help
+
+    Print usage information
+
+.. option:: -o <file>, --output <file>
+
+    Specify output file name
+
+.. option:: -v, --verbose
+
+    Verbose: Provide non-essential informational output.  Repeat :option:`-v` for
+    more verbosity (e.g. ``-vv``)
+
+.. option:: -q, --quiet
+
+    Quiet: Opposite of verbose. In  quiet  mode  not  even  errors  are
+    reported.  Only  interaction  is through the return code (0 on success,
+    non-zero indicates number of FAILED tests)
+
+.. option:: -l, --list
+
+    List the PROJ internal system error codes
+
+Tests for :program:`gie` are defined in simple text files. Usually having the
+extension ``.gie``. Test for :program:`gie` are written in the purpose-build command language for gie.
+The basic functionality of the gie command language is implemented through just
+3 command verbs: ``operation``, which defines the PROJ operation to test,
+``accept``, which defines the input coordinate to read, and ``expect``, which
+defines the result to expect.
+
+A sample test file for :program:`gie` that uses the three above basic commands looks
+like:
+
+.. code-block:: console
+
+    <gie>
+
+    --------------------------------------------
+    Test output of the UTM projection
+    --------------------------------------------
+    operation  +proj=utm  +zone=32  +ellps=GRS80
+    --------------------------------------------
+    accept     12  55
+    expect     691_875.632_14   6_098_907.825_05
+
+    </gie>
+
+Parsing of a  :program:`gie` file starts at ``<gie>`` and ends when ``</gie>``
+is reached. Anything before ``<gie>`` and after ``</gie>`` is not considered.
+Test cases are created by defining an :option:`operation` which
+:option:`accept` an input coordinate and :option:`expect` an output
+coordinate.
+
+Because :program:`gie` tests are wrapped in the ``<gie>``/``</gie>`` tags it is
+also possible to add test cases to custom made :ref:`init files <init_files>`.
+The tests will be ignore by PROJ when reading the init file with *+init* and
+:program:`gie` ignores anything not wrapped in ``<gie>``/``</gie>``.
+
+:program:`gie` tests are defined by a set of commands like :option:`operation`,
+:option:`accept` and :option:`expect` in the example above. Together the
+commands make out the :program:`gie` command language. Any line in a
+:program:`gie` file that does not start with a command is ignored. In the
+example above it is seen how this can be used to add comments and styling to
+:program:`gie` test files in order to make them more readable as well as
+documenting what the purpose of the various tests are.
+
+Below the :ref:`gie_commands` is explained in details.
+
+Examples
+*********
+
+1. Run all tests in a file with all debug information turned on
+
+.. code-block:: console
+
+    gie -vvvv corner-cases.gie
+
+2. Run all tests in several files
+
+.. code-block:: console
+
+    gie foo bar
+
+.. _gie_commands:
+
+gie command language
+********************
+
+
+.. option:: operation <+args>
+
+    Define a PROJ operation to test. Example:
+
+    .. code-block:: console
+
+        operation proj=utm zone=32 ellps=GRS80
+        # test 4D function
+        accept    12 55 0 0
+        expect    691875.63214  6098907.82501  0  0
+
+        # test 2D function
+        accept    12 56
+        expect    687071.4391   6210141.3267
+
+.. option:: accept <x y [z [t]]>
+
+    Define the input coordinate to read. Takes test coordinate. The coordinate
+    can be defined by either 2, 3 or 4 values, where the first two values are
+    the x- and y-components, the 3rd is the z-component and the 4th is the time
+    component. The number of components in the coordinate determines which
+    version of the operation is tested (2D, 3D or 4D). Many coordinates can be
+    accepted for one :option:`operation`. For each :option:`accept` an
+    accompanying :option:`expect` is needed.
+
+    Note that :program:`gie` accepts the underscore ("_") as a thousands
+    separator.  It is not required (in fact, it is entirely ignored by the
+    input routine), but it significantly improves the readability of the very
+    long strings of numbers typically required in projected coordinates.
+
+
+    See :option:`operation` for an example.
+
+.. option:: expect <x y [z [t]]> | <error code>
+
+    Define the expected coordinate that will be returned from accepted
+    coordinate passed though an operation. The expected coordinate can be
+    defined by either 2, 3 or 4 components, similarly to :option:`accept`.
+    Many coordinates can be expected for one :option:`operation`. For each
+    :option:`expect` an accompanying :option:`accept` is needed.
+
+    See :option:`operation` for an example.
+
+    In addition to expecting a coordinate it is also possible to expect a
+    PROJ error code in case an operation can't be created. This is useful when
+    testing that errors are caught and handled correctly. Below is an example of
+    that tests that the pipeline operator fails correctly when a non-invertable
+    pipeline is constructed.
+
+    .. code-block:: console
+
+        operation   proj=pipeline step
+                    proj=urm5 n=0.5 inv
+        expect      failure pjd_err_malformed_pipeline
+
+    See ``gie -l`` for a list of error codes that can be expected.
+
+.. option:: tolerance <tolerance>
+
+    The :option:`tolerance` command controls how much accepted coordinates
+    can deviate from the expected coordinate. This is handy to test that an
+    operation meets a certain numerical tolerance threshold. Some operations
+    are expexted to be accurate within milimeters  where others might only be
+    accurate within a few meters. :option:`tolerance` should
+
+    .. code-block:: console
+
+        operation       proj=merc
+        # test coordinate as returned by ```echo 12 55 | proj +proj=merc``
+        tolerance       1 cm
+        accept          12 55
+        expect          1335833.89 7326837.72
+
+        # test that the same coordinate with a 50 m false easting as determined
+        # by ``echo 12 55 |proj +proj=merc +x_0=50`` is still within a 100 m
+        # tolerance of the unaltered coordinate from proj=merc
+        tolerance       100 m
+        accept          12 55
+        expect          1335883.89  7326837.72
+
+    The default tolerance is 0.5 mm. See :option:`proj -lu` for a list of possible
+    units.
+
+.. option:: roundtrip <n> <tolerance>
+
+    Do a roundtrip test of an operation. :option:`roundtrip` needs a
+    :option:`operation` and a :option:`accept` command
+    to function. The accepted coordinate is passed to the operation first in
+    it's forward mode, then the output from the forward operation is passed
+    back to the inverse operation. This procedure is done ``n`` times. If the
+    resulting coordinate is within the set tolerance of the initial coordinate
+    the test is passed.
+
+    Example:
+
+    operation       proj=merc
+    accept          12 55
+    roundtrip       10000 5 mm
+
+
+.. option:: direction <direction>
+
+    The :option:`direction` command specifies in which direction an operation
+    is performed. This can either be ``forward`` or ``inverse``. An example of
+    this is seen below where it is tested that a symmetrical transformation
+    pipeline returns the same results in both directions.
+
+    .. code-block:: console
+
+        operation proj=pipeline zone=32 step
+                  proj=utm  ellps=GRS80 step
+                  proj=utm  ellps=GRS80 inv
+        tolerance 0.1 mm
+
+        accept 12 55 0 0
+        expect 12 55 0 0
+
+        # Now the inverse direction (still same result: the pipeline is symmetrical)
+
+        direction inverse
+        expect 12 55 0 0
+
+    The default direction is "forward".
+
+.. option:: ignore <error code>
+
+    This is especially
+    useful in test cases that rely on a grid that is not guaranteed to be
+    available. Below is an example of that situation.
+
+    .. code-block:: console
+
+        operation  proj=hgridshift +grids=nzgd2kgrid0005.gsb  ellps=GRS80
+        tolerance 1 mm
+        ignore    pjd_err_failed_to_load_grid
+        accept    172.999892181021551 -45.001620431954613
+        expect    173                 -45
+
+
+    See ``gie -l`` for a list of error codes that can be ignored.
+
+
+Background
+**********
+
+More importantly than being an acronym for "Geospatial Integrity Investigation
+Environment", gie were also the initials, user id, and USGS email address of
+Gerald Ian Evenden (1935--2016), the geospatial visionary, who, already in the
+1980s, started what was  to  become  the PROJ of today.
+
+Gerald's clear vision was that map projections are *just special functions*.
+Some of them rather complex, most of them of two variables, but all of them
+*just special functions*, and not particularly more special than the :c:func:`sin()`,
+:c:func:`cos()`, :c:func:`tan()`, and :c:func:`hypot()` already available  in  the  C standard library.
+
+And hence, according to Gerald, *they should not be particularly much harder
+to use*, for a programmer, than the :c:func:`sin()`'s, :c:func:`tan()`'s and
+:c:func:`hypot()`'s so readily available.
+
+Gerald's ingenuity also showed in the implementation of the vision, where
+he devised a comprehensive, yet simple, system of key-value pairs for
+parameterising a map projection, and the highly flexible PJ struct, storing
+run-time compiled versions of those key-value pairs, hence mak- ing  a  map
+projection  function call, pj_fwd(PJ, point), as easy as a traditional function
+call like ``hypot(x,y)``.
+
+While today, we may have more formally well defined metadata systems (most
+prominent the OGC WKT2 representation), nothing comes close being as easily
+readable ("human compatible") as Gerald's key-value system. This system in
+particular, and the PROJ system in general, was Gerald's great gift to anyone
+using and/or communicating about geodata.
+
+It is only reasonable to name a program, keeping an eye on the
+integrity of the PROJ system, in honour of Gerald.
+
+So in honour, and hopefully also in the spirit, of Gerald Ian Evenden
+(1935--2016), this is the Geospatial Integrity Investigation Environment.
+
+
+.. only:: man
+
+    See also
+    ********
+
+    **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**
+
+    Bugs
+    ****
+
+    A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues
+    where new bug reports can be submitted to.
+
+    Home page
+    *********
+
+    http://proj4.org/
diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst
index 5ee58248..91f5c4ff 100644
--- a/docs/source/apps/index.rst
+++ b/docs/source/apps/index.rst
@@ -4,12 +4,13 @@
 Applications
 ================================================================================
 
-Bundled with PROJ comes a set of small command line utilities. The
-``proj`` program is limited to converting between geographic and projection
-coordinates within one datum. The ``cs2cs`` program operates similarly, but
-allows translation between any pair of definable coordinate systems, including
-support for basic datum translation. The ``geod`` program provides the ability
-to do geodesic (great circle) computations.
+Bundled with PROJ comes a set of small command line utilities. The ``proj``
+program is limited to converting between geographic and projection coordinates
+within one datum. The ``cs2cs`` program operates similarly, but allows
+translation between any pair of definable coordinate systems, including support
+for basic datum translation. The ``geod`` program provides the ability to do
+geodesic (great circle) computations. ``gie`` is the program used for
+regression tests in PROJ.
 
 .. toctree::
    :maxdepth: 1
@@ -18,4 +19,4 @@ to do geodesic (great circle) computations.
    cct
    cs2cs
    geod
-
+   gie
-- 
cgit v1.2.3