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.

1 files changed, 68 insertions, 0 deletions

diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst
new file mode 100644
index 00000000..d162ace9
--- /dev/null
+++ b/docs/source/usage/quickstart.rst
@@ -0,0 +1,68 @@
+.. _quickstart:
+
+================================================================================
+Quick start
+================================================================================
+
+Coordinate transformations are defined by, what in PROJ.4 terminology is
+known as, "proj-strings". A proj-string describes any transformation regardless of
+how simple or complicated it might be. The simplest case is projection of geodetic
+coordinates. This section focuses on the simpler cases and introduces the basic
+anatomy of the proj-string. The complex cases are discussed in
+:doc:`transformation`.
+
+A proj-strings holds the parameters of a given coordinate transformation, e.g.
+
+::
+
+    +proj=merc +lat_ts=56.5 +ellps=GRS80
+
+I.e. a proj-string consists of a projection specifier, ``+proj``, a number of
+parameters that applies to the projection and, if needed, a description of a
+datum shift. In the example above geodetic coordinates are transformed to
+projected space with the :doc:`Mercator projection<../projections/merc>` with
+the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every
+projection in PROJ.4 is identified by a shorthand such as ``merc`` in the above
+example.
+
+By using the  above projection definition as parameters for the command line
+utility ``proj`` we can convert the geodetic coordinates to projected space:
+
+::
+
+    $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+
+If called as above ``proj`` will be in interactive mode, letting you type the
+input data manually and getting a responce presented on screen. ``proj``
+works as any UNIX filter though, which means that you can also pipe data to
+the utility, for instance by using the ``echo`` command:
+
+::
+
+    $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+    3399483.80      752085.60
+
+
+PROJ.4 also comes bundled with the ``cs2cs`` utility which is used to transform
+from onecoordinate reference system to another. Say we want to convert
+the above Mercator coordinates to UTM, we can do that with ``cs2cs``:
+
+::
+
+    $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32
+    6103992.36      1924052.47 0.00
+
+Notice the ``+to`` parameter that seperates the source and destination
+projection definitions.
+
+If you happen to know the EPSG identifiers for the two cordinates reference
+systems you are transforming between you can use those with ``cs2cs``:
+
+::
+
+   $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832
+   231950.54      1920310.71 0.00
+
+In the above example we transform geodetic coordinates in the WGS84 reference
+frame to UTM zone 32N coordinates in the ETRS89 reference frame.
+UTM coordinates