Reformat doc pages for cct, cs2cs, geod and proj

The doc pages are reformatted to better use the features of the Sphinx
documentation system. All four pages has been formatted such that they
can serve as the basis for both the website and UNIX man-pages. This
will make it easier to keep the man-pages aligned with the main
documentation in the future.

4 files changed, 558 insertions, 369 deletions

diff --git a/docs/source/usage/apps/cct.rst b/docs/source/usage/apps/cct.rst
index 014e7732..9153e29b 100644
--- a/docs/source/usage/apps/cct.rst
+++ b/docs/source/usage/apps/cct.rst
@@ -4,135 +4,162 @@
 cct
 ================================================================================
 
-
 .. Index:: cct
 
+.. only:: html
 
+    Coordinate Conversion and Transformation.
 
+Synopsis
+********
 
-``cct`` a 4D equivalent to the ``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.
+       **cct** [ **-cotvz** [ args ] ] *+opts[=arg]*  file[s]
 
-cct is an acronym meaning *Coordinate Conversion and Transformation*.
+Description
+***********
 
-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*:
+: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.
 
-*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).
+The following control parameters can  appear  in any order:
 
-``cct``, however, 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.
+.. program:: cct
 
-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.
+.. option:: -c <x,y,z,t>
 
-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.
+    Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4.
 
-Hence, in honour of cct (the geodesist) this is cct (the program).
+.. option:: -o <output file name>, --output=<output file name>
 
+    Specify the name of the output file.
 
+.. option:: -t <time>, --time=<time>
 
-Synopsis
-********
+    Specify a fixed observation time to be used for all input data.
 
-::
+.. option:: -z <height>, --height=<height>
 
-       cct [ -cotvz [ args ] ]... +opts[=arg]...  file...
+    Specify a fixed observation height to be used for all input data.
 
-Description
-***********
-The following control parameters can  appear  in any order:
+.. option:: -v, --verbose
 
-::
+    Write non-essential, but potentially useful, information to stderr.
+    Repeat for additional information (``-vv``, ``-vvv``, etc.)
 
-       -c x,y,z,t
-       --columns=x,y,z,t
-              Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4
+The *+args* arguments are associated with coordinate operation parameters.
+Usage varies with operation.
 
-       -o <output file name>
-       --output=<output file name>
-              Specify the name of the output file.
+.. only:: html
 
-       -t <time>
-       --time=<time>
-              Specify a fixed observation time to be used for all input data.
+    For a complete description consult the :ref:`projection pages <projections>`.
 
-      -z <height>
-      --height=<height>
-              Specify a fixed observation height to be used for all input data.
 
-       -v
-       --verbose
-              Write non-essential, but potentially useful, information to stderr.
-              Repeat for additional information (-vv, -vvv, etc.)
+: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*:
 
-The ``+args`` arguments are associated with coordinate operation parameters. Usage varies with
-operation. For a complete description consult the `projection pages <../projections/index.html>`_
+*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 cct. So the following script
+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:
+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/usage/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst
index 675379ef..ba77aadf 100644
--- a/docs/source/usage/apps/cs2cs.rst
+++ b/docs/source/usage/apps/cs2cs.rst
@@ -4,140 +4,184 @@
 cs2cs
 ================================================================================
 
+.. only:: html
 
-``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.
-
+    Cartographic coordinate system filter.
 
 Synopsis
 ********
 
-::
-
-       cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s]
+   **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.
 
-       -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
+.. 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.
+     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/usage/apps/geod.rst b/docs/source/usage/apps/geod.rst
index e7056121..3b60f461 100644
--- a/docs/source/usage/apps/geod.rst
+++ b/docs/source/usage/apps/geod.rst
@@ -4,77 +4,105 @@
 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.
+Synopsis
+********
 
+       **geod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s]
 
-``invgeod`` may not be available on all  platforms;  in  this  case
-call geod with the -I option.
+       **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.
 
-Synopsis
-********
 
-::
+:program:`invgeod` may not be available on all  platforms;  in  this  case
+use :option:`geod -I` instead.
 
-       geod +ellps=<ellipse> [ -afFIlptwW [ args ] ] [ +args ] file[s]
+The following command-line options can appear in any order:
 
-       invgeod +ellps=<ellipse> [ -afFIlptwW [ args  ]  ]  [  +args  ] file[s]
 
-Description
-***********
-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
 
-   -I     Specifies that the inverse geodesic computation is to be
-          performed. May be used with execution of geod as an
-          alternative to invgeod execution.
+    Gives a listing of all the ellipsoids that may be selected with the
+    *+ellps=* option.
 
-   -a     Latitude and longitudes of the initial and terminal
-          points, forward and back azimuths and distance are  output.
+.. option:: -lu
 
-   -ta    A specifies a character employed as the first character
-          to denote a control line to be passed through without
-          processing.
+    Gives a listing of all the units that  may  be  selected with the *+units=*
+    option.
 
-   -le    Gives a listing of all the ellipsoids that may be
-          selected with the +ellps= option.
+.. option:: -f <format>
 
-   -lu    Gives a listing of all the units that  may  be  selected
-          with the +units= option.
+    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.
 
-   -[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.
+.. option:: -F <format>
 
-   -[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.
+    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.
 
-   -p     This option causes the azimuthal values to be output as
-          unsigned DMS numbers between 0 and 360 degrees. Also
-          note -f.
+.. option:: -w<n>
 
-The  ``+args``  command-line  options  are associated with geodetic
+    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.
-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.
 
+.. 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
+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.
 
@@ -91,29 +119,29 @@ 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,
+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 ``proj`` by using ``+ellps=``, ``+a=``, ``+es=``, etc.
+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.
+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
+*+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
+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.
 
@@ -123,7 +151,7 @@ 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
@@ -131,7 +159,7 @@ statute miles from Boston, MA, to Portland, OR:
 
 which gives the results:
 
-::
+.. code-block:: console
 
      -66d31'50.141" 75d39'13.083" 2587.504
 
@@ -141,7 +169,7 @@ 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
@@ -149,7 +177,7 @@ and determine Portland's location by azimuth and distance:
 
 which gives:
 
-::
+.. code-block:: console
 
      45d31'0.003"N 123d40'59.985"W 75d39'13.094"
 
@@ -166,3 +194,21 @@ Further reading
    `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/usage/apps/proj.rst b/docs/source/usage/apps/proj.rst
index 6227047f..dee4ea89 100644
--- a/docs/source/usage/apps/proj.rst
+++ b/docs/source/usage/apps/proj.rst
@@ -4,148 +4,194 @@
 proj
 ================================================================================
 
+.. only:: html
 
-.. 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.
+    Cartographic projection filter.
 
+.. Index:: proj
 
 Synopsis
 ********
-::
+    **proj** [ **-bceEfiIlmorsStTvVwW** ] [ args ] ] [ *+args* ] file[s]
 
-    proj [ -bcCeEfiIlmorsStTvVwW [ args ] ] [ +args ] file[s]
-    invproj [ -bcCeEfiIlmorsStTwW [ 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
 
-::
-
-       -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 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.
-
-       -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 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.
+.. 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
@@ -154,11 +200,37 @@ The following script
      +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::
+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
+    *********
 
-     460769.27     5011648.45
+    http://proj4.org/