Major restructure and rewrite of docs.

A section on "Using PROJ.4" has been introduced giving a introduction
on how to use PROJ.4. The Parameters section has been removed and the
content reworked into other sections. Additionally the order of chapters
has been changed to provide a more complete and readable experience for
users of the documentation.

4 files changed, 0 insertions, 509 deletions

diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
deleted file mode 100644
index ae8016fe..00000000
--- a/docs/source/apps/cs2cs.rst
+++ /dev/null
@@ -1,145 +0,0 @@
-.. _cs2cs:
-
-================================================================================
-cs2cs
-================================================================================
-
-
-.. Index:: cs2cs
-
-``cs2cs`` performs transformation between the source and destination cartographic  coordinate  system
-on a set of input points.  The coordinate system transformation can include  translation  between
-projected  and geographic coordinates as well as the application of datum shifts.
-
-
-Synopsis
-********
-
-::
-
-       cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s]
-
-Description
-***********
-The following control parameters can  appear  in any order:
-
-::
-
-       -I     method to specify inverse translation, convert from +to coordinate system to the
-              primary coordinate system defined.
-
-       -ta    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).
-
-       -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.
-
-       -E     causes the input coordinates to be copied to the output line prior to printing  the
-              converted values.
-
-       -l[p|P|=|e|u|d]id
-              List projection identifiers with -l, -lp or -lP (expanded) that can be selected
-              with +proj. -l=id gives expanded description of projection id. List
-              ellipsoid identifiers with -le, that can be selected with +ellps,-lu list  of
-              cartesian to meter conversion factors that can be selected with +units or -ld
-              list of datums that can be selected with +datum.
-
-       -r     This options reverses the order of the expected input from longitude-latitude or
-              x-y to latitude-longitude or y-x.
-
-       -s     This options reverses the order of the output from x-y or longitude-latitude to
-              y-x or latitude-longitude.
-
-       -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.
-
-       -[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.
-
-       -v     causes a listing of cartographic control parameters tested for and used by the
-              program to be printed prior to input data.
-
-The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with
-projection and for a complete description consult the `projection pages <../projections/index.html>`_
-
-The 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
-
-
diff --git a/docs/source/apps/geod.rst b/docs/source/apps/geod.rst
deleted file mode 100644
index 4620a6cc..00000000
--- a/docs/source/apps/geod.rst
+++ /dev/null
@@ -1,173 +0,0 @@
-.. _geod:
-
-================================================================================
-geod
-================================================================================
-
-
-.. Index:: geod
-
-``geod``  (direct)  and  ``invgeod`` (inverse) perform geodesic ("Great
-Circle") computations for determining latitude,  longitude  and
-back  azimuth  of  a terminus point given a initial point latitude,
-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 f is flattening.
-
-
-``invgeod`` may not be available on all  platforms;  in  this  case
-call geod with the -I option.
-
-
-
-Synopsis
-********
-
-::
-
-       geod +ellps=<ellipse> [ -afFIlptwW [ args ] ] [ +args ] file[s]
-
-       invgeod +ellps=<ellipse> [ -afFIlptwW [ args  ]  ]  [  +args  ] file[s]
-
-Description
-***********
-The following command-line options can appear in any order:
-
-::
-
-   -I     Specifies that the inverse geodesic computation is to be
-          performed. May be used with execution of geod as an
-          alternative to invgeod execution.
-
-   -a     Latitude and longitudes of the initial and terminal
-          points, forward and back azimuths and distance are  output.
-
-   -ta    A specifies a character employed as the first character
-          to denote a control line to be passed through without
-          processing.
-
-   -le    Gives a listing of all the ellipsoids that may be
-          selected with the +ellps= option.
-
-   -lu    Gives a listing of all the units that  may  be  selected
-          with the +units= option.
-
-   -[f|F] format
-          Format is a printf format string to control the output
-          form of the geographic coordinate values (f) or distance
-          value (F). The default mode is DMS for geographic
-          coordinates and "%.3f" for distance.
-
-   -[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 with leading zeroes.
-
-   -p     This option causes the azimuthal values to be output as
-          unsigned DMS numbers between 0 and 360 degrees. Also
-          note -f.
-
-The  ``+args``  command-line  options  are associated with geodetic
-parameters for specifying the ellipsoidal  or  sphere  to  use.
-See  ``proj``  `documentation <proj.html>`_ for full list of these parameters and
-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.
-
-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 -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 ``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:
-
-::
-
-     geod +ellps=clrk66 <<EOF -I +units=us-mi
-     42d15'N 71d07'W 45d31'N 123d41'W
-     EOF
-
-which gives the results:
-
-::
-
-     -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 loca-
-tion and determine Portland's location by azimuth and distance:
-
-::
-
-     geod +ellps=clrk66 <<EOF +units=us-mi
-     42d15'N 71d07'W -66d31'50.141" 2587.504
-     EOF
-
-which gives:
-
-::
-
-     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 <http://geographiclib.sf.net>`_
-
-#. `C. F. F. Karney, Algorithms for Geodesics, J. Geodesy 87, 43-55 (2013) <http://dx.doi.org/10.1007/s00190-012-0578-z>`_.
-   `Addendum <http://geographiclib.sf.net/geod-addenda.html>`_
-
-#. `The online geodesic bibliography <http://geographiclib.sf.net/geodesic-papers/biblio.html>`_
-
-
diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst
deleted file mode 100644
index 1baaf1c5..00000000
--- a/docs/source/apps/index.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-.. _apps:
-
-================================================================================
-Applications
-================================================================================
-
-The  proj  program  is  limited  to   converting
-between  geographic  and  projection coordinates
-within one datum.
-
-The cs2cs program operates similarly, but allows
-translation  between any pair of definable coor-
-dinate  systems,  including  support  for  datum
-translation.
-
-The geod program provides the ability to compute
-geodesic (Great Circle) computations.
-
-
-
-.. toctree::
-   :maxdepth: 1
-
-   proj
-   cs2cs
-   geod
-
diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst
deleted file mode 100644
index a06df383..00000000
--- a/docs/source/apps/proj.rst
+++ /dev/null
@@ -1,164 +0,0 @@
-:. _proj:
-
-================================================================================
-proj
-================================================================================
-
-
-.. Index:: proj
-
-Proj and invproj perform respective forward  and inverse  transformation  of cartographic data to
-or from cartesian data  with  a  wide  range  of selectable projection functions.
-
-
-Synopsis
-********
-::
-
-    proj [ -bcCeEfiIlmorsStTvVwW [ args ] ] [ +args ] file[s]
-    invproj [ -bcCeEfiIlmorsStTwW [ args ] ] [ +args ] file[s]
-
-
-Description
-***********
-The  following  control parameters can appear in any order
-
-::
-
-       -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.
-
-       -i     Selects binary input only (see -b option).
-
-       -C     Check. Invoke all built in self tests and report. Get more verbose report by
-              preceding with the -V option).
-
-       -I     alternate method to specify inverse projection. Redundant when used with invproj.
-
-       -o     Selects binary output only (see -b option).
-
-       -ta    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).
-
-       -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.
-
-       -E     causes the input coordinates to be copied to the output line prior to printing the
-              converted values.
-
-
-       -l[p|P|=|e|u|d]id
-              List projection identifiers with -l, -lp or -lP (expanded) that can be selected
-              with +proj. -l=id gives expanded description of projection id. List
-              ellipsoid identifiers with -le, that can be selected with +ellps, -lu list of
-              cartesian to meter conversion factors that can be selected with +units or -ld
-              list of datums that can be selected with +datum.
-
-       -r     This options reverses the order of the expected input from longitude-latitude or
-              x-y to latitude-longitude or y-x.
-
-       -s     This options reverses the order of the output from x-y or longitude-latitude to
-              y-x or latitude-longitude.
-
-       -S     Causes estimation of meridinal 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 meridinal and parallel scales
-              factors will be equal and angular distortion zero. Equal area projections will
-              have an area factor of 1.
-
-       -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.
-
-       -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.
-
-       -[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.
-
-       -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 -T
-              option.
-
-       -V     This option causes an expanded annotated listing of the characteristics of the
-              projected point. -v is implied with this 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. Usage varies with
-projection and for a complete description consult the `projection pages <../projections/index.html>`_
-
-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 trans-
-formed.  A - will specify the location  of  pro-
-cessing  standard input.  If no files are speci-
-fied, 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  geo-
-graphic  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
-
-::
-
-     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 stan-
-dard  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