Clean up FAQ

This removes some questions that are no longer valid
(covered elsewhere in the docs), adjusts the wording in other questions
and fixes formatting and making it proper rst/sphinx syntax.

With this, #1070 is almost fixed.

3 files changed, 53 insertions, 120 deletions

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