Add manpages for cct & gie.

Fixes: #760

3 files changed, 229 insertions, 1 deletions

diff --git a/man/man1/Makefile.am b/man/man1/Makefile.am
index b175aaa0..b8a59ff2 100644
--- a/man/man1/Makefile.am
+++ b/man/man1/Makefile.am
@@ -1,4 +1,4 @@
-man_MANS	=	geod.1 proj.1 cs2cs.1
+man_MANS	=	geod.1 proj.1 cs2cs.1 cct.1 gie.1
 
 EXTRA_DIST	=	$(man_MANS)
 
diff --git a/man/man1/cct.1 b/man/man1/cct.1
new file mode 100644
index 00000000..2cd12e4e
--- /dev/null
+++ b/man/man1/cct.1
@@ -0,0 +1,112 @@
+.\" release 5
+.nr LL 5.5i
+.ad b
+.hy 1
+.TH CCT 1 "2018/02/25 Rel. 5.0.0"
+.SH NAME
+cct \- 4D equivalent to the "proj" projection program
+.SH SYNOPSIS
+.B cct
+[\-options]... [+operator_specs]... infile...
+.SH DESCRIPTION
+.I cct
+is a 4D equivalent to the proj(1) projection program.
+.PP
+cct is an acronym meaning "Coordinate Conversion and Transformation".
+.PP
+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:
+.PP
+*Coordinate Conversions*, which are coordinate operations where input
+and output datum are identical (e.g. conversion from geographical to
+cartesian coordinates) and
+.PP
+*Coordinate Transformations*, which are coordinate operations where
+input and output datums differ (e.g. change of reference frame).
+.PP
+\fBcct\fR, 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
+Amercan Geophysical Union (1991), recipient of the IAG Levallois Medal
+(2007), the European Geosciences Union Vening Meinesz Medal (2008), and
+of numerous other honours.
+.PP
+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.
+.PP
+As Christian was an avid Fortran programmer, and a keen Unix connoiseur,
+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.
+.PP
+Hence, in honour of cct (the geodesist) this is cct (the program).
+.SH OPTIONS
+.IP "\fB\fB\-o /path/to/file\fR\fR" 1c
+Specify output file name\&
+.IP "\fB\fB\-c x,y,z,t\fR\fR" 1c
+Specify input columns for (up to) 4 input parameters.
+Defaults to 1,2,3,4\&
+.IP "\fB\fB\-z value\fR\fR" 1c
+Provide a fixed z value for all input data (e.g. \-z 0)\&
+.IP "\fB\fB\-t value\fR\fR" 1c
+Provide a fixed t value for all input data (e.g. \-t 0)\&
+.IP "\fB\fB\-I\fR\fR" 1c
+Do the inverse transformation\&
+.IP "\fB\fB\-v\fR\fR" 1c
+Verbose: Provide non-essential informational output.
+Repeat \-v for more verbosity (e.g. \-vv)\&
+.SH LONG OPTIONS
+.IP "\fB\fB\-\-output\fR\fR" 1c
+Alias for \-o\&
+.IP "\fB\fB\-\-columns\fR\fR" 1c
+Alias for \-c\&
+.IP "\fB\fB\-\-height\fR\fR" 1c
+Alias for \-z\&
+.IP "\fB\fB\-\-time\fR\fR" 1c
+Alias for \-t\&
+.IP "\fB\fB\-\-verbose\fR\fR" 1c
+Alias for \-v\&
+.IP "\fB\fB\-\-inverse\fR\fR" 1c
+Alias for \-I\&
+.IP "\fB\fB\-\-help\fR\fR" 1c
+Alias for -h\&
+.SH OPERATOR SPECS
+The operator specs describe the action to be performed by cct, e.g:
+.IP
++proj=utm  +ellps=GRS80  +zone=32
+.PP
+instructs cct to convert input data to Universal Transverse Mercator, zone 32
+coordinates, based on the GRS80 ellipsoid.
+.PP
+Hence, the command
+.IP
+echo 12 55 | cct -z0 -t0 +proj=utm +zone=32 +ellps=GRS80
+.PP
+Should give results comparable to the classic proj command
+.IP
+echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80
+.SH EXAMPLES
+1. convert geographical input to UTM zone 32 on the GRS80 ellipsoid:
+.IP
+cct +proj=utm +ellps=GRS80 +zone=32
+.PP
+2. roundtrip accuracy check for the case above:
+.IP
+cct +proj=pipeline +proj=utm +ellps=GRS80 +zone=32 +step +step +inv
+.PP
+3. as (1) but specify input columns for longitude, latitude, height and time:
+.IP
+cct -c 5,2,1,4  +proj=utm +ellps=GRS80 +zone=32
+.PP
+4. as (1) but specify fixed height and time, hence needing only 2 cols in input:
+.IP
+cct -t 0 -z 0  +proj=utm  +ellps=GRS80  +zone=32
+.SH HOME PAGE
+http://proj4.org/
diff --git a/man/man1/gie.1 b/man/man1/gie.1
new file mode 100644
index 00000000..6a2ce887
--- /dev/null
+++ b/man/man1/gie.1
@@ -0,0 +1,116 @@
+.\" release 5
+.nr LL 5.5i
+.ad b
+.hy 1
+.TH GIE 1 "2018/02/25 Rel. 5.0.0"
+.SH NAME
+gie \- The Geospatial Integrity Investigation Environment
+.SH SYNOPSIS
+.B gie
+[\-options]... infile...
+.SH DESCRIPTION
+\fBgie\fR, the Geospatial Integrity Investigation Environment, is a modest
+regression testing environment for the PROJ.4 transformation library.
+.PP
+Its primary design goal was to be able to replace those thousands of
+lines of regression testing code that are (at time of writing) part
+of PROJ.4, while not requiring any other kind of tooling than the same
+C compiler already employed for compiling the library.
+.PP
+The basic functionality of the gie command language is implemented
+through just 3 command verbs:
+.PP
+operation,     which defines the PROJ.4 operation to test,
+.br
+accept,        which defines the input coordinate to read, and
+.br
+expect,        which defines the result to expect.
+.PP
+E.g:
+.PP
+operation  +proj=utm  +zone=32  +ellps=GRS80
+.br
+accept     12  55
+.br
+expect     691_875.632_14   6_098_907.825_05
+.PP
+Note that 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.
+.PP
+By default, gie considers the EXPECTation met, if the result comes to
+within 0.5 mm of the expected. This default can be changed using the
+"tolerance" command verb (and yes, I know, linguistically speaking, both
+"operation" and "tolerance" are nouns, not verbs). See the first
+few hundred lines of the "builtins.gie" test file for more details of
+the command verbs available (verbs of both the VERBal and NOUNistic
+persuation).
+.PP
+But 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.4 of today.
+.PP
+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 sin(), cos(), tan(), and hypot() already available in
+the C standard library.
+.PP
+And hence, according to Gerald, *they should not be particularly much
+harder to use*, for a programmer, than the sin()s, tan()s and hypot()s
+so readily available.
+.PP
+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 making a map projection function call, pj_fwd(PJ, point), as easy
+as a traditional function call like hypot(x,y).
+.PP
+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.4 system in general, was
+Gerald's great gift to anyone using and/or communicating about geodata.
+.PP
+It is only reasonable to name a program, keeping an eye on the integrity
+of the PROJ.4 system, in honour of Gerald.
+.PP
+So in honour, and hopefully also in the spirit, of Gerald Ian Evenden
+(1935--2016), this is the Geospatial Integrity Investigation Environment.
+.SH OPTIONS
+.IP "\fB\fB\-h\fR\fR" 1c
+Help: print usage information\&
+.IP "\fB\fB\-o /path/to/file\fR\fR" 1c
+Specify output file name\&
+.IP "\fB\fB\-v\fR\fR" 1c
+Verbose: Provide non-essential informational output.
+Repeat \-v for more verbosity (e.g. \-vv)\&
+.IP "\fB\fB\-q\fR\fR" 1c
+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)\&
+.IP "\fB\fB\-l\fR\fR" 1c
+List the PROJ internal system error codes\&
+.SH LONG OPTIONS
+.IP "\fB\fB\-\-output\fR\fR" 1c
+Alias for \-o\&
+.IP "\fB\fB\-\-verbose\fR\fR" 1c
+Alias for \-v\&
+.IP "\fB\fB\-\-help\fR\fR" 1c
+Alias for -h\&
+.IP "\fB\fB\-\-list\fR\fR" 1c
+Alias for \-l\&
+.SH EXAMPLES
+1. Run all tests in file \"corner-cases.gie\", providing much extra information
+.IP
+gie \-vvvv corner-cases.gie
+.PP
+2. Run all tests in files \"foo\" and \"bar\", providing info on failures only
+.IP
+gie foo bar
+.SH HOME PAGE
+http://proj4.org/