[GRASS-SVN] r37744 - grass/trunk/lib/gis
svn_grass at osgeo.org
svn_grass at osgeo.org
Fri Jun 5 11:17:52 EDT 2009
Author: martinl
Date: 2009-06-05 11:17:52 -0400 (Fri, 05 Jun 2009)
New Revision: 37744
Modified:
grass/trunk/lib/gis/align_window.c
grass/trunk/lib/gis/alloc.c
grass/trunk/lib/gis/area.c
grass/trunk/lib/gis/area_ellipse.c
grass/trunk/lib/gis/area_poly1.c
grass/trunk/lib/gis/area_poly2.c
grass/trunk/lib/gis/area_sphere.c
grass/trunk/lib/gis/bres_line.c
grass/trunk/lib/gis/date.c
grass/trunk/lib/gis/distance.c
grass/trunk/lib/gis/endian.c
grass/trunk/lib/gis/env.c
grass/trunk/lib/gis/error.c
grass/trunk/lib/gis/find_file.c
grass/trunk/lib/gis/geodist.c
grass/trunk/lib/gis/get_ellipse.c
grass/trunk/lib/gis/get_window.c
grass/trunk/lib/gis/getl.c
grass/trunk/lib/gis/gisbase.c
grass/trunk/lib/gis/gisdbase.c
grass/trunk/lib/gis/gislib.dox
grass/trunk/lib/gis/home.c
grass/trunk/lib/gis/location.c
grass/trunk/lib/gis/mapset.c
grass/trunk/lib/gis/myname.c
grass/trunk/lib/gis/nme_in_mps.c
grass/trunk/lib/gis/open.c
grass/trunk/lib/gis/parser.c
grass/trunk/lib/gis/plot.c
grass/trunk/lib/gis/pole_in_poly.c
grass/trunk/lib/gis/proj1.c
grass/trunk/lib/gis/proj2.c
grass/trunk/lib/gis/proj3.c
grass/trunk/lib/gis/put_window.c
grass/trunk/lib/gis/radii.c
grass/trunk/lib/gis/remove.c
grass/trunk/lib/gis/rename.c
grass/trunk/lib/gis/set_window.c
grass/trunk/lib/gis/short_way.c
grass/trunk/lib/gis/strings.c
grass/trunk/lib/gis/system.c
grass/trunk/lib/gis/tempfile.c
grass/trunk/lib/gis/trim_dec.c
grass/trunk/lib/gis/wind_format.c
grass/trunk/lib/gis/wind_scan.c
grass/trunk/lib/gis/window_map.c
grass/trunk/lib/gis/zone.c
Log:
major gislib.dox update (still not complete)
various minor doxygen fixes
Modified: grass/trunk/lib/gis/align_window.c
===================================================================
--- grass/trunk/lib/gis/align_window.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/align_window.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,39 +1,38 @@
-
-/**
- * \file align_window.c
+/*!
+ * \file gis/align_window.c
*
* \brief GIS Library - Window alignment functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <stdio.h>
#include <math.h>
#include <grass/gis.h>
-
-/**
+/*!
* \brief Align two regions.
*
- * Modifies the input <b>window</b> to align to
- * <b>ref</b> region. The resolutions in <b>window</b> are set to match those
- * in <b>ref</b> and the <b>window</b> edges (north, south, east, west) are
- * modified to align with the grid of the <b>ref</b> region.
- * The <b>window</b> may be enlarged if necessary to achieve the alignment.
- * The north is rounded northward, the south southward, the east eastward and the
- * west westward. Lon-lon constraints are taken into consideration
- * to make sure that the north doesn't go above 90 degrees (for lat/lon)
- * or that the east does "wrap" past the west, etc.
+ * Modifies the input <i>window</i> to align to <i>ref</i> region. The
+ * resolutions in <i>window</i> are set to match those in <i>ref</i>
+ * and the <i>window</i> edges (north, south, east, west) are modified
+ * to align with the grid of the <i>ref</i> region.
*
- * \param[in,out] window
- * \param[in] ref
+ * The <i>window</i> may be enlarged if necessary to achieve the
+ * alignment. The north is rounded northward, the south southward,
+ * the east eastward and the west westward. Lon-lon constraints are
+ * taken into consideration to make sure that the north doesn't go
+ * above 90 degrees (for lat/lon) or that the east does "wrap" past
+ * the west, etc.
+ *
+ * \param[in,out] window pointer to Cell_head to be modified
+ * \param ref pointer to Cell_head
+ *
* \return NULL on success
* \return Pointer to an error string on failure
*/
Modified: grass/trunk/lib/gis/alloc.c
===================================================================
--- grass/trunk/lib/gis/alloc.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/alloc.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,34 +1,32 @@
-
-/**
- * \file alloc.c
+/*!
+ * \file fis/alloc.c
*
* \brief GIS Library - Memory allocation routines.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <stdlib.h>
#include <grass/gis.h>
#include <grass/glocale.h>
-
-/**
+/*!
* \brief Memory allocation.
*
- * Allocates a block of
- * memory at least <b>n</b> bytes which is aligned properly for all data
- * types. A pointer to the aligned block is returned.<br>
+ * Allocates a block of memory at least <i>n</i> bytes which is
+ * aligned properly for all data types. A pointer to the aligned block
+ * is returned.
+ *
* Dies with error message on memory allocation fail.
*
- * \param[in] n
- * \return void *
+ * \param file file name
+ * \param line line number
+ * \param t number of elements
*/
void *G__malloc(const char *file, int line, size_t n)
@@ -46,20 +44,22 @@
return buf;
}
-/**
+/*!
* \brief Memory allocation.
*
- * Allocates a
- * properly aligned block of memory <b>n</b>*<b>m</b> bytes in length,
- * initializes the allocated memory to zero, and returns a pointer to the
- * allocated block of memory.<br>
- * Dies with error message on memory allocation fail.<br>
- * <b>Note:</b> Allocating memory for reading and writing raster maps is
- * discussed in Allocating_Raster_I_O_Buffers.
+ * Allocates a properly aligned block of memory <i>n</i>*<i>m</i>
+ * bytes in length, initializes the allocated memory to zero, and
+ * returns a pointer to the allocated block of memory.
*
- * \param[in] n number of elements
- * \param[in] m element size
- * \return void *
+ * Dies with error message on memory allocation fail.
+ *
+ * <b>Note:</b> Allocating memory for reading and writing raster maps
+ * is discussed in \ref Allocating_Raster_I_O_Buffers.
+ *
+ * \param file fine name
+ * \param line line number
+ * \param m element size
+ * \param n number of elements
*/
void *G__calloc(const char *file, int line, size_t m, size_t n)
@@ -80,26 +80,27 @@
}
-/**
+/*!
* \brief Memory reallocation.
*
- * Changes the
- * <b>size</b> of a previously allocated block of memory at <b>ptr</b> and
- * returns a pointer to the new block of memory. The <b>size</b> may be larger
- * or smaller than the original size. If the original block cannot be extended
- * "in place", then a new block is allocated and the original block copied to the
- * new block.<br>
- * <b>Note:</b> If <b>buf</b> is NULL, then this routine simply allocates a
- * block of <b>n</b> bytes else <b>buf</b> must point to memory that has been dynamically
- * allocated by <i>G_malloc()</i>, <i>G_calloc()</i>, <i>G_realloc()</i>,
- * malloc(3), alloc(3), or realloc(3).. This routine works around broken realloc( )
- * routines, which do not handle a NULL <b>buf</b>.
+ * Changes the <i>size</i> of a previously allocated block of memory
+ * at <i>ptr</i> and returns a pointer to the new block of memory. The
+ * <i>size</i> may be larger or smaller than the original size. If the
+ * original block cannot be extended "in place", then a new block is
+ * allocated and the original block copied to the new block.
*
+ * <b>Note:</b> If <i>buf</i> is NULL, then this routine simply
+ * allocates a block of <i>n</i> bytes else <i>buf</i> must point to
+ * memory that has been dynamically allocated by G_malloc(),
+ * G_calloc(), G_realloc(), malloc(3), alloc(3), or realloc(3).. This
+ * routine works around broken realloc() routines, which do not
+ * handle a NULL <i>buf</i>.
+ *
+ * \param file file name
+ * \param line line number
* \param[in,out] buf buffer holding original data
* \param[in] n array size
- * \return void *
*/
-
void *G__realloc(const char *file, int line, void *buf, size_t n)
{
if (n <= 0)
@@ -118,7 +119,7 @@
}
-/**
+/*!
* \brief Free allocated memory.
*
* \param[in,out] buf buffer holding original data
Modified: grass/trunk/lib/gis/area.c
===================================================================
--- grass/trunk/lib/gis/area.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/area.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
- * \file area.c
+/*!
+ * \file gis/area.c
*
* \brief GIS Library - Area calculation functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
@@ -32,17 +29,14 @@
static struct state *st = &state;
-/**
+/*!
* \brief Begin cell area calculations.
*
* This routine must be called once before any call to
- * <i>G_area_of_cell_at_row()</i>. It perform all inititalizations
- * needed to do area calculations for grid cells, based on the current
- * window "projection" field. It can be used in either planimetric
+ * G_area_of_cell_at_row(). It perform all inititalizations needed to
+ * do area calculations for grid cells, based on the current window
+ * "projection" field. It can be used in either planimetric
* projections or the latitude-longitude projection.
- * <br>
- * If the return value is 1 or 0, all the grid cells in the map have
- * the same area. Otherwise, the area of a grid cell varies with the row.
*
* \return 0 if the projection is not measurable (ie. imagery or xy)
* \return 1 if the projection is planimetric (ie. UTM or SP)
@@ -79,18 +73,17 @@
}
}
-
-/**
- * \brief Cell area in specified <b>row</b>.
+/*!
+ * \brief Cell area in specified row.
*
* This routine returns the area in square meters of a cell in the
- * specified <b>row</b>. This value is constant for planimetric grids
+ * specified <i>row</i>. This value is constant for planimetric grids
* and varies with the row if the projection is latitude-longitude.
*
- * \param[in] row
- * \return double
+ * \param row row number
+ *
+ * \return cell area
*/
-
double G_area_of_cell_at_row(int row)
{
double south_value;
@@ -114,18 +107,16 @@
return cell_area;
}
-
-/**
+/*!
* \brief Begin polygon area calculations.
*
- * This initializes the polygon area calculation routines. It is used
+ * This initializes the polygon area calculation routines. It is used
* both for planimetric and latitude-longitude projections.
*
* \return 0 if the projection is not measurable (ie. imagery or xy)
* \return 1 if the projection is planimetric (ie. UTM or SP)
* \return 2 if the projection is non-planimetric (ie. latitude-longitude)
*/
-
int G_begin_polygon_area_calculations(void)
{
double a, e2;
@@ -145,29 +136,29 @@
return 0;
}
-
-/**
+/*!
* \brief Area in square meters of polygon.
*
* Returns the area in square meters of the polygon described by the
- * <b>n</b> pairs of <b>x,y</b> coordinate vertices. It is used both for
+ * <i>n</i> pairs of <i>x,y</i> coordinate vertices. It is used both for
* planimetric and latitude-longitude projections.
- * <br>
- * Returns the area in coordinate units of the polygon described by the
- * <b>n</b> pairs of <b>x,y</b> coordinate vertices for planimetric grids.
- * If the units for <b>x,y</b> are meters, then the area is in square meters.
- * If the units are feet, then the area is in square feet, and so on.
- * <br>
+ *
+ * Returns the area in coordinate units of the polygon described by
+ * the <i>n</i> pairs of <i>x,y</i> coordinate vertices for
+ * planimetric grids. If the units for <i>x,y</i> are meters, then
+ * the area is in square meters. If the units are feet, then the area
+ * is in square feet, and so on.
+ *
* <b>Note:</b> If the database is planimetric with the non-meter grid,
* this routine performs the required unit conversion to produce square
* meters.
*
- * \param[in] x array of x coordinates
- * \param[in] y array of y coordinates
- * \param[in] n number of x,y coordinate pairs
+ * \param x array of x coordinates
+ * \param y array of y coordinates
+ * \param n number of x,y coordinate pairs
+ *
* \return area in coordinate units of the polygon
*/
-
double G_area_of_polygon(const double *x, const double *y, int n)
{
double area;
Modified: grass/trunk/lib/gis/area_ellipse.c
===================================================================
--- grass/trunk/lib/gis/area_ellipse.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/area_ellipse.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
- * \file area_ellipse.c
+/*!
+ * \file gis/area_ellipse.c
*
* \brief GIS Library - Ellipse area routines.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <math.h>
@@ -30,42 +27,39 @@
* code will fail if e2==0 (sphere)
*/
-/**
+/*!
* \brief Begin area calculations for ellipsoid.
*
- * Initializes raster area calculations for an ellipsoid, where <b>a</b>
- * is the semi-major axis of the ellipse (in meters), <b>e2</b> is the
- * ellipsoid eccentricity squared, and <b>s</b> is a scale factor to
- * allow for calculations of part of the zone (<b>s</b>=1.0 is full
- * zone, <b>s</b>=0.5 is half the zone, and <b>s</b>=360/ew_res is for a
+ * Initializes raster area calculations for an ellipsoid, where <i>a</i>
+ * is the semi-major axis of the ellipse (in meters), <i>e2</i> is the
+ * ellipsoid eccentricity squared, and <i>s</i> is a scale factor to
+ * allow for calculations of part of the zone (<i>s</i>=1.0 is full
+ * zone, <i>s</i>=0.5 is half the zone, and <i>s</i>=360/ew_res is for a
* single grid cell).
- * <br>
- * <b>Note:</b> <b>e2</b> must be positive. A negative value makes no
+ *
+ * <b>Note:</b> <i>e2</i> must be positive. A negative value makes no
* sense, and zero implies a sphere.
*
- * \param[in] a semi-major axis
- * \param[in] e2 ellipsoid eccentricity
- * \param[in] s scale factor
- * \return
+ * \param a semi-major axis
+ * \param e2 ellipsoid eccentricity
+ * \param s scale factor
*/
-
void G_begin_zone_area_on_ellipsoid(double a, double e2, double s)
{
st->E = sqrt(e2);
st->M = s * a * a * M_PI * (1 - e2) / st->E;
}
-
-/**
+/*!
* \brief Calculate integral for area between two latitudes.
*
* This routine is part of the integral for the area between two
* latitudes.
*
- * \param[in] lat
- * \return double
+ * \param lat latitude
+ *
+ * \return cell area
*/
-
double G_darea0_on_ellipsoid(double lat)
{
double x;
@@ -75,24 +69,23 @@
return (st->M * (x / (1.0 - x * x) + 0.5 * log((1.0 + x) / (1.0 - x))));
}
-
-/**
+/*!
* \brief Calculates area between latitudes.
*
* This routine shows how to calculate area between two lats, but
- * isn't efficient for row by row since <i>G_darea0_on_ellipsoid()</i>
- * will be called twice for the same lat, once as a <b>south</b> then
- * again as a <b>north</b>.
- * <br>
- * Returns the area between latitudes <b>north</b> and <b>south</b>
- * scaled by the factor <b>s</b> passed to
- * <i>G_begin_zone_area_on_ellipsoid()</i>.
+ * isn't efficient for row by row since G_darea0_on_ellipsoid()
+ * will be called twice for the same lat, once as a <i>south</i> then
+ * again as a <i>north</i>.
+ *
+ * Returns the area between latitudes <i>north</i> and <i>south</i>
+ * scaled by the factor <i>s</i> passed to
+ * G_begin_zone_area_on_ellipsoid().
*
- * \param[in] north
- * \param[in] south
- * \return double
+ * \param north north coordinate
+ * \param south south coordinate
+ *
+ * \return cell area
*/
-
double G_area_for_zone_on_ellipsoid(double north, double south)
{
return (G_darea0_on_ellipsoid(north) - G_darea0_on_ellipsoid(south));
Modified: grass/trunk/lib/gis/area_poly1.c
===================================================================
--- grass/trunk/lib/gis/area_poly1.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/area_poly1.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,24 +1,20 @@
-
-/**
- * \file area_poly1.c
+/*!
+ * \file gis/area_poly1.c
*
* \brief GIS Library - Polygon area calculation routines.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <math.h>
#include <grass/gis.h>
#include "pi.h"
-
#define TWOPI M_PI + M_PI
static struct state {
@@ -51,17 +47,15 @@
return cosx * (st->QbarA + cosx2 * (st->QbarB + cosx2 * (st->QbarC + cosx2 * st->QbarD)));
}
-
-/**
+/*!
* \brief Begin area calculations.
*
* This initializes the polygon area calculations for the
- * ellipsoid with semi-major axis <b>a</b> (in meters) and ellipsoid
- * eccentricity squared <b>e2</b>.
+ * ellipsoid with semi-major axis <i>a</i> (in meters) and ellipsoid
+ * eccentricity squared <i>e2</i>.
*
- * \param[in] a semi-major axis
- * \param[in] e2 ellipsoid eccentricity
- * \return
+ * \param a semi-major axis
+ * \param e2 ellipsoid eccentricity
*/
void G_begin_ellipsoid_polygon_area(double a, double e2)
@@ -88,23 +82,22 @@
st->E = -st->E;
}
-
-/**
+/*!
* \brief Area of lat-long polygon.
*
* Returns the area in square meters of the polygon described by the
- * <b>n</b> pairs of <b>lat,long</b> vertices for latitude-longitude
+ * <i>n</i> pairs of <i>lat,long</i> vertices for latitude-longitude
* grids.
- * <br>
+ *
* <b>Note:</b> This routine assumes grid lines on the connecting the
* vertices (as opposed to geodesics).
*
- * \param[in] lon array of longitudes
- * \param[in] lat array of latitudes
- * \param[in] n number of lat,lon pairs
- * \return double Area in square meters
+ * \param lon array of longitudes
+ * \param lat array of latitudes
+ * \param n number of lat,lon pairs
+ *
+ * \return area in square meters
*/
-
double G_ellipsoid_polygon_area(const double *lon, const double *lat, int n)
{
double x1, y1, x2, y2, dx, dy;
Modified: grass/trunk/lib/gis/area_poly2.c
===================================================================
--- grass/trunk/lib/gis/area_poly2.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/area_poly2.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,31 +1,27 @@
-
-/**
- * \file area_poly2.c
+/*!
+ * \file gis/area_poly2.c
*
* \brief GIS Library - Planimetric polygon area calculation routines.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
-
-/**
+/*!
* \brief Calculates planimetric polygon area.
*
- * \param[in] x array of x values
- * \param[in] y array of y values
- * \param[in] n number of x,y pairs
- * \return double
- */
+ * \param x array of x values
+ * \param y array of y values
+ * \param n number of x,y pairs
+ * \return polygon area in map units
+ */
double G_planimetric_polygon_area(const double *x, const double *y, int n)
{
double x1, y1, x2, y2;
Modified: grass/trunk/lib/gis/area_sphere.c
===================================================================
--- grass/trunk/lib/gis/area_sphere.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/area_sphere.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
- * \file area_sphere.c
+/*!
+ * \file gis/area_sphere.c
*
* \brief GIS Library - Sphereical area calculation routines.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <math.h>
@@ -25,55 +22,47 @@
static struct state *st = &state;
-/*
- * r is radius of sphere, s is a scaling factor
- */
-
-/**
+/*!
* \brief Initialize calculations for sphere.
*
* Initializes raster area calculations for a sphere.
- * The radius of the sphere is <b>r</b> and <b>s</b> is a scale factor to
+ * The radius of the sphere is <i>r</i> and <i>s</i> is a scale factor to
* allow for calculations of a part of the zone (see
- * <i>G_begin_zone_area_on_ellipsoid()</i>).
+ * G_begin_zone_area_on_ellipsoid()).
*
- * \param[in] r radius of sphere
- * \param[in] s scale factor
- * \return
+ * \param r radius of sphere
+ * \param s scale factor
*/
-
void G_begin_zone_area_on_sphere(double r, double s)
{
st->M = s * 2.0 * r * r * M_PI;
}
-
-/**
+/*!
* \brief Calculates integral for area between two latitudes.
*
- * \param[in] lat latitude
- * \return double
+ * \param lat latitude
+ *
+ * \return area value
*/
-
double G_darea0_on_sphere(double lat)
{
return (st->M * sin(Radians(lat)));
}
-
-/**
+/*!
* \brief Calculates area between latitudes.
*
* This routine shows how to calculate area between two lats, but
- * isn't efficient for row by row since <i>G_darea0_on_sphere()</i> will
- * be called twice for the same lat, once as a <b>south</b> then
- * again as a <b>north</b>.
- * <br>
- * Returns the area between latitudes <b>north</b> and <b>south</b>
- * scaled by the factor <b>s</b> passed to
- * <i>G_begin_zone_area_on_sphere()</i>.
+ * isn't efficient for row by row since G_darea0_on_sphere() will
+ * be called twice for the same lat, once as a <i>south</i> then
+ * again as a <i>north</i>.
*
- * \param[in] north
+ * Returns the area between latitudes <i>north</i> and <i>south</i>
+ * scaled by the factor <i>s</i> passed to
+ * G_begin_zone_area_on_sphere().
+ *
+ * \param north
* \param[in] south
* \return double
*/
Modified: grass/trunk/lib/gis/bres_line.c
===================================================================
--- grass/trunk/lib/gis/bres_line.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/bres_line.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,5 +1,5 @@
/*
- * \file bres_line.c
+ * \file gis/bres_line.c
*
* \brief GIS Library - Bresenham line routines.
*
@@ -8,33 +8,25 @@
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
-
-/**
+/*!
* \brief Bresenham line algorithm.
*
- * Draws a line from <b>x1,y1</b> to <b>x2,y2</b> using Bresenham's
+ * Draws a line from <i>x1,y1</i> to <i>x2,y2</i> using Bresenham's
* algorithm. A routine to plot points must be provided, as is defined
* as: point(x, y) plot a point at x,y.
*
- * This routine does not require a previous call to
- * <i>G_setup_plot()</i> to function correctly, and is independent of
- * all following routines.
+ * This routine does not require a previous call to G_setup_plot() to
+ * function correctly, and is independent of all following routines.
*
- * \param[in] x0
- * \param[in] y0
- * \param[in] x1
- * \param[in] y1
- * \param[in] point pointer to point plotting function
- * \return
+ * \param x0,y0 first point
+ * \param x1,y1 end point
+ * \param point pointer to point plotting function
*/
-
void G_bresenham_line(int x0, int y0, int x1, int y1, int (*point) (int, int))
{
int dx, dy;
Modified: grass/trunk/lib/gis/date.c
===================================================================
--- grass/trunk/lib/gis/date.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/date.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,32 +1,28 @@
-
-/**
- * \file date.c
+/*!
+ * \file gis/date.c
*
* \brief GIS Library - Date functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <time.h>
#include <grass/gis.h>
-
-/**
+/*!
* \brief Current date and time.
*
- * Returns a pointer to a string which is the current date and time. The
- * format is the same as that produced by the UNIX <i>date</i> command.
+ * Returns a pointer to a string which is the current date and
+ * time. The format is the same as that produced by the UNIX
+ * <tt>date</tt> command.
*
- * \return Pointer to a string holding date/time
+ * \return pointer to a string holding date/time
*/
-
const char *G_date(void)
{
static int initialized;
Modified: grass/trunk/lib/gis/distance.c
===================================================================
--- grass/trunk/lib/gis/distance.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/distance.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,6 +1,5 @@
-
-/**
- * \file distance.c
+/*!
+ * \file gis/distance.c
*
* \brief GIS Library - Distance calculation functions.
*
@@ -8,14 +7,12 @@
* including calling sequences to any of the functions
* defined here.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2006
+ * \author Original author CERL
*/
#include <math.h>
@@ -32,7 +29,7 @@
static struct state *st = &state;
-/**
+/*!
* \brief Begin distance calculations.
*
* Initializes the distance calculations. It is used both for the
@@ -64,19 +61,19 @@
}
-/**
+/*!
* \brief Returns distance in meters.
*
* This routine computes the distance, in meters, from
- * <b>x1</b>,<b>y1</b> to <b>x2</b>,<b>y2</b>. If the projection is
- * latitude-longitude, this distance is measured along the geodesic. Two
- * routines perform geodesic distance calculations.
+ * <i>x1</i>,<i>y1</i> to <i>x2</i>,<i>y2</i>. If the projection is
+ * latitude-longitude, this distance is measured along the
+ * geodesic. Two routines perform geodesic distance calculations.
*
- * \param[in] e1,n1 east-north coordinates of first point
- * \param[in] e2,n2 east-north coordinates of second point
+ * \param e1,n1 east-north coordinates of first point
+ * \param e2,n2 east-north coordinates of second point
+
* \return distance
*/
-
double G_distance(double e1, double n1, double e2, double n2)
{
if (st->projection == PROJECTION_LL)
@@ -85,20 +82,18 @@
return st->factor * hypot(e1 - e2, n1 - n2);
}
-
-/**
+/*!
* \brief Returns distance between two line segments in meters.
*
- * \param[in] ax1,ay2,ax2,ay2 first segment
- * \param[in] bx1,by2,bx2,by2 second segment
- * \return double
+ * \param ax1,ay2,ax2,ay2 first segment
+ * \param bx1,by2,bx2,by2 second segment
+ *
+ * \return distance value
*/
-
-double
-G_distance_between_line_segments(double ax1, double ay1,
- double ax2, double ay2,
- double bx1, double by1,
- double bx2, double by2)
+double G_distance_between_line_segments(double ax1, double ay1,
+ double ax2, double ay2,
+ double bx1, double by1,
+ double bx2, double by2)
{
double ra, rb;
double x, y;
@@ -115,20 +110,19 @@
);
}
-
-/**
+/*!
* \brief Returns distance between a point and line segment in meters.
*
- * \param[in] xp,yp point coordinates
- * \param[in] x1,x1 segment point coordinates
- * \param[in] x2,y2 segment point coordinates
+ * \param xp,yp point coordinates
+ * \param x1,x1 segment point coordinates
+ * \param x2,y2 segment point coordinates
+ *
* \return distance
*/
-
-double G_distance_point_to_line_segment(double xp, double yp, /* the point */
+double G_distance_point_to_line_segment(double xp, double yp,
double x1, double y1, double x2,
double y2)
-{ /* the line segment */
+{
double dx, dy;
double x, y;
double xq, yq, ra, rb;
Modified: grass/trunk/lib/gis/endian.c
===================================================================
--- grass/trunk/lib/gis/endian.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/endian.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,23 +1,19 @@
-
-/**
- * \file endian.c
+/*!
+ * \file gis/endian.c
*
* \brief GIS Library - Functions to determine architecture endian.
*
* This endian test was taken from ./src.contrib/GMSL/NVIZ2.2/TOGL/apps/image.c.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
* \author Markus Neteler
- *
- * \date 2001-2008
*/
-
-/**
+/*!
* \brief Tests for little ENDIAN.
*
* Test if machine is little or big endian.
@@ -25,7 +21,6 @@
* \return 1 little endian
* \return 0 big endian
*/
-
int G_is_little_endian(void)
{
union
Modified: grass/trunk/lib/gis/env.c
===================================================================
--- grass/trunk/lib/gis/env.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/env.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,15 +1,15 @@
-/**
- \file lib/gis/env.c
+/*!
+ \file gis/env.c
- \brief GIS library - environment routines
-
- (C) 2001-2009 by the GRASS Development Team
-
- This program is free software under the GNU General Public License
- (>=v2). Read the file COPYING that comes with GRASS for details.
-
- \author Original author CERL
- \author Updated for GRASS7 by Glynn Clements
+ \brief GIS library - environment routines
+
+ (C) 2001-2009 by the GRASS Development Team
+
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+
+ \author Original author CERL
+ \author Updated for GRASS7 by Glynn Clements
*/
#include <signal.h>
@@ -49,35 +49,33 @@
static void write_env(int);
static FILE *open_env(const char *, int);
-/**
- \brief Set where to find/store variables
+/*!
+ \brief Set where to find/store variables
+
+ Modes:
+ - G_GISRC_MODE_FILE
+ - G_GISRC_MODE_MEMORY
- Modes:
- - G_GISRC_MODE_FILE
- - G_GISRC_MODE_MEMORY
-
\param mode mode to find/store variables (G_GISRC_MODE_FILE by default)
-
- \return
*/
void G_set_gisrc_mode(int mode)
{
st->varmode = mode;
}
-/**
- \brief Get info where variables are stored
-
- \return mode
+/*!
+ \brief Get info where variables are stored
+
+ \return mode
*/
int G_get_gisrc_mode(void)
{
return (st->varmode);
}
-/**
+/*!
\brief Initialize variables
-
+
\return
*/
void G_init_env(void)
@@ -275,14 +273,14 @@
return fopen(buf, mode);
}
-/**
- \brief Get environment variable
-
- Calls G_fatal_error() if name not set.
-
- \param name variable name
-
- \return char pointer to value for name
+/*!
+ \brief Get environment variable
+
+ Calls G_fatal_error() if name not set.
+
+ \param name variable name
+
+ \return char pointer to value for name
*/
const char *G_getenv(const char *name)
{
@@ -295,20 +293,20 @@
return NULL;
}
-/**
- \brief Read variable from specific place
+/*!
+ \brief Read variable from specific place
+
+ Locations:
+ - G_VAR_GISRC
+ - G_VAR_MAPSET
- Locations:
- - G_VAR_GISRC
- - G_VAR_MAPSET
-
- G_fatal_error() is called when variable is not found.
-
- \param name variable name
- \param loc location id
-
- \return variable value
- \return NULL if not found
+ G_fatal_error() is called when variable is not found.
+
+ \param name variable name
+ \param loc location id
+
+ \return variable value
+ \return NULL if not found
*/
const char *G_getenv2(const char *name, int loc)
{
@@ -321,13 +319,13 @@
return NULL;
}
-/**
- \brief Get environment variable
-
- \param name variable name
-
- \return char pointer to value for name
- \return NULL if name not set
+/*!
+ \brief Get environment variable
+
+ \param name variable name
+
+ \return char pointer to value for name
+ \return NULL if name not set
*/
const char *G__getenv(const char *name)
{
@@ -339,14 +337,14 @@
return get_env(name, G_VAR_GISRC);
}
-/**
- \brief Get environment variable from specific place
-
- \param name variable name
- \param loc location id
-
- \return char pointer to value for name
- \return NULL if name not set
+/*!
+ \brief Get environment variable from specific place
+
+ \param name variable name
+ \param loc location id
+
+ \return char pointer to value for name
+ \return NULL if name not set
*/
const char *G__getenv2(const char *name, int loc)
{
@@ -358,16 +356,14 @@
return get_env(name, loc);
}
-/**
- \brief Set environment variable
+/*!
+ \brief Set environment variable
- If value is NULL, becomes an G_unsetenv().
- Updates .gisrc
-
- \param name variable name
- \param value variable value
-
- \return
+ If value is NULL, becomes an G_unsetenv().
+ Updates .gisrc
+
+ \param name variable name
+ \param value variable value
*/
void G_setenv(const char *name, const char *value)
{
@@ -376,17 +372,15 @@
write_env(G_VAR_GISRC);
}
-/**
- \brief Set environment variable from specific place
-
- If value is NULL, becomes an G_unsetenv().
- Updates .gisrc
-
- \param name variable name
- \param value variable value
- \param loc location id
-
- \return
+/*!
+ \brief Set environment variable from specific place
+
+ If value is NULL, becomes an G_unsetenv().
+ Updates .gisrc
+
+ \param name variable name
+ \param value variable value
+ \param loc location id
*/
void G_setenv2(const char *name, const char *value, int loc)
{
@@ -395,13 +389,11 @@
write_env(loc);
}
-/**
- \brief Set environment name to value
-
- \param name variable name
- \param value variable value
-
- \return
+/*!
+ \brief Set environment name to value
+
+ \param name variable name
+ \param value variable value
*/
void G__setenv(const char *name, const char *value)
{
@@ -409,14 +401,12 @@
set_env(name, value, G_VAR_GISRC);
}
-/**
- \brief Set environment name to value from specific place
-
- \param name variable name
- \param value variable value
- \param loc location id
-
- \return
+/*!
+ \brief Set environment name to value from specific place
+
+ \param name variable name
+ \param value variable value
+ \param loc location id
*/
void G__setenv2(const char *name, const char *value, int loc)
{
@@ -424,14 +414,12 @@
set_env(name, value, loc);
}
-/**
- \brief Remove name from environment
-
- Updates .gisrc
-
- \param name variable name
-
- \return
+/*!
+ \brief Remove name from environment
+
+ Updates .gisrc
+
+ \param name variable name
*/
void G_unsetenv(const char *name)
{
@@ -440,15 +428,13 @@
write_env(G_VAR_GISRC);
}
-/**
- \brief Remove name from environment from specific place
-
- Updates .gisrc
-
- \param name variable name
- \param loc location id
-
- \return
+/*!
+ \brief Remove name from environment from specific place
+
+ Updates .gisrc
+
+ \param name variable name
+ \param loc location id
*/
void G_unsetenv2(const char *name, int loc)
{
@@ -457,10 +443,8 @@
write_env(loc);
}
-/**
- \brief Writes current environment to .gisrc
-
- \return
+/*!
+ \brief Writes current environment to .gisrc
*/
void G__write_env(void)
{
@@ -468,20 +452,21 @@
write_env(G_VAR_GISRC);
}
-/**
- \brief Get variable name for index n.
+/*!
+ \brief Get variable name for index n.
+
+ For example:
- For example:
- \code
+ \code
for (n = 0; ; n++)
if ((name = G__env_name(n)) == NULL)
break;
- \endcode
+ \endcode
- \param n index of variable
-
- \return pointer to variable name
- \return NULL not found
+ \param n index of variable
+
+ \return pointer to variable name
+ \return NULL not found
*/
const char *G__env_name(int n)
{
@@ -495,20 +480,16 @@
return NULL;
}
-/**
- \brief Initialize init array for G_VAR_GISRC.
-
- \return
+/*!
+ \brief Initialize init array for G_VAR_GISRC.
*/
void G__read_env(void)
{
st->init[G_VAR_GISRC] = 0;
}
-/**
- \brief Set up alternative environment variables
-
- \return
+/*!
+ \brief Set up alternative environment variables
*/
void G__create_alt_env(void)
{
@@ -528,10 +509,8 @@
}
}
-/**
- \brief Switch environments
-
- \return
+/*!
+ \brief Switch environments
*/
void G__switch_env(void)
{
Modified: grass/trunk/lib/gis/error.c
===================================================================
--- grass/trunk/lib/gis/error.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/error.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,9 +1,9 @@
/*!
* \file error.c
*
- * \brief GIS Library: Error messages functions
+ * \brief GIS Library - Error messages functions
*
- * (C) 1999-2008 by the GRASS Development Team
+ * (C) 1999-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public
* License (>=v2). Read the file COPYING that comes with GRASS
@@ -198,9 +198,13 @@
/*!
* \brief Turn on/off no_sleep flag
*
- * \param flag if non-zero/zero value is given G_sleep() will be activated/deactivated
+ * If <em>flag</em> is 0, then no pause will occur after printing an
+ * error or warning message. Otherwise the pause will occur.
+ *
+ * \param flag if non-zero/zero value is given G_sleep() will be
+ * activated/deactivated
*
- * \return previous flag
+ * \return previous no_sleep value
*/
int G_sleep_on_error(int flag)
{
Modified: grass/trunk/lib/gis/find_file.c
===================================================================
--- grass/trunk/lib/gis/find_file.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/find_file.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,9 +1,9 @@
/*!
- \file find_file.c
+ \file gis/find_file.c
- \brief GIS library - find GRASS data base files
+ \brief GIS library - Find GRASS data base files
- (C) 2001-2008 by the GRASS Development Team
+ (C) 2001-2009 by the GRASS Development Team
This program is free software under the
GNU General Public License (>=v2).
@@ -133,70 +133,94 @@
}
/*!
- * \brief searches for a file from the mapset search list
- * or in a specified mapset.
- * returns the mapset name where the file was found.
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset.
*
- * notes:
+ * Returns the mapset name where the file was found.
*
- * If the user specifies a fully qualified element (<i>name at mapset</i>)
- * which exists, then <i>G_find_file()</i> modifies <b>name</b>
- * by removing the "@<i>mapset</i>" part.
+ * If the user specifies a fully qualified element (<i>name at mapset</i>)
+ * which exists, then G_find_file() modifies <i>name</i>
+ * by removing the "@<i>mapset</i>" part.
*
- * Rejects all names that begin with "."
+ * Rejects all names that begin with "."
*
- * If <b>name</b> is of the form nnn in ppp then only mapset ppp
- * is searched.
+ * If <i>name</i> is of the form nnn in ppp then only mapset ppp
+ * is searched.
*
- * \param const char *element database element (eg, "cell", "cellhd", "colr", etc)
- * \param char *name file name to look for
- * \param const char *mapset mapset to search. if mapset is ""
- * will search in mapset search list
+ * \param element database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name file name to look for
+ * \param mapset mapset to search. if mapset is "" will search in mapset search list
*
- * \return char * pointer to a string with name of mapset
- * where file was found, or NULL if not found
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
*/
-
const char *G_find_file(const char *element, char *name, const char *mapset)
{
return find_file1(0, NULL, element, name, mapset);
}
+/*!
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset.
+ *
+ * Returns the mapset name where the file was found.
+ *
+ * \param dir file directory
+ * \param element database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name file name to look for
+ * \param mapset mapset to search. if mapset is "" will search in mapset search list
+ *
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
+ */
const char *G_find_file_misc(const char *dir,
- const char *element, char *name, const char *mapset)
+ const char *element, char *name, const char *mapset)
{
return find_file1(1, dir, element, name, mapset);
}
-
/*!
- * \brief searches for a file from the mapset search list
- * or in a specified mapset. (look but don't touch)
- * returns the mapset name where the file was found.
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset. (look but don't touch)
*
- * Exactly the same as G_find_file() except that if <b>name</b> is in
- * the form "<i>name at mapset</i>", and is found, G_find_file2() will not
- * alter <b>name</b> by removing the "@<i>mapset</i>" part.
+ * Returns the mapset name where the file was found.
*
- * note:
- * rejects all names that begin with "."
+ * Exactly the same as G_find_file() except that if <i>name</i> is in
+ * the form "<i>name at mapset</i>", and is found, G_find_file2() will
+ * not alter <i>name</i> by removing the "@<i>mapset</i>" part.
*
- * \param char *element database element (eg, "cell", "cellhd", "colr", etc)
- * \param char *name file name to look for
- * \param char *mapset mapset to search. if mapset is ""
- * will search in mapset search list
+ * Rejects all names that begin with "."
*
- * \return char * pointer to a string with name of mapset
- * where file was found, or NULL if not found
+ * \param element database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name file name to look for
+ * \param mapset mapset to search. if mapset is "" will search in mapset search list
+ *
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
*/
const char *G_find_file2(const char *element, const char *name, const char *mapset)
{
return find_file(0, NULL, element, name, mapset);
}
+/*!
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset. (look but don't touch)
+ *
+ * Returns the mapset name where the file was found.
+ *
+ *
+ * \param dir file directory
+ * \param element database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name file name to look for
+ * \param mapset mapset to search. if mapset is "" will search in mapset search list
+ *
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
+ */
const char *G_find_file2_misc(const char *dir,
- const char *element,
- const char *name, const char *mapset)
+ const char *element,
+ const char *name, const char *mapset)
{
return find_file(1, dir, element, name, mapset);
}
Modified: grass/trunk/lib/gis/geodist.c
===================================================================
--- grass/trunk/lib/gis/geodist.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/geodist.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,33 +1,29 @@
-
-/**
- * \file geodist.c
+/*!
+ * \file gis/geodist.c
*
* \brief GIS Library - Geodesic distance routines.
*
* Distance from point to point along a geodesic code from Paul
- * D. Thomas, 1970<br> "Spheroidal Geodesics, Reference Systems, and
- * Local Geometry"<br> U.S. Naval Oceanographic Office, p. 162<br>
- * Engineering Library 526.3 T36s
+ * D. Thomas, 1970 "Spheroidal Geodesics, Reference Systems, and Local
+ * Geometry" U.S. Naval Oceanographic Office, p. 162 Engineering
+ * Library 526.3 T36s
* http://stinet.dtic.mil/oai/oai?&verb=getRecord&metadataPrefix=html&identifier=AD0703541
*
* <b>WARNING:</b> this code is preliminary and may be changed,
* including calling sequences to any of the functions defined here.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <math.h>
#include <grass/gis.h>
#include "pi.h"
-
static struct state {
double boa;
double f;
@@ -38,18 +34,17 @@
static struct state *st = &state;
-/**
+/*!
* \brief Begin geodesic distance.
*
* Initializes the distance calculations for the ellipsoid with
- * semi-major axis <b>a</b> (in meters) and ellipsoid eccentricity squared
- * <b>e2</b>. It is used only for the latitude-longitude projection.
- * <br>
+ * semi-major axis <i>a</i> (in meters) and ellipsoid eccentricity squared
+ * <i>e2</i>. It is used only for the latitude-longitude projection.
+ *
* <b>Note:</b> Must be called once to establish the ellipsoid.
*
- * \param[in] a semi-major axis in meters
- * \param[in] e2 ellipsoid eccentricity
- * \return
+ * \param a semi-major axis in meters
+ * \param e2 ellipsoid eccentricity
*/
void G_begin_geodesic_distance(double a, double e2)
@@ -60,16 +55,14 @@
st->ff64 = st->f * st->f / 64;
}
-
-
-/**
+/*!
* \brief Sets geodesic distance lat1.
*
* Set the first latitude.
*
* <b>Note:</b> Must be called first.
*
- * \param[in] lat1 first latitude
+ * \param lat1 first latitude
* \return
*/
@@ -78,18 +71,15 @@
st->t1r = atan(st->boa * tan(Radians(lat1)));
}
-
-/**
+/*!
* \brief Sets geodesic distance lat2.
*
* Set the second latitude.
*
* <b>Note:</b> Must be called second.
*
- * \param[in] lat2 second latitidue
- * \return
+ * \param lat2 second latitidue
*/
-
void G_set_geodesic_distance_lat2(double lat2)
{
double stm, ctm, sdtm, cdtm;
@@ -115,20 +105,19 @@
st->t4 = cdtm * cdtm - stm * stm;
}
-
-/**
+/*!
* \brief Calculates geodesic distance.
*
- * Calculates the geodesic distance from <b>lon1,lat1</b> to
- * <b>lon2,lat2</b> in meters where <b>lat1</b> was the latitude passed
- * to <i>G_set_geodesic_distance_latl()</i> and <b>lat2</b> was the
- * latitude passed to <i>G_set_geodesic_distance_lat2()</i>.
+ * Calculates the geodesic distance from <i>lon1,lat1</i> to
+ * <i>lon2,lat2</i> in meters where <i>lat1</i> was the latitude
+ * passed to G_set_geodesic_distance_latl() and <i>lat2</i> was the
+ * latitude passed to G_set_geodesic_distance_lat2().
*
- * \param[in] lon1 first longitude
- * \param[in] lon2 second longitude
+ * \param lon1 first longitude
+ * \param lon2 second longitude
+ *
* \return double distance in meters
*/
-
double G_geodesic_distance_lon_to_lon(double lon1, double lon2)
{
double a, cd, d, e, /*dl, */
@@ -190,20 +179,20 @@
+ y * (-2 * d + e * y) + d * x * y));
}
-
-/**
+/*!
* \brief Calculates geodesic distance.
*
- * Calculates the geodesic distance from <b>lon1,lat1</b> to
- * <b>lon2,lat2</b> in meters.
- * <br>
- * <b>Note:</b> The calculation of the geodesic distance is fairly costly.
+ * Calculates the geodesic distance from <i>lon1,lat1</i> to
+ * <i>lon2,lat2</i> in meters.
+ *
+ * <b>Note:</b> The calculation of the geodesic distance is fairly
+ * costly.
*
- * \param[in] lon1,lat1 longitude,latitude of first point
- * \param[in] lon2,lat2 longitude,latitude of second point
+ * \param lon1,lat1 longitude,latitude of first point
+ * \param lon2,lat2 longitude,latitude of second point
+ *
* \return distance in meters
*/
-
double G_geodesic_distance(double lon1, double lat1, double lon2, double lat2)
{
G_set_geodesic_distance_lat1(lat1);
Modified: grass/trunk/lib/gis/get_ellipse.c
===================================================================
--- grass/trunk/lib/gis/get_ellipse.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/get_ellipse.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,22 +1,23 @@
/*!
- \file get_ellipse.c
+ \file gis/get_ellipse.c
- \brief Getting ellipsoid parameters from the database.
+ \brief GIS Library - Getting ellipsoid parameters from the database.
- This routine returns the ellipsoid parameters from the database.
- If the PROJECTION_FILE exists in the PERMANENT mapset, read info
- from that file, otherwise return WGS 84 values.
+ This routine returns the ellipsoid parameters from the database.
+ If the PROJECTION_FILE exists in the PERMANENT mapset, read info
+ from that file, otherwise return WGS 84 values.
- Returns: 1 ok, 0 default values used.
- Dies with diagnostic if there is an error
+ New 05/2000 by al: for datum shift the f parameter is needed too.
+ This all is not a clean design, but it keeps backward-
+ compatibility.
+ Looks up ellipsoid in ellipsoid table and returns the
+ a, e2 and f parameters for the ellipsoid
+
+ (C) 2001-2009 by the GRASS Development Team
- (C) 2001-2008 by the GRASS Development Team
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
- This program is free software under the
- GNU General Public License (>=v2).
- Read the file COPYING that comes with GRASS
- for details.
-
\author CERL
*/
@@ -94,13 +95,12 @@
}
/*!
- * \brief get ellipsoid parameters by name
+ * \brief Get ellipsoid parameters by name
*
- * This routine returns the semi-major axis <b>a</b> (in meters) and
- * eccentricity squared <b>e2</b> for the named ellipsoid. Returns 1
- * if <b>name</b> is a known ellipsoid, 0 otherwise.
+ * This routine returns the semi-major axis <i>a</i> (in meters) and
+ * eccentricity squared <i>e2</i> for the named ellipsoid.
*
- * \param[in] name ellipsoid name
+ * \param name ellipsoid name
* \param[out] a semi-major axis
* \param[out] e2 eccentricity squared
*
@@ -124,16 +124,16 @@
}
/*!
- * \brief get ellipsoid name
+ * \brief Get ellipsoid name
*
* This function returns a pointer to the short name for the
- * <b>n</b><i>th</i> ellipsoid. If <b>n</b> is less than 0 or greater
+ * <i>n</i><i>th</i> ellipsoid. If <i>n</i> is less than 0 or greater
* than the number of known ellipsoids, it returns a NULL pointer.
*
- * \param[in] n ellipsoid identificator
+ * \param n ellipsoid identificator
*
- * \return char * ellipsoid name
- * \return NULL if no ellipsoid found
+ * \return ellipsoid name
+ * \return NULL if no ellipsoid found
*/
const char *G_ellipsoid_name(int n)
{
@@ -141,26 +141,14 @@
return n >= 0 && n < table.count ? table.ellipses[n].name : NULL;
}
-/*
- * new 05/2000 by al: for datum shift the f parameter is needed too.
- * this all is not a clean design, but it keeps backward-
- * compatibility.
- * looks up ellipsoid in ellipsoid table and returns the
- * a, e2 and f parameters for the ellipsoid
- *
- * returns 1 if ok,
- * 0 if not found in table
- */
-
/*!
- * \brief get spheroid parameters by name
+ * \brief Get spheroid parameters by name
*
- * This function returns the semi-major axis <b>a</b> (in meters), the
- * eccentricity squared <b>e2</b> and the inverse flattening <b>f</b>
- * for the named ellipsoid. Returns 1 if <b>name</b> is a known
- * ellipsoid, 0 otherwise.
+ * This function returns the semi-major axis <i>a</i> (in meters), the
+ * eccentricity squared <i>e2</i> and the inverse flattening <i>f</i>
+ * for the named ellipsoid.
*
- * \param[in] name spheroid name
+ * \param name spheroid name
* \param[out] a semi-major axis
* \param[out] e2 eccentricity squared
* \param[out] f inverse flattening
@@ -187,18 +175,17 @@
/*!
- * \brief get description for <b>n</b><i>th</i> ellipsoid
+ * \brief Get description for nth ellipsoid
*
* This function returns a pointer to the description text for the
- * <b>n</b><i>th</i> ellipsoid. If <b>n</b> is less than 0 or greater
+ * <i>n</i>th ellipsoid. If <i>n</i> is less than 0 or greater
* than the number of known ellipsoids, it returns a NULL pointer.
*
- * \param[in] n ellipsoid identificator
+ * \param n ellipsoid identificator
*
* \return pointer to ellipsoid description
* \return NULL if no ellipsoid found
*/
-
const char *G_ellipsoid_description(int n)
{
G_read_ellipsoid_table(0);
@@ -253,6 +240,15 @@
return G_strcasecmp(a->name, b->name);
}
+/*!
+ \brief Read ellipsoid table
+
+ \param fatal non-zero value for G_fatal_error(), otherwise
+ G_warning() is used
+
+ \return 1 on sucess
+ \return 0 on error
+*/
int G_read_ellipsoid_table(int fatal)
{
FILE *fd;
Modified: grass/trunk/lib/gis/get_window.c
===================================================================
--- grass/trunk/lib/gis/get_window.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/get_window.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,25 +1,16 @@
-/*
- *************************************************************************
- * G_get_window (window)
- * struct Cell_head *window
- *
- * read the current mapset window
- * dies if error
- *
- *************************************************************************
- * G_get_default_window (window)
- * struct Cell_head *window
- *
- * read the default window for the location
- * dies if error
- *
- *************************************************************************
- * char *
- * G__get_window (window, element, name, mapset)
- * read the window 'name' in 'element' in 'mapset'
- * returns NULL if ok, error message if not
- ************************************************************************/
+/*!
+ \file gis/get_window.c
+ \brief GIS Library - Get window (i.e. GRASS region)
+
+ (C) 2001-2009 by the GRASS Development Team
+
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+
+ \author Original author CERL
+*/
+
#include <stdlib.h>
#include "G.h"
#include <grass/gis.h>
@@ -33,21 +24,22 @@
static struct state *st = &state;
/*!
- * \brief read the database region
+ * \brief Read the database region
*
* Reads the database region as stored in the WIND file in the user's
- * current mapset <b>into region.</b>
+ * current mapset into region.
+ *
* 3D values are set to defaults if not available in WIND file.
- * An error message is printed and exit( ) is called if there is a problem reading
+ * An error message is printed and exit() is called if there is a problem reading
* the region.
- * <b>Note.</b> GRASS applications that read or write raster maps should not
- * use this routine since its use implies that the active module region will not
- * be used. Programs that read or write raster map data (or vector data) can
- * query the active module region <i>using G_window_rows and
- * G_window_cols..</i>
*
- * \param region
- * \return int
+ * <b>Note:</b> GRASS applications that read or write raster maps
+ * should not use this routine since its use implies that the active
+ * module region will not be used. Programs that read or write raster
+ * map data (or vector data) can query the active module region using
+ * G_window_rows() and G_window_cols().
+ *
+ * \param window pointer to Cell_head
*/
void G_get_window(struct Cell_head *window)
@@ -76,7 +68,8 @@
}
if (err)
- G_fatal_error(_("region for current mapset %s\nrun \"g.region\""), err);
+ G_fatal_error(_("Region for current mapset %s. "
+ "Run \"g.region\" to fix the current region."), err);
*window = st->dbwindow;
@@ -88,17 +81,16 @@
G_initialize_done(&st->initialized);
}
-
/*!
- * \brief read the default region
+ * \brief Read the default region
*
- * Reads the default region for the location into <b>region.</b>
- * 3D values are set to defaults if not available in WIND file.
- * An error message is printed and exit( ) is called if there is a problem
- * reading the default region.
+ * Reads the default region for the location into <i>region.</i> 3D
+ * values are set to defaults if not available in WIND file.
*
- * \param region
- * \return int
+ * An error message is printed and exit() is called if there is a
+ * problem reading the default region.
+ *
+ * \param[out] window pointer to Cell_head
*/
void G_get_default_window(struct Cell_head *window)
@@ -106,9 +98,20 @@
const char *err = G__get_window(window, "", "DEFAULT_WIND", "PERMANENT");
if (err)
- G_fatal_error(_("default region %s"), err);
+ G_fatal_error(_("Default region %s"), err);
}
+/*!
+ \brief Get cwindow (region) of selected map layer
+
+ \param window pointer to Cell_head
+ \param element element name
+ \param name map name
+ \param mapset mapset name
+
+ \return string on error
+ \return NULL on success
+*/
char *G__get_window(struct Cell_head *window,
const char *element, const char *name, const char *mapset)
{
Modified: grass/trunk/lib/gis/getl.c
===================================================================
--- grass/trunk/lib/gis/getl.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/getl.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,3 +1,16 @@
+/*!
+ * \file gis/getl.c
+ *
+ * \brief GIS Library - Get line of text from file
+ *
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <stdio.h>
#include <grass/gis.h>
@@ -2,14 +15,15 @@
/*!
- * \brief gets a line of text from a file
+ * \brief Gets a line of text from a file
*
- * This routine runs fgets() to fetch a line of text from a file (advancing
- * file pointer) and removes trailing newline. fgets() does not recognize
- * '<code>\\r</code>' as an EOL and will read past it.<br>
+ * This routine runs fgets() to fetch a line of text from a file
+ * (advancing file pointer) and removes trailing newline. fgets() does
+ * not recognize '<code>\\r</code>' as an EOL and will read past * it.
*
- * \param buf: string buffer to receive read data
- * \param n: maximum number of bytes to read
- * \param fd: file descriptor structure
- * \return 1 if ok, 0 if EOF
+ * \param buf string buffer to receive read data
+ * \param n maximum number of bytes to read
+ * \param fd file descriptor structure
+ *
+ * \return 1 on success
+ * \return 0 EOF
*/
-
int G_getl(char *buf, int n, FILE * fd)
@@ -25,30 +39,28 @@
return 1;
}
-
-
/*!
- * \brief gets a line of text from a file of any pedigree
+ * \brief Gets a line of text from a file of any pedigree
*
- * This routine is like G_getl() but is more portable.
- * It supports text files created on various platforms (UNIX, MacOS9, DOS),
- * i.e. <code>\\n (\\012)</code>, <code>\\r (\\015)</code>, and
+ * This routine is like G_getl() but is more portable. It supports
+ * text files created on various platforms (UNIX, MacOS9, DOS),
+ * i.e. <code>\\n (\\012)</code>, <code>\\r (\\015)</code>, and
* <code>\\r\\n (\\015\\012)</code> style newlines.
- * <br>
- * <br>
- * Reads in at most <b>n-1</b> characters from stream (the last spot is
- * reserved for the end-of-string NUL) and stores them into the buffer
- * pointed to by <b>buf</b>. Reading stops after an EOF or a newline.
- * New line is not stored in the buffer. At least <b>n</b> must be allocated
- * for the string buffer.<br>
+ *
+ *
+ * Reads in at most <i>n-1</i> characters from stream (the last spot
+ * is reserved for the end-of-string NUL) and stores them into the
+ * buffer pointed to by <i>buf</i>. Reading stops after an EOF or a
+ * newline. New line is not stored in the buffer. At least <i>n</i>
+ * must be allocated for the string buffer.
*
- * \param buf: string buffer to receive read data, at least <b>n</b> must
- * be allocated
+ * \param buf: string buffer to receive read data, at least <i>n</i> must be allocated
* \param n: maximum number of bytes to read
* \param fd: file descriptor structure
- * \return 1 if ok, 0 if EOF
+ *
+ * \return 1 on success
+ * \return 0 EOF
*/
-
int G_getl2(char *buf, int n, FILE * fd)
{
int i = 0;
Modified: grass/trunk/lib/gis/gisbase.c
===================================================================
--- grass/trunk/lib/gis/gisbase.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/gisbase.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -12,33 +12,32 @@
/*!
- * \brief top level module directory
+ * \brief Get full path name of the top level module directory
*
- * Returns the full
- * path name of the top level directory for GRASS programs. This directory will
- * have subdirectories which will contain modules and files required for the
- * running of the system. Some of these directories are:
- \code
+ * Returns the full path name of the top level directory for GRASS
+ * programs. This directory will have subdirectories which will
+ * contain modules and files required for the running of the
+ * system. Some of these directories are:
+
+ \verbatim
bin commands run by the user
etc modules and data files used by GRASS commands
- txt help files
- menu files used by the <i>grass3</i> menu interface
- \endcode
- * The use of G_gisbase( ) to find these subdirectories enables GRASS modules
- * to be written independently of where the GRASS system is actually installed
- * on the machine. For example, to run the module <i>sroff</i> in the GRASS
- * <i>etc</i> directory:
+ \endverbatim
+
+ * The use of G_gisbase() to find these subdirectories enables GRASS
+ * modules to be written independently of where the GRASS system is
+ * actually installed on the machine. For example, to run the module
+ * <i>sroff</i> in the GRASS <i>etc</i> directory:
+
\code
char command[200];
- sprintf (command, "%s/etc/sroff", G_gisbase( ) );
- G_spawn (command, "sroff", NULL);
+ sprintf(command, "%s/etc/sroff", G_gisbase());
+ G_spawn(command, "sroff", NULL);
\endcode
*
- * \param void
- * \return char *
+ * \return pointer to a string
*/
-
const char *G_gisbase(void)
{
return G_getenv("GISBASE");
Modified: grass/trunk/lib/gis/gisdbase.c
===================================================================
--- grass/trunk/lib/gis/gisdbase.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/gisdbase.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,9 +1,9 @@
/*!
- \file gisdbase.c
+ \file gis/gisdbase.c
\brief GIS library - environment routines (gisdbase)
- (C) 2001-2008 by the GRASS Development Team
+ (C) 2001-2009 by the GRASS Development Team
This program is free software under the
GNU General Public License (>=v2).
@@ -19,13 +19,10 @@
* \brief Get name of top level database directory
*
* Returns the full UNIX path name of the directory which holds the
- * database locations. See GISDBASE for a full explanation of this
- * directory.
+ * database locations.
*
- * \param
* \return pointer to string containing the base directory
*/
-
const char *G_gisdbase(void)
{
return G_getenv("GISDBASE");
Modified: grass/trunk/lib/gis/gislib.dox
===================================================================
--- grass/trunk/lib/gis/gislib.dox 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/gislib.dox 2009-06-05 15:17:52 UTC (rev 37744)
@@ -30,64 +30,62 @@
- \subpage TimeStamp_functions
- \subpage GRASS_GIS_Library_Overview
-The <i>GIS Library</i> is the primary programming library provided
+The <em>GIS Library</em> is the primary programming library provided
with the GRASS system. <b>Programs must use this libary to access the
-database.</b> It contains the routines which locate, create, open,
+GIS database.</b> It contains the routines which locate, create, open,
rename, and remove GRASS database files. It contains the routines
which read and write raster files. It contains routines which
interface the user to the database, including prompting the user,
-listing available files, validating user access, etc. It also has
+listing available files, validating user access, etc. It also has
some general purpose routines (string manipulation, user information,
etc.) which are not tied directly to database processing.
-It is assumed that the reader has read Database_Structure for a
-general description of GRASS databases, Raster_Maps for details about
-raster map layers in GRASS, and Region_and_Mask which discusses
-regions and masks. The routines in the <i>GIS Library</i> are
-presented in functional groupings, rather than in alphabetical
-order. The order of presentation will, it is hoped, provide a better
-understanding of how the library is to be used, as well as show the
-interrelationships among the various routines. Note that a good way to
-understand how to use these routines is to look at the source code for
-GRASS modules which use them. Most routines in this library require
-that the header file "gis.h" be included in any code using these
-routines. Therefore, programmers should always include this file when
-writing code using routines from this library:
+It is assumed that the reader has read \ref location for a general
+description of GRASS databases, \ref Raster_File_Processing for
+details about raster map layers in GRASS, and Region_and_Mask
+(<b>???</b>) which discusses regions and masks. The routines in the
+<em>GIS Library</em> are presented in functional groupings, rather
+than in alphabetical order. The order of presentation will, it is
+hoped, provide a better understanding of how the library is to be
+used, as well as show the interrelationships among the various
+routines. Note that a good way to understand how to use these routines
+is to look at the source code for GRASS modules which use them. Most
+routines in this library require that the header file <b>grass/gis.h</b> be
+included in any code using these routines. Therefore, programmers
+should always include this file when writing code using routines from
+this library:
-\verbatim
+\code
#include <grass/gis.h>
-\endverbatim
+\endcode
-<b>Note</b>. All routines and global variables in this library,
+<b>Note:</b> All routines and global variables in this library,
documented or undocumented, start with the prefix <b>G_</b>. To avoid
name conflicts, programmers should not create variables or routines in
their own modules which use this prefix.
\subsection init Library Initialization
-
-<P>
It is <B>mandatory</B> that the system be initialized before any other
library routines are called.
-<P>
-int G_gisinit() initialize gis library
+G_gisinit() initialize GIS library.
This routine reads the user's GRASS environment file into memory and
makes sure that the user has selected a valid database and mapset. It
also initializes hidden variables used by other routines. If the
user's database information is invalid, an error message is printed
-and the module exits. The <B>program_name</B> is stored for later
-recall by <I>G_program_name.</I> It is recommended that argv[0] be
-used for the <B>program_name:</B>
+and the module exits. The <b>program_name</b> is stored for later
+recall by G_program_name(). It is recommended that argv[0] be
+used for the program_name:
-\verbatim
+\code
int main (int argc, char **argv)
{
G_gisinit(argv[0]);
}
-\endverbatim
+\endcode
\subsection diag Diagnostic Messages
@@ -95,106 +93,88 @@
report warning and error messages. They may also be used directly by
GRASS programs.
-<P> int G_fatal_error() print error message and exit
+ - G_fatal_error() print error message and exit
-<P> int G_debug() print debug message
+ - G_debug() print debug message
-<P> int G_warning() print warning message and continue
+ - G_warning() print warning message and continue
These routines report errors to the user. The normal mode is to write
-the <B>message</B> to the screen (on the standard error output) and
-wait a few seconds. G_warning() will return and
-G_fatal_error() will exit.
+the <em>message</em> to the screen (on the standard error
+output). G_warning() will return and G_fatal_error() will exit.
-<P>
If the standard error output is not a tty device, then the message is
mailed to the user instead.
-<P> If the file GIS_ERROR_LOG exists (with write permission), in
-either the user's home directory or in the $GISBASE directory, the
+If the file GIS_ERROR_LOG exists (with write permission), in either
+the user's home directory or in the <tt>$GISBASE</tt> directory, the
messages will also be logged to this file.
-<P> While most applications will find the normal error reporting quite
+While most applications will find the normal error reporting quite
adequate, there will be times when different handling is needed. For
example, graphics modules may want the messages displayed graphically
instead of on the standard error output. If the programmer wants to
handle the error messages differently, the following routines can be
used to modify the error handling:
-<P>
-int G_set_error_routine() change error handling
+ - G_set_error_routine() change error handling
This routine provides a different error handler for G_fatal_error()
-and G_warning(). The <B>handler</B> routine must be defined as follows:
+and G_warning(). The <m>handler</em> routine must be defined as
+follows:
-\verbatim
-int handler (char *message, int fatal)
-\endverbatim
+\code
+int handler(char *message, int fatal)
+\endcode
-<P>
-where <B>message</B> is the message to be handled and <B>fatal</B>
-indicates the type of error: 1 (fatal error) or 0 (warning).
+where <i>message</i> is the message to be handled and <i>fatal</i>
+indicates the type of error:
-<P> <B>Note.</B> The handler only provides a way to send the message
+ - 1 (fatal error)
+ - or 0 (warning).
+
+<b>Note:</b> The handler only provides a way to send the message
somewhere other than to the error output. If the error is fatal, the
module will exit after the handler returns.
-<P>
-int G_unset_error_routine() reset normal error handling
+ - G_unset_error_routine() reset normal error handling
-This routine resets the error handling for <I>G_fatal_error()</I> and
-<I>G_warning()</I> back to the default action.
+This routine resets the error handling for G_fatal_error() and
+G_warning() back to the default action.
-<P>
-int G_sleep_on_error() sleep on error?
+ - G_sleep_on_error() sleep on error
-If <B>flag</B> is 0, then no pause will occur after printing an error
-or warning message. Otherwise the pause will occur.
+ - G_suppress_warnings() suppress warnings
-<P>
-int G_suppress_warnings() suppress warnings?
-
-If <B>flag</B> is 0, then <I>G_warning()</I> will no longer print
-warning messages. If <B>flag</B> is 1, then G_warning() will print
-warning messages.
-
-<P>
-<B>Note.</B> This routine has no effect on <I>G_fatal_error().</I>
-
-
\subsection envir Environment and Database Information
-<P> The following routines return information about the current
-database selected by the user. Some of this information is retrieved
-from the user's GRASS environment file. Some of it comes from files in
-the database itself. See \ref Environment_Variables for a discussion of
+The following routines return information about the current database
+selected by the user. Some of this information is retrieved from the
+user's GRASS environment file. Some of it comes from files in the
+database itself. See \ref Environment_Variables for a discussion of
the GRASS environment.
-<P>
The following four routines can be used freely by the programmer:
-<P> char * G_location() current location name
+ - G_location() current location name
Returns the name of the current database location. This routine should
be used by modules that need to display the current location to the
user. See \ref Locations for an explanation of locations.
-<P>
-char * G_mapset() current mapset name
+ - G_mapset() current mapset name
Returns the name of the current mapset in the current location. This
routine is often used when accessing files in the current mapset. See
-Mapsets for an explanation of mapsets.
+\ref Mapsets for an explanation of mapsets.
-<P>
-char * G_myname() location title
+ - G_myname() location title
Returns a one line title for the database location. This title is read
-from the file MYNAME in the PERMANENT mapset. See also
-\ref Permanent_Mapset for a discussion of the PERMANENT mapset.
+from the file MYNAME in the PERMANENT mapset. See also \ref
+Permanent_Mapset for a discussion of the PERMANENT mapset.
-<P>
-char * G_gisbase() top level module directory
+ - G_gisbase() top level module directory
Returns the full path name of the top level directory for GRASS
programs. This directory will have subdirectories which will contain
@@ -207,204 +187,80 @@
html help files
\endverbatim
-
-<P>
The use of G_gisbase() to find these subdirectories enables GRASS modules
to be written independently of where the GRASS system is actually installed
-on the machine. For example, to run the module <I>sroff</I> in the GRASS
-<I>etc</I> directory:
+on the machine. For example, to run the module <i>sroff</i> in the GRASS
+<tt>etc</tt> directory:
-\verbatim
+\code
char command[200];
-sprintf (command, "%s/etc/sroff", G_gisbase() );
-system (command);
-\endverbatim
+sprintf(command, "%s/etc/sroff", G_gisbase());
+G_spawn(command, "sroff", NULL);
+\endcode
-<P>
The following two routines return full path UNIX directory names. They
should be used only in special cases. They are used by other routines
in the library to build full UNIX file names for database
files. <B>The programmer should not use the next two routines to
bypass the normal database access routines.</B>
-<P>
-char * G_gisdbase() top level database directory
+ - G_gisdbase() top level database directory
-Returns the full UNIX path name of the directory which holds the database
-locations. See \ref GISDBASE for a full explanation of this directory.
+Returns the full UNIX path name of the directory which holds the
+database locations. See \ref GISDBASE for a full explanation of this
+directory.
-<P>
-char * G_location_path() current location directory
+ - G_location_path() current location directory
Returns the full UNIX path name of the current database location. For
example, if the user is working in location <I>spearfish</I> in the
-<I>/home/user/grassdata</I> database directory, this routine will
+<tt>/home/user/grassdata</tt> database directory, this routine will
return a string which looks like
+<tt>/home/user/grassdata/spearfish</tt>.
-<P>
-<I>/home/user/grassdata/spearfish</I>.
-
-<BR>
-
-<P>
These next routines provide the low-level management of the
information in the user's GRASS environment file. <B>They should not
be used in place of the higher level interface routines described
above.</B>
-<P>
-int G_getenv() query GRASS environment variable
+ - G_getenv()
-<P>
-int G__getenv() query GRASS environment variable
+ - G__getenv()
-These routines look up the variable <B>name</B> in the GRASS
+These routines look up the variable <em>name</em> in the GRASS
environment and return its value (which is a character string). If
-<B>name</B> is not set, G_getenv() issues an error message and calls
+<em>name</em> is not set, G_getenv() issues an error message and calls
exit(). G__setenv() just returns the NULL pointer.
-<P>
-int G_setenv () set GRASS environment
- variable
+ - G_setenv ()
-<P>
-int G__setenv() set GRASS environment variable
+ - G__setenv()
-These routines set the the GRASS environment variable <B>name</B>
-to <B>value.</B> If <B>value</B> is NULL, the <B>name</B> is unset.
+These routines set the the GRASS environment variable <em>name</em> to
+<em>value</em>. If <em>value</em> is NULL, the <em>name</em> is unset.
-<P>
-Both routines set the value in module memory, but only G_setenv() writes the
-new value to the user's GRASS environment file.
+Both routines set the value in module memory, but only G_setenv()
+writes the new value to the user's GRASS environment file.
\subsection dbaseaccess Fundamental Database Access Routines
-
-<P>
The routines described in this section provide the low-level interface
to the GRASS database. They search the database for files, prompt the
user for file names, open files for reading or writing, etc. The
programmer should never bypass this level of database interface. These
-routines must be used to access the GRASS database unless there <B>are
+routines must be used to access the GRASS database unless there <b>are
other higher level library routines which perform the same
-function.</B> For example, routines to process raster files
-(Raster_File_Processing), vector files (Vector_File_Processing),
-etc., should be used instead.
+function</b>. For example, routines to process raster files (see \ref
+Raster_File_Processing), vector files (see \ref
+Vector_File_Processing), etc., should be used instead.
-<P>
-In the descriptions below, the term database <I>element</I> is used.
+In the descriptions below, the term database <i>element</i> is used.
Elements are subdirectories within a mapset and are associated with a
specific GRASS data type. For example, raster files live in the "cell"
and "fcell" element. See \ref Elements for more details.
-\subsection prompt Prompting for Database Files
-
-<P>
-The following routines interactively prompt the user for a file name
-from a specific database <B>element.</B> (See \ref Elements for an
-explanation of elements.) In each, the <B>prompt</B> string will be
-printed as the first line of the full prompt which asks the user to
-enter a file name. If <B>prompt</B> is the empty string "" then an
-appropriate prompt will be substituted. The name that the user enters
-is copied into the <B>name</B> buffer. The size of name should be
-large enough to hold any GRASS file name. Most systems allow file
-names to be quite long. It is recommended that name be declared char
-name[GNAME_MAX].
-
-The short (one or two word) <B>label</B> describing the <B>element</B>
-is used as part of a title when listing the files <B>in element.</B>
-
-<P>
-The user is required to enter a valid file name, or else hit the
-RETURN key to cancel the request. If the user enters an invalid
-response, a message is printed, and the user is prompted again. If the
-user cancels the request, the NULL pointer is returned. Otherwise the
-mapset where the file lives or is to be created is returned. Both the
-name and the mapset are used in other routines to refer to the file.
-
-<P>
-An example will be given here. The G_ask_old() routine used in the
-example is described a bit later. The user is asked to enter a file
-from the "paint/labels" element:
-
-\verbatim
-char name[GNAME_MAX];
-char *mapset;
-
-mapset = G_ask_old("", name, "paint/labels", "labels");
-if (mapset == NULL)
- exit(EXIT_SUCCESS); /* user canceled the request */
-\endverbatim
-
-<P>
-The user will see the following:
-
-\verbatim
-Enter the name of an existing labels file
-Enter 'list' for a list of existing labels files
-Hit RETURN to cancel request
-\endverbatim
-
-The last line of the prompt can be modified using G_set_ask_return_msg().
-
-<P>
-char * G_ask_old() prompt for existing database file
-
-The user is asked to enter the name of an existing database file.
-
-<P>
-<B>Note.</B> This routine looks for the file in the current mapset as
-well as other mapsets. The mapsets that are searched are determined
-from the user's mapset search path. See \ref Mapset_Search_Path for some
-more details about the search path.
-
-<P>
-char * G_ask_new() prompt for new database file
-The user is asked to enter the name of a new file which does not exist
-in the current mapset.
-
-<P>
-<B>Note.</B> The file chosen by the user may exist in other
-mapsets. This routine does not look in other mapsets, since the
-assumption is that <B>name</B> will be used to create a new file. New
-files are always created in the current mapset.
-
-<P>
-char * G_ask_in_mapset() prompt for existing database file
-
-The user is asked to enter the name of an file which exists in the
-current mapset.
-
-<P>
-<B>Note.</B> The file chosen by the user may or may not exist in other
-mapsets. This routine does not look in other mapsets, since the
-assumption is that <B>name</B> will be used to modify a file. GRASS
-only permits users to modify files in the current mapset.
-
-<P>
-char * G_ask_any() prompt for any valid file name
-
-The user is asked to enter any legal file name. If <B>warn</B> is 1
-and the file chosen exists in the current mapset, then the user is
-asked if it is ok to overwrite the file. If <B>warn</B> is 0, then any
-leg al name is accepted and no warning is issued to the user if the
-file exists.
-
-<P>
-int G_set_ask_return_msg() set Hit RETURN msg
-
-The "Hit RETURN to cancel request" part of the prompt in the prompting
-routines described above, is modified to "Hit RETURN <B>msg.</B>"
-
-<P>
-char * G_get_ask_return_msg() get Hit RETURN msg
-
-The current <I>msg</I> (as set by <I>G_set_ask_return_msg()</I>) is
-returned.
-
-
\subsection Fully_Qualified_File_Names Fully Qualified File Names
All GRASS routines which access database files must be given both the
@@ -412,23 +268,20 @@
the mapset are 2 distinct character strings. However, there is a need
for a single character string which contains both the name and the
mapset (e.g., for interactive interfacing to command-line
-programs). This form of the name is known as the <I>fully qualified
-file name</I> and is built by the following routine:
+programs). This form of the name is known as the <em>fully qualified
+file name</em> and is built by the following routine:
-<P>
-char * G_fully_qualified_name() fully
- qualified file name
+ - G_fully_qualified_name()
-Returns a fully qualified name for the file <B>name</B> in
-<B>mapset.</B> Currently this string is in the form
-<I>name at mapset</I>, but the programmer should pretend not to know this
-and always call this routine to get the fully qualified name.
+Returns a fully qualified name for the file <i>name</i> in
+<i>mapset</i> Currently this string is in the form <i>name at mapset</i>,
+but the programmer should pretend not to know this and always call
+this routine to get the fully qualified name.
-<P>
-The following example shows how an interactive version of <I>d.rast</I>
-interfaces with the command-line version of <I>d.rast</I>:
+The following example shows how an interactive version of <tt>d.rast</tt>
+interfaces with the command-line version of <tt>d.rast</tt>:
-\verbatim
+\code
#include <grass/gis.h>
int main(char *argc, char **argv)
{
@@ -438,458 +291,303 @@
G_gisinit(argv[0]);
mapset = G_ask_cell_old("", name, "");
- if (mapset == NULL) exit(EXIT_SUCCESS);
+ if (mapset == NULL)
+ exit(EXIT_SUCCESS);
fqn = G_fully_qualified_name(name, mapset);
sprintf(command, "d.rast map='%s'", fqn);
- system(command);
+ G_spawn(command, "d.rast", NULL);
}
-\endverbatim
+\endcode
-
\subsection finding Finding Files in the Database
-Noninteractive modules cannot make use of the interactive prompting
-routines described above. For example, a command line driven module
-may require a database file name as one of the command arguments. In
-this case, the programmer must search the database to find the mapset
-where the file resides.
+Command line driven module requires a database file name as one of the
+command arguments. In this case, the programmer must search the
+database to find the mapset where the file resides.
-<P>
The following routines search the database for files:
-<P>
-char * G_find_file() find a
- database file
+ - G_find_file()
-Look for the file <B>name</B> under the specified <B>element</B> in
-the database. The <B>mapset</B> parameter can either be the empty
+Look for the file <i>name</i> under the specified <i>element</i> in
+the database. The <i>mapset</i> parameter can either be the empty
string "", which means search all the mapsets in the user's current
-mapset search path, or it can be a specific mapset, which means
-<I>.</I> look for the file only in this one mapset (for example, in
-the current mapset).
+mapset search path, or it can be a specific mapset, which means. Look
+for the file only in this one mapset (for example, in the current
+mapset).
-<P>
If found, the mapset where the file lives is returned. If not found,
the NULL pointer is returned.
-<P>
-If the user specifies a fully qualified file name, (i.e, a name that also
-contains the mapset; see \ref Fully_Qualified_File_Names) then
-<I>G_find_file()</I> modifies <B>name</B> by eliminating the mapset
-from the <B>name</B>
+If the user specifies a fully qualified file name, (i.e, a name that
+also contains the mapset; see \ref Fully_Qualified_File_Names) then
+G_find_file() modifies <em>name</em> by eliminating the mapset from
+the <em>name</em>.
-<P>
For example, to find a "paint/labels" file anywhere in the database:
-\verbatim
+\code
char name[GNAME_MAX];
char *mapset;
-if ((mapset = G_find_file("paint/labels",name,"")) == NULL)
+if ((mapset = G_find_file("paint/labels", name, "")) == NULL)
/* not found */
-\endverbatim
+\endcode
-<P>
To check that the file exists in the current mapset:
-\verbatim
+\code
char name[GNAME_MAX];
-if (G_find_file("paint/labels",name,G_mapset()) == NULL)
+if (G_find_file("paint/labels", name, G_mapset()) == NULL)
/* not found */
-\endverbatim
+\endcode
-<P>
-
\subsection Legal_File_Names Legal File Names
-<P>
Not all names that a user may enter will be legal files for the GRASS
-databases. The routines which create new files require that the new
-file have a legal name. The routines which prompt the user for file
-names (e.g., <I>G_ask_new()</I>) guarantee that the name entered by
-the user will be legal. If the name is obtained from the command
-line, for example, the programmer must check that the name is
-legal. The following routine checks for legal file names:
+databases. The routines which create new files require that the new
+file have a legal name. If the name is obtained from the command line,
+the programmer must check that the name is legal. The following
+routine checks for legal file names:
-<P>
-int G_legal_filename() check for legal database file
- names
+ - G_legal_filename()
-Returns 1 if <B>name</B> is ok, -1 otherwise.
-
-<P>
-
\subsection Opening_an_Existing_Database_File_for_Reading Opening an Existing Database File for Reading
-<P>
-The following routines open the file <B>name</B> in <B>mapset</B> from
-the specified database <B>element</B> for reading (but not for
-writing). The file <B>name</B> and <B>mapset</B> can be obtained
-interactively <I>using G_ask_old(), and noninteractively using
-G_find_file().</I>
+The following routines open the file <i>name</i> in <i>mapset</i> from
+the specified database <i>element</i> for <b>reading</b> (but not for
+writing). The file <i>name</i> and <i>mapset</i> can be obtained using
+G_find_file().
-<P>
-int G_open_old() open a database file for reading
+The database file <i>name</i> under the <i>element</i> in the
+specified <i>mapset</i> is opened for reading (but not for writing).
-The database file <B>name</B> under the
-<B>element</B> in the specified <B>mapset</B> is opened for reading (but
-not for writing).
+ - G_open_old()
-<P>
-The UNIX open() routine is used to open the file. If the file does not exist,
--1 is returned. Otherwise the file descriptor from the open() is returned.
+The UNIX open() routine is used to open the file. If the file does not
+exist, -1 is returned. Otherwise the file descriptor from the open()
+is returned.
-<P>
-FILE * G_fopen_old() open a database file for reading
+ - G_fopen_old()
-The database file <B>name</B> under the
-<B>element</B> in the specified <B>mapset</B> is opened for reading (but
-not for writing).
-
-<P>
The UNIX fopen() routine, with "r" read mode, is used to open the
-file. If the file does not exist, the NULL pointer is
+file. If the file does not exist, the NULL pointer is
returned. Otherwise the file descriptor from the fopen() is returned.
-<P>
-
\subsection Opening_an_Existing_Database_File_for_Update Opening an Existing Database File for Update
-<P>
-The following routines open the file <B>name</B> in the current mapset
-from the specified database <B>element</B> for writing. The file must
-exist. Its <B>name</B> can be obtained interactively <I>using
-G_ask_in_mapset(), and noninteractively using G_find_file().</I>
+The following routines open the file <i>name</i> in the current mapset
+from the specified database <i>element</i> for <b>writing</b>. The
+file must exist. Its <i>name</i> can be obtained using G_find_file().
-<P>
-int G_open_update() open a database file for update
+The database file <i>name</i> under the <i>element</i> in the current
+mapset is opened for reading and writing.
-The database file <B>name</B> under the <B>element</B> in the
- current mapset is opened for reading and writing.
+ - G_open_update()
-<P>
-The UNIX open() routine is used to open the file. If the file does not exist,
- -1 is returned. Otherwise the file is positioned at the end of the file and
- the file descriptor from the open() is returned.
+The UNIX open() routine is used to open the file. If the file does not
+exist, -1 is returned. Otherwise the file is positioned at the end of
+the file and the file descriptor from the open() is returned.
-<P>
-int G_fopen_append() open a database file for update
+- G_fopen_append()
-The database file <B>name</B> under the <B>element</B> in the current
-mapset is opened for appending (but not for reading).
-
-<P>
The UNIX fopen() routine, with "a" append mode, is used to open the
-file. If the file does not exist, the NULL pointer is
+file. If the file does not exist, the NULL pointer is
returned. Otherwise the file is positioned at the end of the file and
the file descriptor from the fopen() is returned.
\subsection Creating_and_Opening_a_New_Database_File Creating and Opening a New Database File
-<P>
-The following routines create the new file <B>name</B> in the current
+The following routines create the new file <i>name</i> in the current
mapset (GRASS does not allow files to be created outside the current
mapset; see \ref Database_Access_Rules) under the specified database
-<B>element</B> and open it for writing. The database <B>element</B> is
+<i>element</i> and open it for writing. The database <i>element</i> is
created, if it does not already exist.
-<P>
-The file <B>name</B> should be obtained interactively using
-<I>G_ask_new()</I>. If obtained noninteractively (e.g., from the
-command line), <I>G_legal_filename()</I> should be called first to
-make sure that <B>name</B> is a valid GRASS file name. <B>Warning.</B>
-It is not an error for <B>name</B> to already exist. However, the file
-will be removed and recreated empty. The interactive routine
-<I>G_ask_new()</I> guarantees that <B>name</B> will not exist, but if
-<B>name</B> is obtained from the command line, <B>name</B> may
-exist. In this case <I>G_find_file()</I> could be used to see if
-<B>name</B> exists.
+The file <i>name</i> is obtained noninteractively (e.g., from the
+command line), G_legal_filename() should be called first to make sure
+that <i>name</i> is a valid GRASS file name. <b>Warning:</b> It is not
+an error for <i>name</i> to already exist. However, the file will be
+removed and recreated empty. G_find_file() could be used to see if
+<i>name</i> exists.
-<P>
-int G_open_new() open a new database file
-
-The database file <B>name</B> under the <B>element</B> in the current
+The database file <i>name</i> under the <i>element</i> in the current
mapset is created and opened for writing (but not reading).
-<P>
+ - G_open_new()
+
The UNIX open() routine is used to open the file. If the file does not
exist, -1 is returned. Otherwise the file is positioned at the end of
the file and the file descriptor from the open() is returned.
-<P>
-FILE * G_fopen_new() open a new database file
+ - G_fopen_new()
-The database file <B>name</B> under the <B>element</B> in the current
-mapset is created and opened for writing (but not reading).
-
-<P>
The UNIX fopen() routine, with "w" write mode, is used to open the
file. If the file does not exist, the NULL pointer is
returned. Otherwise the file is positioned at the end of the file and
the file descriptor from the fopen() is returned.
-<P>
\subsection Database_File_Management Database File Management
-<P>
The following routines allow the renaming and removal of database
files in the current mapset (These functions only apply to the current
mapset since GRASS does permit users to modify things in mapsets other
than the current mapset; see \ref Database_Access_Rules).
-int G_rename() rename a database
-file
+ - G_rename() rename a database file
-The file or directory <B>old</B> under the database <B>element</B>
-directory in the current mapset is renamed to <B>new.</B>
+ - G_remove() remove a database file
-<P>
-Returns 1 if successful, 0 if <B>old</B> does not exist, and -1 if
-there was an error.
-
-<P>
-<B>Bug.</B> This routine does not check to see if the <B>new</B> name is a
- valid database file name.
-
-<P>
-int G_remove() remove a database file
-
-The file or directory <B>name</B> under the database <B>element</B> directory
- in the current mapset is removed.
-
-<P>
-Returns 1 if successful, 0 if <B>name</B> does not exist, and -1 if
-there was an error.
-
-<P>
-<B>Note.</B> If <B>name</B> is a directory, everything within the
- directory is removed as well.
-
-<P>
-<B>Note.</B> These functions only apply to the specific <B>element</B>
-and not to other "related" elements. For example, if <B>element</B> is
+<b>Note:</b> These functions only apply to the specific <i>element</i>
+and not to other "related" elements. For example, if <i>element</i> is
"cell", then the specified raster file will be removed (or renamed),
but the other support files, such as "cellhd" or "cats", will not. To
remove these other files as well, specific calls must be made for each
-related <B>element.</B>
+related <i>element</i>.
\subsection Memory_Allocation Memory Allocation
-<P>
The following routines provide memory allocation capability. They are
simply calls to the UNIX suite of memory allocation routines malloc(),
realloc() and calloc(), except that if there is not enough memory,
they print a diagnostic message to that effect and then call exit().
-<P>
-<B>Note.</B> Use the G_free() routine to release memory allocated by these
-routines.
+ - G_malloc ()
-<P>
-int G_free() free the memory allocated
-
-Free the memory allocated by the GRASS malloc routines.
-
-<P>
-void * G_malloc () memory allocation
-
-Allocates a block of memory at least <B>size</B> bytes which is
+Allocates a block of memory at least <i>size</i> bytes which is
aligned properly for all data types. A pointer to the aligned block is
returned.
-<P>
-void * G_realloc() memory allocation
+ - G_realloc()
-Changes the <B>size</B> of a previously allocated block of memory at
-<B>ptr</B> and returns a pointer to the new block of memory. The
-<B>size</B> may be larger or smaller than the original size. If the
+Changes the <i>size</i> of a previously allocated block of memory at
+<i>ptr</i> and returns a pointer to the new block of memory. The
+<i>size</i> may be larger or smaller than the original size. If the
original block cannot be extended "in place", then a new block is
allocated and the original block copied to the new block.
-<P>
-<B>Note.</B> If <B>ptr</B> is NULL, then this routine simply allocates
-a block of <B>size</B> bytes. This routine works around broken
-realloc() routines, which do not handle a NULL <B>ptr.</B>
+<b>Note:</b> If <i>ptr</i> is NULL, then this routine simply allocates
+a block of <i>size</i> bytes. This routine works around broken
+realloc() routines, which do not handle a NULL <i>ptr</i>.
-<P>
-void * G_calloc() memory allocation
+ - G_calloc()
-Allocates a properly aligned block of memory <B>n</B>*<B>size</B>
+Allocates a properly aligned block of memory <i>n</i>*<i>size</i>
bytes in length, initializes the allocated memory to zero, and returns
a pointer to the allocated block of memory.
-<P>
-<B>Note.</B> Allocating memory for reading and writing raster files is
-discussed in Allocating_Raster_I_O_Buffers.
+ - G_free()
-<P>
-double * G_alloc_vector() memory allocation
+Use the G_free() routine to release memory allocated by
+these routines.
-Allocate a vector (array) of <B>n</B> doubles initialized to zero.
-
-<P>
-float * G_alloc_fvector() memory allocation
-
-Allocate a vector (array) of <B>n</B> floats initialized to zero.
-
-<P>
-double ** G_alloc_matrix() memory allocation
-
-Allocate a matrix of <B>rows</B> by <B>cols</B> doubles initialized to
-zero.
-
-<P>
-float ** G_alloc_fmatrix() memory allocation
-
-Allocate a matrix of <B>rows</B> by <B>cols</B> floats initialized to
-zero.
-
-<P>
-int G_free_vector() memory deallocation
-
-Deallocate a vector (array) of doubles or floats.
-
-<P>
-int G_free_matrix() memory deallocation
-
-Deallocate a matrix of doubles.
-
-<P>
-int G_free_fmatrix() memory deallocation
-
-Deallocate a matrix of floats.
-
-
\subsection The_Region The Region
-The region concept is explained in Region. It can be thought of as a
+The region concept is explained in \ref Region. It can be thought of as a
two-dimensional matrix with known boundaries and rectangular cells.
-<P>
+
There are logically two different regions. The first is the database
region that the user has set in the current mapset. The other is the
region that is active in the module. This active module region is what
-controls reading and writing of raster file data. The
-vector map export does not take care for the active region settings.
+controls reading and writing of raster file data. The vector map
+export does not take care for the active region settings.
-<P>
The routines described below use a GRASS data structure
-<I>Cell_head</I> to hold region information. This structure is defined
-in the "gis.h" header file. It is discussed in detail under
-GIS_Library_Data_Structures .
+<tt>Cell_head</tt> to hold region information. This structure is
+defined in the "gis.h" header file. It is discussed in detail under
+\ref GIS_Library_Data_Structures.
-
\subsection The_Database_Region The Database Region
-
Reading and writing the user's database region are done by the
following routines:
-[Note: Previous versions of GRASS called this the "window". Due to
+Note: Previous versions of GRASS called this the "window". Due to
overuse of this term (database window, graphics window, etc.), the
term was changed to "region". However, to maintain compatibility with
existing programs, library routine names were not changed - hence the
term "window" is used in the routine name (where "region" should
-probably be used instead.)]
+probably be used instead).
-<P>
-int G_get_window() read the database region
+ - G_get_window()
Reads the database region as stored in the WIND file in the user's
-current mapset <B>into region.</B>
+current mapset into region.
-<P>
An error message is printed and exit() is called if there is a problem
reading the region.
-<P>
-<B>Note.</B> GRASS applications that read or write raster files should
+<b>Note:</b> GRASS applications that read or write raster files should
not use this routine since its use implies that the active module
region will not be used. Programs that read or write raster file data
-(or vector data) can query the active module region <I>using
-G_window_rows() and G_window_cols().</I>
+(or vector data) can query the active module region using
+G_window_rows() and G_window_cols().
-<P>
-int G_put_window() write the database region
+ - G_put_window()
+
Writes the database region file (WIND) in the user's current mapset
-from <B>region.</B> Returns 1 if the region is written ok. Returns -1
-if not (no diagnostic message is printed).
+from region.
-<P>
-<B>Warning.</B> Since this routine actually changes the database
+<b>Warning:</b> Since this routine actually changes the database
region, it should only be called by modules which the user knows will
-change the region. It is probably fair to say that under GRASS 3.0
-only the <I>g.region</I>, and <I>d.zoom</I> modules should call this
-routine.
+change the region. It is probably fair to say that only the
+<tt>g.region</tt> should call this routine.
-<P>
There is another database region. This region is the default region
for the location. The default region provides the user with a
"starting" region, i.e., a region to begin with and return to as a
-reference point. The GRASS modules <I>g.region</I> allow the user to
-set their database region from the default region. (See
-Permanent_Mapset for a discussion of the default region.) The
+reference point. The GRASS modules <tt>g.region</tt> allow the user to
+set their database region from the default region (see \ref
+Permanent_Mapset for a discussion of the default region). The
following routine reads this region:
-<P>
-int G_get_default_window() read the default
-region
+ - G_get_default_window()
-Reads the default region for the location into <B>region.</B>
-
-<P>
-An error message is printed and exit() is called if there is a problem
-reading the default region.
-
\subsection The_Active_Module_Region The Active Module Region
-<P>
-The active module region is the one that is used when reading and
-writing raster file data. This region determines the resampling when
-reading raster data. It also determines the extent and resolution of
-new raster files.
+The <em>active module region</em> is the one that is used when reading
+and writing raster file data. This region determines the resampling
+when reading raster data. It also determines the extent and resolution
+of new raster files.
-<P>
Initially the active module region and the user's database region are
the same, but the programmer can make them different. The following
routines manage the active module region.
-<P>
-int G_window_rows() number of rows in active region
+ - G_window_rows() number of rows in active region
-<P>
-int G_window_cols() number of columns in active region
+ - G_window_cols() number of columns in active region
These routines return the number of rows and columns (respectively) in
the active module region. Before raster files can be read or written,
it is necessary to known how many rows and columns are in the active
region. For example:
-\verbatim
+\code
int nrows, cols;
int row, col;
nrows = G_window_rows();
ncols = G_window_cols();
-for (row = 0; row < nrows; row++){
- read row ...
- for (col = 0; col < ncols; col++){
- process col ...
+for (row = 0; row < nrows; row++) {
+ /* read row ... */
+ for (col = 0; col < ncols; col++) {
+ /* process col ... */
}
}
-\endverbatim
+\endcode
-<P>
-int G_set_window() set the active region
+ - G_set_window() set the active region
-This routine sets the active region from <B>region.</B> Setting the
+This routine sets the active region from given region. Setting the
active region does not change the WIND file in the database. It simply
changes the region for the duration of the module.
@@ -898,328 +596,243 @@
region for a module to be executed using the system() or popen()
routines.
-A warning message is printed and -1 returned if <B>region</B> is not
-valid. Otherwise 1 is returned.
-
-<P>
-<B>Note.</B> This routine overrides the region as set by the user. Its
+<b>Note:</b> This routine overrides the region as set by the user. Its
use should be very limited since it changes what the user normally
expects to happen. If this routine is not called, then the active
region will be the same as what is in the user's WIND file.
-<P>
-<B>Warning.</B> Calling this routine with already opened raster files
+<b>Warning:</b> Calling this routine with already opened raster files
has some side effects. If there are raster files which are open for
reading, they will be read into the newly set region, not the region
that was active when they were opened. However, CELL buffers allocated
for reading the raster files are not automatically reallocated. The
-module must reallocate them explicitly. Also, this routine does not
+module must reallocate them explicitly. Also, this routine does not
change the region for raster files which are open for writing. The
region that was active when the open occurred still applies to these
files.
-<P>
-int G_get_set_window() get the active region
+ - G_get_set_window() get the active region
-Gets the values of the currently active region into <B>region.</B> If
-<I>G_set_window()</I> has been called, then the values set by that call
-are retrieved. Otherwise the user's database region is retrieved.
+Gets the values of the currently active region into region. If
+G_set_window() has been called, then the values set by that call are
+retrieved. Otherwise the user's database region is retrieved.
-<P>
-<B>Note.</B> For modules that read or write raster data, and really
+<b>Note:</b> For modules that read or write raster data, and really
need the full region information, this routine is preferred over
-<I>G_get_window().</I> However, since <I>G_window_rows() and G_window_cols()
-return the number of rows and</I> columns in the active region, the
+G_get_window(). However, since G_window_rows() and G_window_cols()
+return the number of rows and columns in the active region, the
programmer should consider whether or not the full region information
is really needed before using this routine.
-<P>
-char * G_align_window() align two regions
+ - G_align_window() align two regions
-Modifies the input <B>region</B> to align to the <B>ref</B>
-region. The resolutions in <B>region</B> are set to match those in
-<B>ref</B> and the <B>region</B> edges (north, south, east, west) are
-modified to align with the grid of the <B>ref</B> region.
+Modifies the input region to align to the reference region. The
+resolutions in region are set to match those in refefence region and
+the region edges (north, south, east, west) are modified to align with
+the grid of the reference region.
-<P>
-The <B>region</B> may be enlarged if necessary to achieve the
-alignment. The north is rounded northward, the south southward, the
+The <i>region</i> may be enlarged if necessary to achieve the
+alignment. The north is rounded northward, the south southward, the
east eastward and the west westward.
-<P>
-This routine returns NULL if ok, otherwise it returns an error message.
+ - G_col_to_easting()
-<P>
-double G_col_to_easting() column to easting
+Converts a column relative to a region to an easting.
-Converts a <B>col</B>umn relative to a <B>region</B> to an easting;
-
-<P>
-<B>Note.</B> col is a double: col+0.5 will return the easting for the
+<b>Note:</b> col is a double: col+0.5 will return the easting for the
center of the column; col+0.0 will return the easting for the western
edge of the column; and col+1.0 will return the easting for the
eastern edge of the column.
-<P>
-double G_row_to_northing() row to northing
+ - G_row_to_northing()
-Converts a <B>row</B> relative to a <B>region</B> to a northing;
+Converts a row relative to a region to a northing.
-<P>
-<B>Note.</B> row is a double: row+0.5 will return the northing for the
+<b>Note:</b> row is a double: row+0.5 will return the northing for the
center of the row; row+0.0 will return the northing for the northern
edge of the row; and row+1.0 will return the northing for the southern
edge of the row.
-double G_easting_to_col() easting to column
+ - G_easting_to_col()
-<P>
-Converts an <B>east</B>ing relative to a <B>region</B> to a column.
+Converts an easting relative to a region to a column.
-<P>
-<B>Note.</B> The result is a double. Casting it to an integer will
+<b>Note:</b> The result is a double. Casting it to an integer will
give the column number.
-<P>
-double G_northing_to_row() northing to row
+ - G_northing_to_row()
-Converts a <B>north</B>ing relative to a <B>region</B> to a row.
+Converts a northing relative to a region to a row.
-<P>
-<B>Note.</B> the result is a double. Casting it to an integer will
+<b>Note:</b> the result is a double. Casting it to an integer will
give the row number.
\subsection Projection_Information Projection Information
-
-<P>
The following routines return information about the cartographic
projection and zone. See \ref Region for more information about these
values.
-<P>
-int G_projection() query cartographic projection
+ - G_projection()
This routine returns a code indicating the projection for the active
region. The current values are:
-<P>
-0 unreferenced x,y (imagery data)
-<br>
-1 UTM
-<br>
-2 State Plane
-<br>
-3 Latitude-Longitude
-<br>
-99 Other (more than 121 projections are supported)
+ - PROJECTION_XY - unreferenced x,y (imagery data)
+ - PROJECTION_UTM - UTM
+ - PROJECTION_SP - State Plane
+ - PROJECTION_LL - Latitude-Longitude
+ - PROJECTION_OTHER - Other (more than 121 projections are supported)
-<P>
-char * G_database_projection_name() query cartographic projection
+ - G_database_projection_name()
Returns a pointer to a string which is a printable name for projection
-code <B>proj</B> (as returned by <I>G_projection()</I>). Returns NULL if
-<B>proj</B> is not a valid projection.
+code (as returned by G_projection()).
-<P>
-char * G_database_unit_name() database units
+ - G_database_unit_name()
-Returns a string describing the database grid units. It returns a
-plural form (eg. feet) if <B>plural</B> is true. Otherwise it returns
-a singular form (eg. foot).
+Returns a string describing the database grid units.
-<P>
-double G_database_units_to_meters_factor() conversion to
- meters
+ - G_database_units_to_meters_factor()
Returns a factor which converts the grid unit to meters (by
multiplication). If the database is not metric (eg. imagery) then 0.0
is returned.
-<P>
-int G_zone() query cartographic zone
+ - G_zone()
This routine returns the zone for the active region. The meaning for
the zone depends on the projection. For example zone 18 for projection
type 1 would be UTM zone 18.
-\subsection Latitude_Longitude_Databases Latitude-Longitude Databases
+\subsection Latitude_Longitude_Databases Latitude-Longitude GIS Databases
-<P>
GRASS supports databases in a longitude-latitude grid using a
projection where the x coordinate is the longitude and the y
coordinate is the latitude. This projection is called the Equidistant
Cylindrical Projection (also known as Plate Carree). ECP has the
-property that <I>where am I</I> and <I>row-column</I> calculations are
-identical to those in planimetric grids (like UTM, Universal
+property that <em>where am I</em> and <em>row-column</em> calculations
+are identical to those in planimetric grids (like UTM, Universal
Transverse Mercator Projection). This implies that normal GRASS
registration and overlay functions will work without any special
considerations or modifications to existing code. However, the
projection is not planimetric. This means that distance and area
calculations are no longed Euclidean.
-<P>
Also, since the world is round, maps may not have edges in the
east-west direction, especially for global databases. Maps may have
the same longitude at both the east and west edges of the
display. This feature, called global wraparound, must be accounted for
-by GRASS modules (particularly vector based functions, like plotting.)
-What follows is a description of the GISLIB library routines that are
+by GRASS modules (particularly vector based functions, like plotting).
+What follows is a description of the GIS Library routines that are
available to support latitude-longitude databases.
\subsection Coordinates Coordinates
-<P>
Latitudes and longitudes are specified in degrees. Northern latitudes
range from 0 to 90 degrees, and southern latitudes from 0 to
-90. Longitudes have no limits since longitudes ±360 degrees are
equivalent.
-<P>
-Coordinates are represented in ASCII using the format <B>dd:mm:ssN</B>
-or <B>dd:mm:ssS</B> for latitudes, <B>ddd:mm:ssE</B> or
-<B>ddd.mm.ssW</B> for longitudes, and <B>dd.mm.ss</B> for grid
-resolution. For example, 80:30:24N represents a northern latitude of
-80 degrees, 30 minutes, and 24 seconds. 120:15W represents a
-longitude 120 degrees and 15 minutes west of the prime meridian. 30:15
-represents a resolution of 30 degrees and 15 minutes. These next
-routines convert between ASCII representations and the machine
-representation for a coordinate. They work both with
-latitude-longitude projections and planimetric projections.
+Coordinates are represented in ASCII using the format
+<tt>dd:mm:ssN</tt> or <tt>dd:mm:ssS</tt> for latitudes,
+<tt>ddd:mm:ssE</tt> or <tt>ddd.mm.ssW</tt> for longitudes, and
+<tt>dd.mm.ss</tt> for grid resolution. For example, 80:30:24N
+represents a northern latitude of 80 degrees, 30 minutes, and 24
+seconds. 120:15W represents a longitude 120 degrees and 15 minutes
+west of the prime meridian. 30:15 represents a resolution of 30
+degrees and 15 minutes. These next routines convert between ASCII
+representations and the machine representation for a coordinate. They
+work both with latitude-longitude projections and planimetric
+projections.
-<P>
-<B>Note.</B> In each subroutine, the programmer must specify the
+<b>Note:</b> In each subroutine, the programmer must specify the
projection number. If the projection number is PROJECTION_LL (defined
in "gis.h"), then latitude-longitude ASCII format is invoked.
Otherwise, a standard floating-point to ASCII conversion is made.
-<P>
-int G_format_easting() easting to ASCII
+ - G_format_easting() easting to ASCII
-Converts the double representation of the <B>east</B> coordinate to
-its ASCII representation (into <B>buf</B>).
+ - G_format_northing() northing to ASCII
-<P>
-int G_format_northing() northing to ASCII
+Converts the double representation of the given coordinate to its
+ASCII representation.
-Converts the double representation of the <B>north</B> coordinate to
-its ASCII representation (into <B>buf</B>).
+ - G_format_resolution()
-<P>
-int G_format_resolution() resolution to ASCII
+Converts the double representation of the resolution to its
+ASCII representation.
-Converts the double representation of the <B>resolution</B> to its
-ASCII representation (into <B>buf</B>).
+ - G_scan_easting() ASCII easting to double
-<P>
-int G_scan_easting() ASCII easting to double
+ - G_scan_northing() ASCII northing to double
-Converts the ASCII "easting" coordinate string in <B>buf</B> to its
-double representation (into <B>easting</B>).
+Converts the ASCII coordinate string in to its double representation.
-<P>
-int G_scan_northing() ASCII northing to double
+ - G_scan_resolution() ASCII resolution to double
-Converts the ASCII "northing" coordinate string in <B>buf</B> to its
-double representation (into <B>northing</B>).
+Converts the ASCII "resolution" string to its double representation
+(into resolution).
-<P>
-int G_scan_resolution() ASCII resolution to double
-
-Converts the ASCII "resolution" string in <B>buf</B> to its double
-representation (into resolution).
-
-<P>
The following are examples of how these routines are used.
-\verbatim
+\code
double north;
char buf[50];
-G_scan_northing(buf, north, G_projection()); /* ASCII to double */
+G_scan_northing(buf, north, G_projection()); /* ASCII to double */
G_format_northing(north, buf, G_projection()); /* double to ASCII */
-G_format_northing(north, buf, -1); /* double to ASCII */
+G_format_northing(north, buf, -1); /* double to ASCII */
/* This last example forces floating-point ASCII format */
-\endverbatim
+\endcode
\subsection Raster_Area_Calculations Raster Area Calculations
-
-The following routines perform area calculations for raster maps.,
+The following routines perform area calculations for raster maps.
They are based on the fact that while the latitude-longitude grid is
not planimetric, the size of the grid cell at a given latitude is
constant. The first routines work in any projection.
-<P>
-int G_begin_cell_area_calculations() begin cell area calculations
+ - G_begin_cell_area_calculations()
This routine must be called once before any call to
-<I>G_area_of_cell_at_row().</I> It can be used in either planimetric
-projections or the latitude-longitude projection. It returns 2 if the
-projection is latitude-longitude, 1 if the projection is planimetric,
-and 0 of the projection doesn't hav e a metric (e.g. imagery.) If the
-return value is 1 or 0, all the grid cells in the map have the same
-area. Otherwise the area of a grid cell varies with the row.
+G_area_of_cell_at_row(). It can be used in either planimetric
+projections or the latitude-longitude projection.
-<P>
-double G_area_of_cell_at_row() cell area in specified row
+ - G_area_of_cell_at_row()
This routine returns the area in square meters of a cell in the
-specified <B>row.</B> This value is constant for planimetric grids and
-varies with the row if the projection is latitude-longitude.
+specified row. This value is constant for planimetric grids and varies
+with the row if the projection is latitude-longitude.
-<P>
-int G_begin_zone_area_on_ellipsoid() begin area calculations for ellipsoid
+ - G_begin_zone_area_on_ellipsoid()
-Initializes raster area calculations for an ellipsoid, where <B>a</B>
-is the semi-major axis of the ellipse (in meters), <B>e2</B> is the
-ellipsoid eccentricity squared, and <B>s</B> is a scale factor to
-allow for calculations of part of the zone (<B>s</B>=1.0 is full zone,
-<B>s</B>=0.5 is half the zone, and <B>s</B>=360/ew_res is for a single
-grid cell).
+Initializes raster area calculations for an ellipsoid.
-<P>
-<B>Note.</B> e2 must be positive. A negative value makes no sense, and
-zero implies a sphere.
+ - G_area_for_zone_on_ellipsoid()
-<P>
-double G_area_for_zone_on_ellipsoid() area between latitudes
+Returns the area between latitudes scaled by the factor passed to
+G_begin_zone_area_on_ellipsoid().
-Returns the area between latitudes <B>north</B> and <B>south</B>
-scaled by the factor <B>s</B> passed to
-<I>G_begin_zone_area_on_ellipsoid().</I>
+ - G_begin_zone_area_on_sphere()
-<P>
-int G_begin_zone_area_on_sphere() initialize
-calculations for sphere
+Initializes raster area calculations for a sphere.
-Initializes raster area calculations for a sphere. The radius of the
-sphere is <B>r</B> and <B>s</B> is a scale factor to allow for
-calculations of a part of the zone (see
-<I>G_begin_zone_area_on_ellipsoid()</I>).
+ - G_area_for_zone_on_sphere()
-<P>
-double G_area_for_zone_on_sphere() area between latitudes
+Returns the area between latitudes.
-Returns the area between latitudes <B>north</B> and <B>south</B>
-scaled by the factor <B>s</B> passed to
-<I>G_begin_zone_area_on_sphere()</I>
-
-
\subsection Polygonal_Area_Calculations Polygonal Area Calculations
-
-<P>
These next routines provide area calculations for polygons. Some of
the routines are specifically for latitude-longitude, while others
will function for all projections.
-<P>
However, there is an issue for latitude-longitude that does not occur
with planimetric grids. Vector/polygon data is described as a series
of x,y coordinates. The lines connecting the points are not stored but
@@ -1228,196 +841,134 @@
is the shape of the line that connects two points on the surface of a
globe?
-<P>
-One choice (among many) is the shortest path from <B>x1,y1</B> to
-<B>x2,y2</B>, known as the geodesic. Another is a straight line on the
-grid. The area routines described below assume the latter. Routines
-to work with the former have not yet been developed.
+One choice (among many) is the shortest path from <tt>x1,y1</tt> to
+<tt>x2,y2</tt>, known as the geodesic. Another is a straight line on
+the grid. The area routines described below assume the
+latter. Routines to work with the former have not yet been developed.
-<P>
-int G_begin_polygon_area_calculations() begin polygon area
-calculations
+ - G_begin_polygon_area_calculations()
This initializes the polygon area calculation routines. It is used
both for planimetric and latitude-longitude projections.
-<P>
-It returns 2 if the projection is latitude-longitude, 1 if the
-projection is planimetric, and 0 if the projection doesn't have a
-metric (e.g. imagery.)
+ - G_area_of_polygon()
-<P>
-double G_area_of_polygon() area in square meters of polygon
-Returns the area in square meters of the polygon described by the
-<B>n</B> pairs of <B>x,y</B> coordinate vertices. It is used both for
+Returns the area in square meters of the polygon. It is used both for
planimetric and latitude-longitude projections.
-<P>
<B>Note.</B> If the database is planimetric with the non-meter grid,
this routine performs the required unit conversion to produce square
-meters. double <B>G_planimetric_polygon_area()</B> (x, y, n) <I>area in
-coordinate units</I> double *x, *y ; int n ;
+meters.
-<P>
-Returns the area in coordinate units of the polygon described by the
-<B>n</B> pairs of <B>x,y</B> coordinate vertices for planimetric
-grids. If the units for <B>x,y</B> are meters, then the area is in
-square meters. If the units are feet, then the area is in square
-feet, and so on.
+ - G_planimetric_polygon_area()
-<P>
-int G_begin_ellipsoid_polygon_area () begin area calculations
+Return the area in map units of the polygon,
-This initializes the polygon area calculations for the ellipsoid with
-semi-major axis <B>a</B> (in meters) and ellipsoid eccentricity
-squared <B>e2.</B>
+ - G_begin_ellipsoid_polygon_area()
-<P>
-double G_ellipsoid_polygon_area() area of lat-long polygon
+This initializes the polygon area calculations for the ellipsoid.
-Returns the area in square meters of the polygon described by the
-<B>n</B> pairs of <B>lat,long</B> vertices for latitude-longitude
+ - G_ellipsoid_polygon_area()
+
+Returns the area in square meters of the polygon for latitude-longitude
grids.
-<P>
-<B>Note.</B> This routine assumes grid lines on the connecting the
+<b>Note:</b> This routine assumes grid lines on the connecting the
vertices (as opposed to geodesics).
\subsection Distance Calculations Distance Calculations
-
Two routines perform distance calculations for any projection.
-<P>
-int G_begin_distance_calculations() begin distance calculations
+ - G_begin_distance_calculations()
Initializes the distance calculations. It is used both for the
planimetric and latitude-longitude projections.
-<P>
-It returns 2 if the projection is latitude-longitude, 1 if the
-projection is planimetric, and 0 if the projection doesn't hav e a
-metric (e.g. imagery).
+ - G_distance()
-<P>
-double G_distance() distance in meters
+This routine computes the distance between two points in meters.
-This routine computes the distance, in meters, from <B>x1,y1</B> to
-<B>x2,y2.</B> If the projection is latitude-longitude, this distance
-is measured along the geodesic. Two routines perform geodesic distance
-calculations.
+ - G_begin_geodesic_distance()
-<P>
-int G_begin_geodesic_distance() begin geodesic distance
+Initializes the distance calculations for the ellipsoid. It is used
+only for the latitude-longitude projection.
-Initializes the distance calculations for the ellipsoid with
-semi-major axis <B>a</B> (in meters) and ellipsoid eccentricity
-squared <B>e2.</B> It is used only for the latitude-longitude
-projection.
+ - G_geodesic_distance() geodesic distance
-<P>
-double G_geodesic_distance() geodesic distance
+Calculates the geodesic distance between two points in meters.
-Calculates the geodesic distance from <B>lon1,lat1</B> to
-<B>lon2,lat2</B> in meters.
-
-<P>
The calculation of the geodesic distance is fairly costly. These next
three routines provide a mechanism for calculating distance with two
fixed latitudes and varying longitude separation.
-<P>
-int G_set_geodesic_distance_lat1() set geodesic distance lat1
+ - G_set_geodesic_distance_lat1() set the first latitude.
-Set the first latitude.
+ - G_set_geodesic_distance_lat2() set the second latitude.
-<P>
-int G_set_geodesic_distance_lat2() set geodesic distance lat2
+ - G_geodesic_distance_lon_to_lon()
-Set the second latitude.
+Calculates the geodesic distance between two points set by
+G_set_geodesic_distance_latl() and G_set_geodesic_distance_lat2().
-<P>
-double G_geodesic_distance_lon_to_lon() geodesic distance
-
-Calculates the geodesic distance from <B>lon1,lat1</B> to
-<B>lon2,lat2</B> in meters, where <B>lat1</B> was the latitude passed
-to <I>G_set_geodesic_distance_latl()</I> and <B>lat2</B> was the
-<I>latitude passed to G_set_geodesic_distance_lat2().</I>
-
-
\subsection Global_Wraparound Global Wraparound
-<P>
These next routines provide a mechanism for determining the relative
position of a pair of longitudes. Since longitudes of ±360 are
equivalent, but GRASS requires the east to be bigger than the west,
some adjustment of coordinates is necessary.
-<P>
-double G_adjust_easting() returns east larger than west
+ - G_adjust_easting()
+
+Returns east larger than west. If the region projection is
+PROJECTION_LL, then this routine returns an equivalent <i>east</i>
+that is larger, but no more than 360 degrees larger, than the
+coordinate for the western edge of the region. Otherwise no adjustment
+is made and the original <i>east</i> is returned.
-If the region projection is PROJECTION_LL, then this routine returns
-an equivalent <B>east</B> that is larger, but no more than 360 degrees
-larger, than the coordinate for the western edge of the
-region. Otherwise no adjustment is made and the original <B>east</B>
-is returned.
+ - G_adjust_east_longitude()
-<P>
-double G_adjust_east_longitude() adjust east
-longitude
+This routine returns an equivalent <i>east</i> that is larger, but no
+more than 360 larger than the <i>west</i> coordinate.
-This routine returns an equivalent <B>east</B> that is larger, but no
-more than 360 larger than the <B>west</B> coordinate.
-
-<P>
This routine should be used only with latitude-longitude coordinates.
-<P>
-int G_shortest_way() shortest way between eastings
+ - G_shortest_way()
-If the database projection is PROJECTION_LL, then <B>east1,east2</B>
-are changed so that they are no more than 180 degrees apart. Their
-true locations are not changed. If the database projection is not
-PROJECTION_LL, then <B>east1,east2</B> are not changed.
+Returns shortest way between eastings.
-
\subsection Miscellaneous Miscellaneous
-char * G_ellipsoid_name() return ellipsoid name
+ - G_ellipsoid_name()
This routine returns a pointer to a string containing the name for the
-<B>n</B><I>th</I> ellipsoid in the GRASS ellipsoid table; NULL when
-<B>n</B> is too large. It can be used as follows:
+ellipsoid in the GRASS ellipsoid table. It can be used as follows:
-\verbatim
+\code
int n;
char *name;
-for (n=0; name=G_ellipsoid_name(n); n++)
+for(n = 0; name = G_ellipsoid_name(n); n++)
fprintf(stdout, "%s\n", name);
-\endverbatim
+\endcode
-<P>
-int G_get_ellipsoid_by_name() get ellipsoid by name
+ - G_get_ellipsoid_by_name()
-This routine returns the semi-major axis <B>a</B> (in meters) and
-eccentricity squared <B>e2</B> for the named ellipsoid. Returns 1 if
-<B>name</B> is a known ellipsoid, 0 otherwise.
+This routine returns the semi-major axis (in meters) and
+eccentricity squared for the named ellipsoid.
-<P>
-int G_get_ellipsoid_parameters() get ellipsoid parameters
+ - G_get_ellipsoid_parameters()
-This routine returns the semi-major axis <B>a</B> (in meters) and the
-eccentricity squared <B>e2</B> for the ellipsoid associated with the
+This routine returns the semi-major axis (in meters) and the
+eccentricity squared for the ellipsoid associated with the
database. If there is no ellipsoid explicitly associated with the
database, it returns the values for the WGS 84 ellipsoid.
-<P>
-double G_meridional_radius_of_curvature() meridional radius of curvature
+- G_meridional_radius_of_curvature()
Returns the meridional radius of curvature at a given longitude:
@@ -1425,18 +976,15 @@
\rho = \frac{a (1-e^2)}{(1-e^2\sin^2 lon)^{3/2}}
\f$
+ - G_transverse_radius_of_curvature()
-<P>
-double G_transverse_radius_of_curvature() transverse radius of curvature
-
Returns the transverse radius of curvature at a given longitude:
\f$
\nu = \frac{a}{(1-e^2\sin^2 lon)^{1/2}}
\f$
-<P>
-double G_radius_of_conformal_tangent_sphere() radius of conformal tangent sphere
+ - G_radius_of_conformal_tangent_sphere()
Returns the radius of the conformal sphere tangent to ellipsoid at a
given longitude:
@@ -1445,32 +993,21 @@
r = \frac{a (1-e^2)^{1/2}}{(1-e^2\sin^2 lon)}
\f$
-<P>
-int G_pole_in_polygon() pole in polygon
+ - G_pole_in_polygon()
For latitude-longitude coordinates, this routine determines if the
-polygon defined by the <B>n</B> coordinate vertices <B>x,y</B>
-contains one of the poles.
+polygon contains one of the poles.
-<P>
-Returns -1 if it contains the south pole; 1 if it contains the north
-pole; 0 if it contains neither pole.
-
-<P>
-<B>Note.</B> Use this routine only if the projection is PROJECTION_LL.
-
-<P>
-
-
\section Raster_File_Processing GRASS Raster File Processing
- Please refer to GRASS Raster File Processing in Chapter \ref gisrastintro .
+Please refer to GRASS Raster File Processing in Chapter \ref gisrastintro.
\section Vector_File_Processing GRASS Vector File Processing
- Please refer to GRASS Vector File Processing in Chapter \ref gisvectintro .
- Note, that the old "sites" are stored as vector points since GRASS 6.
+Please refer to GRASS Vector File Processing in Chapter \ref
+gisvectintro. Note, that the old "sites" are stored as vector points
+since GRASS 6.
\section General_Plotting_Routines General Plotting Routines
@@ -1478,115 +1015,59 @@
The following routines form the foundation of a general purpose line
and polygon plotting capability.
-<P>
-int G_bresenham_line() Bresenham line algorithm
+ - G_bresenham_line()
-Draws a line from <B>x1,y1</B> to <B>x2,y2</B> using Bresenham's
+Draws a line from one point to another using Bresenham's
algorithm. A routine to plot points must be provided, as is defined
-as:
+as: <tt>point(x, y)</tt> plot a point at x,y.
-<P>
-point(x, y) plot a point at x,y
-
-<P>
-This routine does not require a previous call to <I>G_setup_plot()</I> to
+This routine does not require a previous call to G_setup_plot() to
function correctly, and is independent of all following routines.
-<P>
-int G_setup_plot() initialize plotting routines
+ - G_setup_plot()
Initializes the plotting capability. This routine must be called once
-before calling the <B>G_plot_*()</B> routines described below.
+before calling the G_plot_*() routines described below.
-<P>
-The parameters <B>t, b, l, r</B> are the top, bottom, left, and right
-of the output x,y coordinate space. They are not integers, but doubles
-to allow for subpixel registration of the input and output coordinate
-spaces. The input coordinate space is assumed to be the current GRASS
-region, and the routines supports both planimetric and
-latitude-longitude coordinate systems.
+ - G_plot_line()
-<P>
-<B>Move</B> and <B>Cont</B> are subroutines that will draw lines in
-x,y space. They will be called as follows:
+Plots line between latlon coordinates. This routine handles global
+wrap-around for latitude-longitude databases. See G_setup_plot() for
+the required coordinate initialization procedure.
-<P>
-Move(x, y) move to x,y (no draw)
+ - G_plot_polygon()
-<P>
-Cont(x, y) draw from previous position
+Plots filled polygon with n vertices. See G_setup_plot() for the
+required coordinate initialization procedure.
-<P>
-to x,y. Cont() is responsible for clipping
+ - G_plot_area()
-<P>
-int G_plot_line() plot line between latlon coordinates
-
-A line from <B>east1,north1</B> to <B>east2,north2</B> is plotted in
-output x,y coordinates (e.g. pixels for graphics.) This routine
-handles global wrap-around for latitude-longitude databases.
-
-<P>
-See <B>G_setup_plot()</B> for the required coordinate initialization
-procedure.
-
-<P>
-int G_plot_polygon() plot filled
-polygon with n vertices
-
-The polygon, described by the <B>n</B> vertices <B>east,north</B>, is
-plotted in the output x,y space as a filled polygon.
-
-<P>
-See <B>G_setup_plot()</B> for the required coordinate initialization
-procedure.
-
-<P>
-int G_plot_area() plot multiple polygons
-
-Like G_plot_polygon(), except it takes a set of polygons, each with
-<B>npts[<I>i</I>]</B> vertices, where the number of polygons is
-specified with the <B>rings</B> argument. It is especially useful for
+Plots multiple polygons. Like G_plot_polygon(), except it takes a set
+of polygons, each with n vertices, where the number of polygons is
+specified with the <i>rings</i> argument. It is especially useful for
plotting vector areas with interior islands.
-<P>
-int G_plot_where_en() x,y to east,north
+ - G_plot_where_en()
-The pixel coordinates <B>x,y</B> are converted to map coordinates
-<B>east,north.</B>
+The pixel coordinates <i>x,y</i> are converted to map coordinates
+east,north</i>. See G_setup_plot() for the required coordinate
+initialization procedure.
-<P>
-See <B>G_setup_plot()</B> for the required coordinate initialization
-procedure.
+ - G_plot_where_xy()
-<P>
-int G_plot_where_xy() east,north to x,y
+The map coordinates <i>east,north</i> are converted to pixel
+coordinates <i>x,y.</i>. See G_setup_plot() for the required
+coordinate initialization procedure.
-The map coordinates <B>east,north</B> are converted to pixel
-coordinates <B>x,y.</B>
+ - G_plot_fx()
-<P>
-See <B>G_setup_plot()</B> for the required coordinate initialization
-procedure.
-
-<P>
-int G_plot_fx() plot f(east1) to f(east2)
-
-The function <B>f(east)</B> is plotted from <B>east1</B> to
-<B>east2.</B> The function <B>f(east)</B> must return the map northing
-coordinate associated with east.
-
-<P>
-See <B>G_setup_plot()</B> for the required coordinate initialization
-procedure.
-
-
\section Temporary_Files Temporary Files
+
Often it is necessary for modules to use temporary files to store
information that is only useful during the module run. After the
module finishes, the information in the temporary file is no longer
-needed and the file is removed. Commonly it is required that
+needed and the file is removed. Commonly it is required that
temporary file names be unique from invocation to invocation of the
module. It would not be good for a fixed name like "/tmp/mytempfile"
to be used. If the module were run by two users at the same time, they
@@ -1595,34 +1076,29 @@
The following routine generates temporary file names which are unique
within the module and across all GRASS programs.
-<P>
-char * G_tempfile() returns a temporary file name
+ - G_tempfile()
This routine returns a pointer to a string containing a unique file
name that can be used as a temporary file within the
module. Successive calls to G_tempfile() will generate new names.
-<P>
Only the file name is generated. The file itself is not created. To
create the file, the module must use standard UNIX functions which
create and open files, e.g., creat() or fopen().
-<P>
The programmer should take reasonable care to remove (unlink) the file
before the module exits. However, GRASS database management will
eventually remove all temporary files created by G_tempfile() that
have been left behind by the modules which created them.
-<P>
-<B>Note.</B> The temporary files are created in the GRASS database
-rather than under /tmp. This is done for two reasons. The first is to
-increase the likelihood that enough disk is available for large
-temporary files since /tmp may be a very small file system. The second
-is so that abandoned temporary files can be automatically removed (but
-see the warning below).
+<b>Note:</b> The temporary files are created in the GRASS database
+rather than under <tt>/tmp</tt>. This is done for two reasons. The
+first is to increase the likelihood that enough disk is available for
+large temporary files since /tmp may be a very small file system. The
+second is so that abandoned temporary files can be automatically
+removed (but see the warning below).
-<P>
-<B>Warning.</B> The temporary files are named, in part, using the
+<b>Warning:</b> The temporary files are named, in part, using the
process id of the module. GRASS database management will remove these
files only if the module which created them is no longer
running. However, this feature has a subtle trap. Programs which
@@ -1634,8 +1110,9 @@
\section Command_Line_Parsing Command Line Parsing
+
The following routines provide a standard mechanism for command line
-parsing. Use of the provided set of routines will standardize GRASS
+parsing. Use of the provided set of routines will standardize GRASS
commands that expect command line arguments, creating a family of
GRASS modules that is easy for users to learn. As soon as a GRASS user
familiarizes himself with the general form of command line input as
@@ -1648,27 +1125,22 @@
limit the programmer to a pre-defined look and feel, but limiting the
interface is well worth the shortened user learning curve.
-
\subsection Description Description
+
The GRASS parser is a collection of five subroutines which use two
structures that are defined in the GRASS "gis.h" header file. These
structures allow the programmer to define the options and flags that
make up the valid command line input of a GRASS command.
-<P>
The parser routines behave in one of three ways:
-<P>
-(1) If no command line arguments are entered by the user, the parser
+ # If no command line arguments are entered by the user, the parser
searches for a completely interactive version of the command. If the
interactive version is found, control is passed over to this
-version. If not, the parser will prompt the user for all
-programmer-defined options and flags. This prompting conforms to the
-same standard for every GRASS command that uses the parser routines.
+version.
-<P>
-(2) If command line arguments are entered but they are a subset of the
+ # If command line arguments are entered but they are a subset of the
options and flags that the programmer has defined as required
arguments, three things happen. The parser will pass an error message
to the user indicating which required options and/or flags were
@@ -1676,181 +1148,155 @@
usage message for that command, and finally the parser cancels
execution of the command.
-<P>
-(3) If all necessary options and flags are entered on the command line
+ # If all necessary options and flags are entered on the command line
by the user, the parser executes the command with the given options
and flags.
\subsection Structures Structures
-<P>
The parser routines described below use two structures as defined in
the GRASS "gis.h" header file.
-<P>
-This is a basic list of members of the Option and Flag structures. A
-comprehensive description of all elements of these two structures and
-their possible values can be found in
-Full_Structure_Members_Description.
+This is a basic list of members of the <b>Option</b> and <b>Flag</b>
+structures. A comprehensive description of all elements of these two
+structures and their possible values can be found in
+\ref Full_Structure_Members_Description.
-
\subsection Option_structure Option structure
-These are the basic members of the Option structure.
+These are the basic members of the <em>Option</em> structure.
-\verbatim
+\code
struct Option *opt; /* to declare a command line option */
-\endverbatim
+\endcode
-<P>
-<B>Structure Member Description of Member</B>
+Structure Member Description of Member:
-\verbatim
-opt->key Option name that user will use
-opt->description Option description that is shown to the user
-opt->type Variable type of the user's answer to the option
-opt->required Is this option required on the command line? (Boolean)
-\endverbatim
+ - <i>opt->key</i> - Option name that user will use
+ - <i>opt->description</i> - Option description that is shown to the user
+ - <i>opt->type</i> - Variable type of the user's answer to the option
+ - <i>opt->required</i> - Is this option required on the command line? (Boolean)
-
\subsection Flag_structure Flag structure
-<P>
These are the basic members of the Flag structure.
-\verbatim
+\code
struct Flag *flag; /* to declare a command line flag */
-\endverbatim
+\endcode
-<B>Structure Member Description of Member</B>
+Structure Member Description of Member:
-\verbatim
-flag->key Single letter used for flag name
-flag->description Flag description that is shown to the user
-\endverbatim
+ - <i>flag->key</i> - Single letter used for flag name
+ - <i>flag->description</i> - Flag description that is shown to the user
+\endcode
-
\subsection Parser_Routines Parser Routines
-<P>
+
Associated with the parser are five routines that are automatically
included in the GRASS Makefile process. The Makefile process is
documented in \ref Compiling_and_Installing_GRASS_Modules.
-<P>
-struct Option * G_define_option() returns Option structure
+ - G_define_option()
-Allocates memory for the Option structure and returns a pointer to
-this memory (of <I>type struct Option *).</I>
+Returns <i>Option</i> structure. Allocates memory for the Option structure
+and returns a pointer to this memory.
-<P>
-struct Flag * G_define_flag() return Flag structure
+ - G_define_flag()
-Allocates memory for the Flag structure and returns a pointer to this
-memory (of <I>type struct Flag *).</I>
+Allocates memory for the <i>Flag</i> structure and returns a pointer
+to this memory.
-<P>
-int G_parser() parse command line
+ - G_parser()
-The command line parameters <B>argv</B> and the number of parameters
-<B>argc</B> from the main() routine are passed directly to
-<I>G_parser()</I>. <I>G_parser()</I> accepts the command line input
+The command line parameters <i>argv</i> and the number of parameters
+<i>argc</i> from the main() routine are passed directly to
+G_parser(). G_parser() accepts the command line input
entered by the user, and parses this input according to the input
options and/or flags that were defined by the programmer.
-<P>
-<I>G_parser()</I> returns 0 if successful. If not successful, a usage
+G_parser() returns 0 if successful. If not successful, a usage
statement is displayed that describes the expected and/or required
options and flags and a non-zero value is returned.
-<P>
-int G_usage() command line help/usage message
+ - G_usage()
-Calls to <I>G_usage()</I> allow the programmer to print the usage
-message at any time. This will explain the allowed and required
-command line input to the user. This description is given according to
-the programmer's definitions for options and flags. This function
-becomes useful when the user enters options and/or flags on the
-command line that are syntactically valid to the parser, but
-functionally invalid for the command (e.g. an invalid file name.)
+Calls to G_usage() allow the programmer to print the usage message at
+any time. This will explain the allowed and required command line
+input to the user. This description is given according to the
+programmer's definitions for options and flags. This function becomes
+useful when the user enters options and/or flags on the command line
+that are syntactically valid to the parser, but functionally invalid
+for the command (e.g. an invalid file name).
-<P>
For example, the parser logic doesn't directly support grouping
options. If two options be specified together or not at all, the
parser must be told that these options are not required and the
programmer must check that if one is specified the other must be as
-well. If this additional check fails, then <I>G_parser()</I> will
-succeed, but the programmer can then call <I>G_usage()</I> to print
+well. If this additional check fails, then G_parser() will
+succeed, but the programmer can then call G_usage() to print
the standard usage message and print additional information about how
the two options work together.
-<P>
-int G_disable_interactive() turns off interactive capability
+ - G_disable_interactive()
When a user calls a command with no arguments on the command line, the
parser will enter its own standardized interactive session in which
all flags and options are presented to the user for input. A call to
-<I>G_disable_interactive()</I> disables the parser's interactive
-prompting.
+G_disable_interactive() disables the parser's interactive prompting.
-<P>
-<B>Note:</B> Displaying multiple answers default values (new in GRASS
+<b>Note:</b> Displaying multiple answers default values (new in GRASS
5, see d.zoom for example).
-\verbatim
+\code
char *def[] = {"One", "Two", "Last", NULL};
opt->multiple = YES;
opt->answers = def;
if (G_parser(argc, argv))
exit(EXIT_FAILURE);
-\endverbatim
+\endcode
-<P>
The programmer may not forget last NULL value.
\subsection Parser_Programming_Examples Parser Programming Examples
-<P>
The use of the parser in the programming process is demonstrated
here. Both a basic step by step example and full code example are
presented.
-
\subsection Step_by_Step_Use_of_the_Parser Step by Step Use of the Parser
+
These are the four basic steps to follow to implement the use of the
GRASS parser in a GRASS command:
-<P>
-(1) Allocate memory for Flags and Options:
+<b>(1) Allocate memory for Flags and Options:</b>
-<P>
Flags and Options are pointers to structures allocated through the
-parser routines <I>G_define_option()</I> and <I>G_define_flag()</I> as
-defined in Parser_Routines.
+parser routines G_define_option() and G_define_flag() as
+defined in \ref Parser_Routines.
-\verbatim
-#include <grass/gis.h> ; /* The standard GRASS include file */
+\code
+#include <grass/gis.h>; /* The standard GRASS include file */
-struct Option *opt ; /* Establish an Option pointer for each option */
-struct Flag *flag ; /* Establish a Flag pointer for each option */
+struct Option *opt; /* Establish an Option pointer for each option */
+struct Flag *flag; /* Establish a Flag pointer for each option */
-opt = G_define_option() ; /* Request a pointer to memory for each option */
+opt = G_define_option(); /* Request a pointer to memory for each option */
-flag = G_define_flag() ; /* Request a pointer to memory for each flag */
-\endverbatim
+flag = G_define_flag(); /* Request a pointer to memory for each flag */
+\endcode
-<P>
-(2) Define members of Flag and Option structures:
+<b>(2) Define members of Flag and Option structures:</b>
-<P>
The programmer should define the characteristics of each option and
flag desired as outlined by the following example:
-\verbatim
+\code
opt->key = "option"; /* The name of this option is "option". */
opt->description = _("Option test"); /* The option description is "Option test" */
opt->type = TYPE_STRING; /* The data type of the answer to the option */
@@ -1858,49 +1304,41 @@
flag->key = "t"; /* Single letter name for flag */
flag->description = _("Flag test"); /* The flag description is "Flag test" */
-\endverbatim
+\endcode
-
-<B>Note.</B>There are more options defined later in
+<b>Note:</b> There are more options defined later in \ref
Complete_Structure_Members_Table.
-<P>
-(3) Call the parser:
+<b>(3) Call the parser:</b>
-\verbatim
-int
-main(int argc, char *argv[]); /* command line args passed into main() */
+\code
+int main(int argc, char *argv[]); /* command line args passed into main() */
-if (G_parser(argc, argv)) /* Returns 0 if successful, non-zero otherwise */
+if (G_parser(argc, argv)) /* Returns 0 if successful, non-zero otherwise */
exit(EXIT_FAILURE);
-\endverbatim
+\endcode
+<b>(4) Extracting information from the parser structures:</b>
-(4) Extracting information from the parser structures:
+\code
+fprintf(stdout, "For the option "%s" you chose: <%s>\n", opt->description, opt->answer);
+fprintf(stdout, "The flag "-%s" is %s set.\n", flag->key, flag->answer ? "" : "not");
+\endcode
-\verbatim
-fprintf(stdout, "For the option "%s" you chose: <%s>\n", opt->description, opt->answer );
-fprintf(stdout, "The flag "-%s" is %s set.\n", flag->key, flag->answer ? "" : "not" );
-\endverbatim
+<b>(5) Running the example program</b>
-
-<P>
-(5) Running the example program
-
-<P>
Once such a module has been compiled (for example to the default
-executable file <I>a.out</I> , execution will result in the following
-user interface scenarios. Lines that begin with # imply user entered
+executable file <tt>a.out</tt> , execution will result in the following
+user interface scenarios. Lines that begin with '$' imply user entered
commands on the command line.
\verbatim
-# a.out help
+$ a.out help
\endverbatim
-<P>
This is a standard user call for basic help information on the
module. The command line options (in this case, "help") are sent to
-the parser via <I>G_parser().</I> The parser recognizes the "help"
+the parser via G_parser(). The parser recognizes the "help"
command line option and returns a list of options and/or flags that
are applicable for the specific command. Note how the programmer
provided option and flag information is captured in the output.
@@ -1921,7 +1359,6 @@
# a.out -t
\endverbatim
-<P>
This command line does not contain the required option. Note that the
output provides this information along with the standard usage message
(as already shown above):
@@ -1941,7 +1378,6 @@
option Option test
\endverbatim
-<P>
The following commands are correct and equivalent. The parser provides no
error messages and the module executes normally:
@@ -1954,43 +1390,14 @@
The flag "-t" is set.
\endverbatim
-<P>
-If this specific command has no fully interactive version (a user
-interface that does not use the parser), the parser will prompt for
-all programmer-defined options and/or flags.
-
-<P>
-User input is in <I>italics</I>, default answers are displayed in
-square brackets [ ].
-
-\verbatim
-# a.out
-
-OPTION: Option test
-
-key: option
-required: YES
-enter option> <I>Hello</I>
-
-You have chosen:
-option=Hello
-Is this correct? (y/n) [y] <I>y</I>
-FLAG: Set the following flag?
-Flag test? (y/n) [n] <I>n</I>
-You chose: <Hello>
-The flag is not set
-\endverbatim
-
-
\section Full_Module_Example Full Module Example
-<P>
The following code demonstrates some of the basic capabilities of the
parser. To compile this code, create this Makefile and run the
-<I>make</I> command (see \ref Compiling_and_Installing_GRASS_Modules.
+<tt>make</tt> command (see \ref Compiling_and_Installing_GRASS_Modules).
-\verbatim
+\code
MODULE_TOPDIR = ../..
PGM = r.mysample
@@ -2001,86 +1408,83 @@
include $(MODULE_TOPDIR)/include/Make/Module.make
default: cmd
-\endverbatim
+\endcode
-
-<P>
-The sample.c code follows. You might experiment with this code to
+The <tt>sample.c</tt> code follows. You might experiment with this code to
familiarize yourself with the parser.
-<P>
-<B>Note.</B> This example includes some of the advanced structure members
-described in Complete_Structure_Members_Table.
+<b>Note:</b> This example includes some of the advanced structure
+members described in \ref Complete_Structure_Members_Table.
-\verbatim
+\code
#include <stdlib.h>
#include <string.h>
#include <grass/gis.h>
-#include "glocale.h"
+#include <grass/glocale.h>
-int
-main(int argc , char *argv[] )
+int main(int argc , char *argv[] )
{
- struct Option *opt ;
- struct Option *coor ;
- struct Flag *flag ;
- double X , Y ;
- int n ;
+ struct Option *opt;
+ struct Option *coor;
+ struct Flag *flag;
+ double X , Y;
+ int n;
- opt = G_define_option() ;
- opt->key = "debug" ;
- opt->type = TYPE_STRING ;
- opt->required = NO ;
- opt->answer = "0" ;
- opt->description = _("Debug level") ;
+ opt = G_define_option();
+ opt->key = "debug";
+ opt->type = TYPE_STRING;
+ opt->required = NO;
+ opt->answer = "0";
+ opt->description = _("Debug level");
- coor = G_define_option() ;
- coor->key = "coordinate" ;
- coor->key_desc = "x,y" ;
- coor->type = TYPE_STRING ;
- coor->required = YES ;
- coor->multiple = YES ;
- coor->description = _("One or more coordinates") ;
+ coor = G_define_option();
+ coor->key = "coordinate";
+ coor->key_desc = "x,y";
+ coor->type = TYPE_STRING;
+ coor->required = YES;
+ coor->multiple = YES;
+ coor->description = _("One or more coordinates");
/* Note that coor->answer is not given a default value. */
- flag = G_define_flag() ;
- flag->key = 'v' ;
- flag->description = _("Verbose execution") ;
+ flag = G_define_flag();
+ flag->key = 'v';
+ flag->description = _("Verbose execution");
/* Note that flag->answer is not given a default value. */
if (G_parser( argc , argv ))
exit (EXIT_FAILURE);
- G_message("For the option <%s> you chose: <%s>\n", opt->description, opt->answer );
- G_message("The flag <%s> is: %s set \n", flag->key, flag->answer ? "" : "not");
- G_message("You specified the following coordinates:\n");
+ G_message("For the option <%s> you chose: <%s>", opt->description, opt->answer);
+ G_message("The flag <%s> is: %s set", flag->key, flag->answer ? "" : "not");
+ G_message("You specified the following coordinates:");
for ( n=0 ; coor->answers[n] != NULL ; n+=2 ) {
- G_scan_easting ( coor->answers[n ] , &X , G_projection() );
- G_scan_northing ( coor->answers[n+1] , &Y , G_projection() );
- G_message( "%.31f,%.21f\n", X , Y );
+ G_scan_easting ( coor->answers[n ] , &X , G_projection());
+ G_scan_northing ( coor->answers[n+1] , &Y , G_projection());
+ G_message( "%.31f,%.21f\n", X , Y);
}
}
-\endverbatim
+\endcode
-
\section Compiling_and_Installing_GRASS_Modules Compiling and Installing GRASS Modules
-GRASS modules are compiled and installed using the UNIX <i>make</i> command:
-<i>make</i> reads a file named <i>Makefile</i> (see
-Multiple_Architecture_Conventions for more information,) and then runs
-the compiler. The GRASS compilation process allows for multiple-architecture
-compilation from a single copy of the source code (for instance, if the source
-code is NFS mounted to various machines with differing architectures.) This
-chapter assumes that the programmer is familiar with <i>make</i> and its
-accompanying <i>Makefile</i>.
-<b>TODO: Explain ''auto-conf''....</b>
+GRASS modules are compiled and installed using the UNIX <tt>make</tt>
+command, which reads a file named <tt>Makefile</tt> (see \ref
+Multiple_Architecture_Conventions for more information) and then runs
+the compiler. The GRASS compilation process allows for
+multiple-architecture compilation from a single copy of the source
+code (for instance, if the source code is NFS mounted to various
+machines with differing architectures). This chapter assumes that the
+programmer is familiar with <tt>make</tt> and its accompanying
+Makefile.
-<b>TODO: Include contents of SUBMITTING and INSTALL files from source code</b>
+\todo Explain ''auto-conf''
+\todo Include contents of SUBMITTING and INSTALL files from source code
+
To compile enter following:
\verbatim
@@ -2090,7 +1494,7 @@
\endverbatim
Then the code will be compiled into "/usr/local/grass-7.x.y" directory. The start
-script "grass7x" will be placed into "/usr/local/bin/".\\
+script "grass7x" will be placed into "/usr/local/bin/".
Optionally other target directories can be specified while "configuring":
@@ -2100,133 +1504,122 @@
make install
\endverbatim
-This will store the GRASS binaries into the directory "/opt/grass-7.x.y" and
-the script mentioned above into "/usr/bin".
+This will store the GRASS binaries into the directory
+"/opt/grass-7.x.y" and the script mentioned above into "/usr/bin".
The script "make" is required to compile single modules. The
compilation process and requirements are discussed in more detail now.
\subsection Makefile_Variables Makefile Variables
+\todo Update the list.
+
<b>GRASS Libraries</b>. The following variables name the various GRASS
libraries:
-<i>GISLIB</i> This names the <i>GIS Library</i>, which is the principal GRASS
-library. See \ref GIS_Library for details about this library, and
-\ref Loading_the_GIS_Library for a sample Makefile which
+ - <i>GISLIB</i> - This names the <b>GIS Library</b>, which is the
+principal GRASS library. See \ref GIS_Library for details about this
+library, and \ref Loading_the_GIS_Library for a sample Makefile which
loads this library.
-<i>VASKLIB</i> This names the <i>Vask Library</i>, which does full screen user
-input.
+ - <i>SEGMENTLIB</i> - This names the <b>Segment Library</b>, which
+manages large matrix data. See \ref Segment_Library for details about
+this library, and \ref Loading_the_Vask_Library for a sample
+<i>Makefile</i> which loads this library.
-<i>VASK</i> This specifies the <i>Vask Library</i> plus the UNIX [n]curses and
-termcap libraries needed to use the <i>Vask Library</i> routines. See
-\ref Vask_Library for details about this library, and \ref Loading_the_Vask_Library
-for a sample Makefile which loads this library.
+ - <i>RASTERLIB</i> - This names the <b>Raster Graphics Library</b>,
+which communicates with GRASS graphics drivers. See \ref
+Raster_Graphics_Library for details about this library, and \ref
+Loading_the_Raster_Graphics_Library for a sample <i>Makefile</i> which
+loads this library.
-<i>SEGMENTLIB</i> This names the <i>Segment Library</i>, which manages large
-matrix data. See \ref Segment_Library for details about this library,
-and \ref Loading_the_Vask_Library for a sample <i>Makefile</i> which loads
-this library.
+ - <i>DISPLAYLIB</i> - This names the <b>Display Graphics Library</b>,
+which provides a higher level graphics interface to
+<i>RASTERLIB</i>. See Display_Graphics_Library for details about this
+library, and Loading_the_Display_Graphics_Library for a sample
+<i>Makefile</i> which loads this library.
-<i>RASTERLIB</i> This names the <i>Raster Graphics Library</i>, which
-communicates with GRASS graphics drivers. See \ref Raster_Graphics_Library
- for details about this library, and \ref Loading_the_Raster_Graphics_Library
-for a sample <i>Makefile</i> which loads this library.
-
-<i>DISPLAYLIB</i> This names the <i>Display Graphics Library</i>, which provides a
-higher level graphics interface to <i>RASTERLIB</i>. See
-Display_Graphics_Library for details about this library, and
-Loading_the_Display_Graphics_Library for a sample <i>Makefile</i>
-which loads this library.\\
-
-
-
<b>UNIX Libraries:</b> The following variables name some useful UNIX
system libraries:
-<i>MATHLIB</i> This names the math library. It should be used instead of the -lm
-loader option.
+ - <i>MATHLIB</i> This names the math library. It should be used
+instead of the -lm loader option.
-<i>CURSES</i> This names both the curses and termcap libraries. It should be used
-instead of the \newline
--lcurses/-lncurses and -ltermcap loader options. Do not use <tt>$CURSES</tt> if
-you use <tt>$VASK</tt>.
+ - <i>CURSES</i> This names both the curses and termcap libraries. It
+should be used instead of the -lcurses/-lncurses and
+-ltermcap loader options. Do not use <tt>$CURSES</tt> if you use
+<tt>$VASK</tt>.
-<i>TERMLIB</i> This names the termcap library. It should be used instead of the
--ltermcap or -ltermlib loader options. Do not use <tt>$TERMLIB</tt> if you use
-<tt>$VASK</tt> or <tt>$CURSES</tt>.\\
+ - <i>TERMLIB</i> This names the termcap library. It should be used
+-instead of the ltermcap or -ltermlib loader options. Do not use
+-<tt>$TERMLIB</tt> if you use <tt>$VASK</tt> or <tt>$CURSES</tt>.
+<b>Compiler and loader variables.</b> The following variables are
+related to compiling and loading C programs:
-<b>Compiler and loader variables.</b> The following variables are related
-to compiling and loading C programs:
+ - <i>EXTRA\_CFLAGS</i> This variable can be used to add additional
+options to <tt>$CFLAGS</tt>. It has no predefined values. It is
+usually used to specify additional -I include directories, or -D
+preprocessor defines.
-<i>EXTRA\_CFLAGS</i> This variable can be used to add additional options
-to <tt>$CFLAGS</tt>. It has no predefined values. It is usually used to specify
-additional -I include directories, or -D preprocessor defines.
-
-
\subsection Constructing_a_Makefile Constructing a Makefile
+
The complete syntax for a <i>Makefile</i> is discussed in the UNIX
-documentation for <i>make</i> and will not be repeated here. The essential
-idea is that a target (e.g. a GRASS module) is to be built from a list of
-dependencies (e.g. object files, libraries, etc.). The relationship between
-the target, its dependencies, and the rules for constructing the target is
-expressed according to the following syntax:
+documentation for <tt>make</tt> and will not be repeated here. The
+essential idea is that a target (e.g. a GRASS module) is to be built
+from a list of dependencies (e.g. object files, libraries, etc.). The
+relationship between the target, its dependencies, and the rules for
+constructing the target is expressed according to the following
+syntax:
-\verbatim
+\code
target: dependencies
actions
more actions
-\endverbatim
+\endcode
If the target does not exist, or if any of the dependencies have a newer
date than the target (i.e., have changed), the actions will be executed to
-build the target. The actions must be indented using a TAB. <i>make</i> is
+build the target. The actions must be indented using a TAB. <tt>make</tt> is
picky about this. It does not like spaces in place of the TAB.
-
\section Multiple_Architecture_Conventions Multiple-Architecture Conventions
+
The following conventions allow for multiple architecture compilation on a
machine that uses a common or networked GRASS source code directory tree.
-<P>
-Object files and library archives are compiled into subdirectories that
-represent the architecture that they were compiled on. These subdirectories
-are created in the $SRC directory as OBJ.<I>arch</I> and
-LIB.<I>arch</I>, where <I>arch</I> represents the architecture of the
-compiling machine. Thus, for example, $SRC/OBJ.sun4 would contain the
-object files for Sun/4 and SPARC architectures, and $SRC/LIB.686-pc-linux-gnu would
-contain library archives for Linux architectures. Likewise,
-$SRC/OBJ.686-pc-linux-gnu would contain the object files for Linux architectures,
-and $SRC/LIB.686-pc-linux-gnu would contain library archives for Linux
-architectures.
+Object files and library archives are compiled into subdirectories
+that represent the architecture that they were compiled on. These
+subdirectories are created in the $SRC directory as OBJ.<tt>arch</tt>
+and LIB.<tt>arch</tt>, where <tt>arch</tt> represents the architecture
+of the compiling machine. Thus, for example, $SRC/OBJ.sun4 would
+contain the object files for Sun/4 and SPARC architectures, and
+<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
+Linux architectures. Likewise, <tt>$SRC/OBJ.686-pc-linux-gnu</tt>
+would contain the object files for Linux architectures, and
+<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
+Linux architectures.
-<P>
Note that 'arch' is defined for a specific architecture during setup and
compilation of GRASS, it is not limited to sun4 or any specific string.
-
\section Full_Structure_Members_Description Full Structure Members Description
-<P>
-There are many members to the Option and Flag structures. The following
-tables and descriptions summarize all defined members of both the Option and
-Flag structures.
+There are many members to the <b>Option</b> and <b>Flag</b>
+structures. The following tables and descriptions summarize all
+defined members of both the Option and Flag structures.
-<P>
-An in-depth summary of the more complex structure members is presented in
-Description_of_Complex_Structure_Members.
+An in-depth summary of the more complex structure members is presented
+in \ref Description_of_Complex_Structure_Members.
-
\section Complete_Structure_Members_Table Complete Structure Members Table
-<B>struct Flag</B>
+<v>struct Flag</v>
<table border=1>
<tr>
<td>structure member</td>
@@ -2258,8 +1651,7 @@
</tr>
</table>
-<P>
-<B>struct Option</B>
+<b>struct Option</b>
<table border=1>
<tr>
<td>structure member</td>
@@ -2379,67 +1771,58 @@
\section Description_of_Complex_Structure_Members Description of Complex Structure Members
+
What follows are explanations of possibly confusing structure
members. It is intended to clarify and supplement the structures table
above.
-
\subsection Answer_member_of_the_Flag_and_Option_structures Answer member of the Flag and Option structures
The answer structure member serves two functions for GRASS commands
that use the parser.
-<P>
-<B><I>(1) To set the default answer to an option:</I></B>
+<b>(1) To set the default answer to an option:</b>
-<P>
If a default state is desired for a programmer-defined option, the
programmer may define the Option structure member "answer" before
-calling <I>G_parser()</I> in his module. After the <I>G_parser()</I> call,
-the answer member will hold this preset default value if the user did
-<I>not</I> enter an option that has the default answer member value.
+calling G_parser() in his module. After the G_parser() call, the
+answer member will hold this preset default value if the user did
+<i>not</i> enter an option that has the default answer member value.
-<P>
-<B><I>(2) To obtain the command-line answer to an option or flag:
-After a call to</I> </B><B>G_parser()</B><B><I>, the answer member will
-contain one of two values:</I></B>
+<b>(2) To obtain the command-line answer to an option or flag:</b>
-<P>
-(a) If the user provided an option, and answered this option on the command
-line, the default value of the answer member (as described above) is
-replaced by the user's input.
+After a call to G_parser(), the answer member will contain one of two
+values:
-<P>
-(b) If the user provided an option, but did <I>not</I> answer this option
-on the command line, the default is not used. The user may use the default
-answer to an option by withholding mention of the option on the command
-line. But if the user enters an option without an answer, the default answer
-member value will be replaced and set to a NULL value by <I>G_parser().</I>
+ - (a) If the user provided an option, and answered this option on the
+command line, the default value of the answer member (as described
+above) is replaced by the user's input.
-<P>
+ - (b) If the user provided an option, but did <i>not</i> answer this
+option on the command line, the default is not used. The user may use
+the default answer to an option by withholding mention of the option
+on the command line. But if the user enters an option without an
+answer, the default answer member value will be replaced and set to a
+NULL value by G_parser().
+
As an example, please review the use of answer members in the structures
-implemented in Full_Module_Example.
+implemented in \ref Full_Module_Example.
-
\subsection Multiple_and_Answers_Members Multiple and Answers Members
-<P>
The functionality of the answers structure member is reliant on the
programmer's definition of the multiple structure member. If the multiple
member is set to NO, the answer member is used to obtain the answer to an
option as described above.
-<P>
-If the multiple structure member is set to YES, the programmer has told
-<I>G_parser()</I> to capture multiple answers. Multiple answers are
-separated by commas on the command line after an option.
+If the multiple structure member is set to YES, the programmer has
+told G_parser() to capture multiple answers. Multiple answers are
+separated by <em>commas</em> on the command line after an option.
-<P>
-<B>Note.</B> <I>G_parser()</I> does not recognize any character other
-than a comma to delimit multiple answers.
+<b>Note:</b> G_parser() does not recognize any character other than a
+comma to delimit multiple answers.
-<P>
After the programmer has set up an option to receive multiple answers,
these the answers are stored in the answers member of the Option
structure. The answers member is an array that contains each
@@ -2448,114 +1831,100 @@
array contains however many comma-delimited answers the user entered,
followed (terminated) by a NULL array element.
-<P>
-For example, here is a sample definition of an Option using multiple and
-answers structure members:
+For example, here is a sample definition of an Option using multiple
+and answers structure members:
-\verbatim
-opt->key ="option" ;
-opt->description = _("option example") ;
-opt->type = TYPE_INTEGER ;
-opt->required = NO ;
-opt->multiple = YES ;
-\endverbatim
+\code
+opt->key ="option";
+opt->description = _("option example");
+opt->type = TYPE_INTEGER;
+opt->required = NO;
+opt->multiple = YES;
+\endcode
-<P>
The above definition would ask the user for multiple integer answers
to the option. If in response to a routine that contained the above
code, the user entered "option=1,3,8,15" on the command line, the
answers array would contain the following values:
-\verbatim
+\code
answers[0] == 1
answers[1] == 3
answers[2] == 8
answers[3] == 15
answers[4] == NULL
-\endverbatim
+\endcode
+
\subsection key_desc_Member key_desc Member
-<P>
-The key_desc structure member is used to define the format of a single
+The <b>key_desc</b> structure member is used to define the format of a single
command line answer to an option. A programmer may wish to ask for one
answer to an option, but this answer may not be a single argument of a type
set by the type structure member. If the programmer wants the user to enter
a coordinate, for example, the programmer might define an Option as follows:
-\verbatim
-opt->key ="coordinate" ;
-opt->description = _("Specified Coordinate") ;
-opt->type = TYPE_INTEGER ;
-opt->required = NO ;
+\code
+opt->key ="coordinate";
+opt->description = _("Specified Coordinate");
+opt->type = TYPE_INTEGER;
+opt->required = NO;
opt->key_desc = "x,y"
-opt->multiple = NO ;
+opt->multiple = NO;
\endverbatim
-<P>
-The answer to this option would <I>not</I> be stored in the answer member,
-but in the answers member. If the user entered "coordinate=112,225" on the
-command line in response to a routine that contains the above option
-definition, the answers array would have the following values after the call
-to <I>G_parser()</I>:
+The answer to this option would <i>not</i> be stored in the answer
+member, but in the answers member. If the user entered
+"coordinate=112,225" on the command line in response to a routine that
+contains the above option definition, the answers array would have the
+following values after the call to G_parser():
-\verbatim
+\code
answers[0] == 112
answers[1] == 225
answers[2] == NULL
-\endverbatim
+\endcode
-<P>
Note that "coordinate=112" would not be valid, as it does not contain both
components of an answer as defined by the key_desc structure member.
-<P>
-If the multiple structure member were set to YES instead of NO in the
-example above, the answers are stored sequentially in the answers member.
-For example, if the user wanted to enter the coordinates (112,225),
-(142,155), and (43,201), his response on the command line would be
-"coordinate=112,225,142,155,43,201". Note that <I>G_parser()</I>
-recognizes only a comma for both the key_desc member, and for multiple
+If the multiple structure member were set to YES instead of NO in the
+example above, the answers are stored sequentially in the answers
+member. For example, if the user wanted to enter the coordinates
+(112,225), (142,155), and (43,201), his response on the command line
+would be "coordinate=112,225,142,155,43,201". Note that G_parser()
+recognizes only a comma for both the key_desc member, and for multiple
answers.
-<P>
The answers array would have the following values after a call to
-<I>G_parser()</I>:
+G_parser():
-\verbatim
+\code
answers[0] == 112 answers[1] == 225
answers[2] == 142 answers[3] == 155
answers[4] == 43 answers[5] == 201
answers[6] == NULL
-\endverbatim
+\endcode
-
-<P>
<B>Note.</B> In this case as well, neither "coordinate=112" nor
"coordinate=112,225,142" would be valid command line arguments, as
they do not contain even pairs of coordinates. Each answer's format
(as described by the key_desc member) must be fulfilled completely.
-<P>
The overall function of the key_desc and multiple structure members is
very similar. The key_desc member is used to specify the number of
-<I>required</I> components of a single option answer (e.g. a
-multi-valued coordinate.) The multiple member tells <I>G_parser()</I> to
-ask the user for multiple instances of the compound answer as defined
-by the format in the key_desc structure member.
+<i>required</i> components of a single option answer (e.g. a
+multi-valued coordinate.) The multiple member tells G_parser() to ask
+the user for multiple instances of the compound answer as defined by
+the format in the key_desc structure member.
-<P>
Another function of the key_desc structure member is to explain to the
user the type of information expected as an answer. The coordinate
example is explained above.
-<P>
-The usage message that is displayed by <I>G_parser()</I> in case of an
-error, or by
-
-<P>
-<I>G_usage()</I> on programmer demand, is shown below. The Option
-"option" for the command <I>a.out</I> does not have its key_desc
+The usage message that is displayed by G_parser() in case of an error,
+or by G_usage() on programmer demand, is shown below. The Option
+"option" for the command <tt>a.out</tt> does not have its key_desc
structure member defined.
\verbatim
@@ -2564,12 +1933,10 @@
a.out option=name
\endverbatim
-
-<P>
-The use of "name" is a <I>G_parser()</I> standard. If the programmer
-defines the key_desc structure member before a call to <I>G_parser()</I>,
-the value of the key_desc member replaces "name". Thus, if the key_desc
-member is set to "x,y" as was used in an example above, the following
+The use of "name" is a G_parser() standard. If the programmer defines
+the key_desc structure member before a call to G_parser(), the
+value of the key_desc member replaces "name". Thus, if the key_desc
+member is set to "x,y" as was used in an example above, the following
usage message would be displayed:
\verbatim
@@ -2578,127 +1945,92 @@
a.out option=x,y
\endverbatim
-<P>
-The key_desc structure member can be used by the programmer to clarify the
-usage message as well as specify single or multiple required components of a
-single option answer.
+The key_desc structure member can be used by the programmer to clarify
+the usage message as well as specify single or multiple required
+components of a single option answer.
-
\subsection gisprompt_Member gisprompt Member
-<P>
-The gisprompt Option structure item requires a bit more
+The <b>gisprompt</b> Option structure item requires a bit more
description. The three comma-separated (no spaces allowed)
sub-arguments are defined as follows:
-<P>
-First argument:
+ - First argument: "old" results in a call to the GRASS library
+subroutine G_open_old(), "new" to G_open_new(), otherwise "any" or
+"mapset".
-<P>
-"old" results in a call to the GRASS library subroutine
-<I>G_ask_old()</I>, "new" to <I>G_ask_new(), "any" to
-G_ask_any(), and "mapset" to G_ask_in_mapset().</I>
+ - Second argument: This is identical to the "element" argument in the
+above subroutine calls. It specifies a directory inside the mapset
+that may contain the user's response.
-<P>
-Second argument:
+ - Third argument: Identical to the "prompt" argument in the above
+subroutine calls. This is a string presented to the user that
+describes the type of data element being requested.
-<P>
-This is identical to the "element" argument in the above subroutine calls.
-It specifies a directory inside the mapset that may contain the user's
-response.
-
-<P>
-Third argument:
-
-<P>
-Identical to the "prompt" argument in the above subroutine calls. This is
-a string presented to the user that describes the type of data element being
-requested.
-
-<P>
Here are two examples:
-<P>
-<B>gisprompt arguments Resulting call</B>
+\verbatim
+"new,cell,raster" G_open_new("cell", "map")
+"old,vector,vector" G_open_old("vector", "map")
+\endverbatim
-<P>
-"new,cell,raster" G_ask_new("", buffer, "cell", "raster")
-
-<P>
-"old,dig,vector" G_ask_old("", buffer, "dig", "vector")
-
-<P>
-
\subsection Common_Questions Common Questions
-<P>
-"How is automatic prompting turned off?"
+ - "How is automatic prompting turned off?"
-<P>
-GRASS 4.0 introduced a new method for driving GRASS interactive and
-non-interactive modules as described in \ref Compiling_and_Installing_GRASS_Programs.
-Here is a short overview.
+GRASS 4.0 introduced a new method for driving GRASS interactive and
+non-interactive modules as described in \ref
+Compiling_and_Installing_GRASS_Programs. Here is a short overview.
-<P>
For most modules a user runs a front-end module out of the GRASS bin
directory which in turn looks for the existence of interactive and
non-interactive versions of the module. If an interactive version
exists and the user provided no command line arguments, then that
version is executed.
-<P>
-In such a situation, the parser's default interaction will never be seen by
-the user. A programmer using the parser is able to avoid the front-end's
-default search for a fully interactive version of the command by placing a
-call to <I>G_disable_interactive()</I> before calling <I>G_parser()</I>
-(see \ref Parser_Routines for details.)
+In such a situation, the parser's default interaction will never be
+seen by the user. A programmer using the parser is able to avoid the
+front-end's default search for a fully interactive version of the
+command by placing a call to G_disable_interactive() before
+calling G_parser() (see \ref Parser_Routines for details).
-<P>
-"Can the user mix options and flags?"
+ - "Can the user mix options and flags?"
-<P>
Yes. Options and flags can be given in any order.
-<P>
-"In what order does the parser present options and flags?"
+ - "In what order does the parser present options and flags?"
-<P>
-Flags and options are presented by the usage message in the order that the
-programmer defines them using calls to <I>G_define_option()</I> and
-<I>G_define_flag().</I>
+Flags and options are presented by the usage message in the order that
+the programmer defines them using calls to G_define_option()
+and G_define_flag().
-<P>
-"How does a programmer query for coordinates?"
+ - "How does a programmer query for coordinates?"
-<P>
-For any user input that requires a set of arguments (like a pair of map
-coordinates,) the programmer specifies the number of arguments in the
-key_desc member of the Option structure. For example, if opt->key_desc was
-set to "x,y", the parser will require that the user enter a pair of
-arguments separated only by a comma. See the source code for the GRASS
-commands r.drain or r.cost for examples.
+For any user input that requires a set of arguments (like a pair of
+map coordinates,) the programmer specifies the number of arguments in
+the key_desc member of the Option structure. For example, if
+opt->key_desc was set to "x,y", the parser will require that the
+user enter a pair of arguments separated only by a comma. See the
+source code for the GRASS commands <tt>r.drain</tt> or <tt>r.cost</tt>
+for examples.
-<P>
-"Is a user required to use full option names?"
+ - "Is a user required to use full option names?"
-<P>
-No! Users are required to type in only as many characters of an option name
+No. Users are required to type in only as many characters of an option name
as is necessary to make the option choice unambiguous. If, for example,
there are two options, "input=" and "output=", the following would be
valid command line arguments:
-<P>
+\verbatim
# command i=map1 o=map2
-<P>
# command in=map1 out=map2
+\endverbatim
-<P>
-"Are options standardized at all?"
+ - "Are options standardized at all?"
-<P>
Yes. There are a few conventions. Options which identify a single input map
are usually "map=", not "raster=" or "vector=". In the case of an
input and output map the convention is: "input=xx output=yy". By passing
@@ -2707,153 +2039,92 @@
user to remember (or guess correctly) what the command line syntax is for a
given command.
-<P>
-
-
\section String_Manipulation_Functions String Manipulation Functions
-<P>
+
This section describes some routines which perform string manipulation.
Strings have the usual C meaning: a NULL terminated array of characters.
-<P>
These next 3 routines remove unwanted white space from a single string.
-<P>
-char * G_squeeze() remove unnecessary white space
+ - G_squeeze()
-Leading and trailing white space is removed from the string <B>s</B>
-and internal white space which is more than one character is reduced
-to a single space character. White space here means spaces, tabs,
-linefeeds, newlines, and formfeeds. Returns <B>s.</B>
+Leading and trailing white space is removed from the string and
+internal white space which is more than one character is reduced to a
+single space character. White space here means spaces, tabs,
+linefeeds, newlines, and formfeeds.
-<P>
-void G_strip() remove leading/training white space
+ - G_strip()
-Leading and trailing white space is removed from the string <B>s.</B>
-White space here means only spaces and tabs. There is no return value.
+Leading and trailing white space is removed from the string. White
+space here means only spaces and tabs. There is no return value.
-<P>
-char * G_chop() Chop leading and trailing white spaces:
- space, \f, \n, \r, \t, \v - returns pointer to string
+ - G_chop()
-<P>
+Chop leading and trailing white spaces: space, \f, \n, \r,
+ \t, \v.
+
The next routines replaces character(s) from string.
-<P>
-char * G_strchg() replace character(s)
+ - G_strchg()
-Replace all occurencies of character in string bug with new. Returns
-changed string
+Replace all occurencies of character in string with new.
-<P>
This next routine copies a string to allocated memory.
-<P>
-char * G_store() copy string to allocated memory
+ - G_store()
-This routine allocates enough memory to hold the string <B>s</B>,
-copies <B>s</B> to the allocated memory, and returns a pointer to the
-allocated memory.
+This routine allocates enough memory to hold the string, and returns a
+pointer to the allocated memory.
-<P>
The next 2 routines convert between upper and lower case.
-<P>
-char * G_tolcase() convert string to lower case
+ - G_tolcase()
-Upper case letters in the string <B>s</B> are converted to their lower
-case equivalent. Returns <B>s.</B>
+Upper case letters in the string are converted to their lower case
+equivalent.
-<P>
-char * G_toucase() convert string to upper case
+ - G_toucase()
-Lower case letters in the string <B>s</B> are converted to their upper
-case equivalent. Returns <B>s.</B>
+Lower case letters in the string are converted to their upper case
+equivalent.
-<P>
-And finally a routine which gives a printable version of control characters.
+ - G_trim_decimal()
-<P>
-char * G_unctrl() printable version of control
- character
-
-This routine returns a pointer to a string which contains an
-English-like representation for the character <B>c.</B> This is useful
-for nonprinting characters, such as control characters. Control
-characters are represented by ctrl-C, e.g., control A is represented
-by ctrl-A. 0177 is represented by DEL/RUB. Normal characters remain
-unchanged.
-
-
-<P>
-This routine is useful in combination with <I>G_intr_char()</I> for printing
-the user's interrupt character:
-
-\verbatim
-char G_intr_char();
-char * G_unctrl();
-
-fprintf(stdout, "Your interrupt character is %s\n",
- G_unctrl(G_intr_char()));
-\endverbatim
-
-<P>
-<B>Note.</B> G_unctrl() uses a hidden static buffer which is
-overwritten from call to call.
-
-<P>
-<I>FOLLOWING new FUNCTIONS need to be merged into the flow of this text:</I>
-
-<P>
-int G_trim_decimal() trim
-
This routine remove trailing zeros from decimal number for example:
-23.45000 would come back as 23.45
+23.45000 would come back as 23.45.
-<P>
-char * G_index() delimiter
+ - G_index()
-Position of delimiter
+ - G_rindex()
+
+Get position of delimiter.
-<P>
-char * G_rindex () ??????
+ - G_strcasecmp()
-<P>
-int G_strcasecmp(char *a, char *b) string compare ignoring case (upper or lower)
- returns: -1 if a<b
-<br>
-0 if a==b
-<br>
-1 if a>b
+String compare ignoring case (upper or lower).
-<P>
-char * G_strstr() Return a pointer
- to the first occurrence of subString in mainString, or NULL if no occurrences
- are found
+ - G_strstr()
-<P>
-char * G_strdup() Return a pointer to a string that is a
-duplicate of the string given to G_strdup. The duplicate is created
-using malloc. If unable to allocate the required space, NULL is
-returned.
+Return a pointer to the first occurrence of subString in mainString,
+or NULL if no occurrences are found.
+ - G_strdup()
+Returns a pointer to a string that is a duplicate of the string given
+to G_strdup. The duplicate is created using malloc. If unable to
+allocate the required space, NULL is returned.
\section Enhanced_UNIX_Routines Enhanced UNIX Routines
-<P>
-A number of useful UNIX library routines have side effects which are
-sometimes undesirable. The routines here provide the same functions as their
-corresponding UNIX routine, but with different side effects.
+A number of useful UNIX library routines have side effects which are
+sometimes undesirable. The routines here provide the same functions as
+their corresponding UNIX routine, but with different side effects.
-<P>
-
\subsection Running in the Background Running in the Background
-<P>
The standard UNIX fork() routine creates a child process which is a
copy of the parent process. The fork() routine is useful for placing a
module into the background. For example, a module that gathers input
@@ -2863,12 +2134,11 @@
exit() allowing the child to continue in the background, and the user
could then do other processing.
-<P>
However, there is a subtle problem with this logic. The fork() routine does not
protect child processes from keyboard interrupts even if the parent is no longer
running. Keyboard interrupts will also kill background processes that do not
protect themselves.
-<br>
+
Note: Programmers who use /bin/sh know that programs run in the
background (using & on the command line) are not automatically
protected from keyboard interrupts. To protect a command that is run
@@ -2876,359 +2146,88 @@
who use the /bin/csh (or other variants) do not know, or forget that
the C-shell automatically protects background processes from keyboard
interrupts.
-<br>
Thus a module which puts itself in the background may never finish if
the user interrupts another module which is running at the keyboard.
-<P>
-The solution is to fork() but also put the child process in a process group
-which is different from the keyboard process group. G_fork() does this.
-
-<P>
-pid_t G_fork() create a protected child process
-
-This routine creates a child process by calling the UNIX fork()
-routine. It also changes the process group for the child so that
-interrupts from the keyboard do not reach the child. It does not cause
-the parent to exit().
-
-<P>
-G_fork() returns what fork() returns: -1 if fork() failed; otherwise 0
-to the child, and the process id of the new child to the parent.
-
-<P>
-<B>Note.</B> Interrupts are still active for the child. Interrupts
-sent using the <I>kill</I> command, for example, will interrupt the
-child. It is simply that keyboard-generated interrupts are not sent to
-the child.
-
-<P>
-
\subsection Partially_Interruptible_System_Call Partially Interruptible System Call
The UNIX system() call allows one program, the parent, to execute
another UNIX command or module as a child process, wait for that
process to complete, and then continue. The problem addressed here
-concerns interrupts. During the standard system() call, the child
+concerns interrupts. During the standard system() call, the child
process inherits its responses to interrupts from the parent. This
means that if the parent is ignoring interrupts, the child will ignore
them as well. If the parent is terminated by an interrupt, the child
will be also.
-<P>
-However, in some cases, this may not be the desired effect. In a menu
-environment where the parent activates menu choices by running commands
-using the system() call, it would be nice if the user could interrupt the
-command, but not terminate the menu module itself. The G_system() call
-allows this.
+However, in some cases, this may not be the desired effect. In a menu
+environment where the parent activates menu choices by running
+commands using the system() call, it would be nice if the user could
+interrupt the command, but not terminate the menu module itself. The
+G_system() call allows this.
-<P>
-int G_system() run a shell level command
+ - G_system()
-The shell level <B>command</B> is executed. Interrupt signals for the
-parent module are ignored during the call. Interrupt signals for the
-<B>command</B> are enabled. The interrupt signals for the parent are
+The shell level <em>command</em> is executed. Interrupt signals for
+the parent module are ignored during the call. Interrupt signals for
+the command are enabled. The interrupt signals for the parent are
restored to their previous settings upon return.
-<P>
G_system() returns the same value as system(), which is essentially
the exit status of the <B>command.</B> See UNIX manual system(1) for
details.
-<P>
\subsection ENDIAN_test ENDIAN test
-<P>
To test if the user's machine is little or big ENDIAN, the following
function is provided:
-<P>
-int G_is_little_endian() test little ENDIAN
+ - G_is_little_endian()
Test if machine is little or big endian.
-<P>
-Returns:
-
-<br>
-1 little endian
-<br>
-0 big endian
-
-
-<P>
-
-\subsection Unix_Socket_Functions Unix Socket Functions
-
-
-<P>
-The following provide a simplified interface for interprocess
-communication via Unix sockets. The caller need only be concerned
-with the path to the socket file and the various file descriptors for
-socket connections. The caller does not need to worry about handling
-socket structures - which, unlike internet sockets, have little
-utility once a file descriptor has been opened on a connection. All
-socket functions in the GIS library have a <B>G_sock()</B> prefix.
-One should keep in mind that unix sockets connections can both be read
-from and written to. Also, it is possible for calls to <B>read()</B>
-and <B>write()</B> to read or write fewer bytes than specified.
-Hence, looping calls may be required to read or write all of the data.
-The <B>read()</B> will still normally block if there is nothing to
-read, so a zero byte return value typically means the connection has
-been closed. The <B>write()</B> function typically returns
-immediately (see W. Richard Stevens. 1997. UNIX network programming:
-Volume 1, 2nd edition. Prentice Hall).
-
-<P>
-char * G_sock_get_fname() makes full socket path
-
-Takes a simple <B>name</B> for a communication channel and builds the
-full path for a sockets file with that <B>name</B>. The path as of
-this writing (2000-02-18) is located in the temporary directory for
-the user's current mapset (although this will likely change). A
-<B>NULL</B> pointer is returned if the function fails for some reason.
-The caller is responsible for freeing the memory of the returned
-string when it is no longer needed.
-
-<P>
-int G_sock_exists() does the socket exist
-
-Takes the full path to a unix socket; determines if the file exists;
-and if the file exists whether it is a socket file or not. Returns a
-non-zero value if the file exists and is a socket file. Otherwise it
-returns zero.
-
-<P>
-int G_sock_bind() binds the socket
-
-Takes the full path to a unix socket and attempts to bind a file
-descriptor to the path <B>name</B>. If successful it will return the
-file descriptor. Otherwise, it returns -1. The socket file must not
-already exist. If it does, this function will fail and set the global
-<B>errno</B> to <B>EADDRINUSE</B>. Other error numbers may be set if
-the call to <B>bind()</B> fails. Server programs wishing to bind a
-socket should test if the socket file they wish to use already exists.
-And, if so, they may try to connect to the socket to see if it is in
-use. If it is not in use, such programs may then call <B>unlink()</B>
-or <B>remove()</B> to delete the file before calling
-<B>G_sock_bind()</B>. It is important that server processes do not
-just delete existing socket files without testing the connection.
-Doing so may make another server process unreachable (i.e. you will
-have hijacked the other server's communication channel). Server
-processes must call <B>G_sock_bind()</B> prior to calling
-<B>G_sock_listen()</B> and <B>G_sock_accept()</B>.
-
-<P>
-int G_sock_listen() listen on a socket
-
-Takes the file descriptor returned by a successful call to
-<B>G_sock_bind()</B> and the length of the the listen queue. A
-successful call will return 0, while a failed call will return -1.
-The global <B>errno</B> will contain the error number corresponding to
-the reason for the failure. The queue length should never be zero.
-Some systems may interpret this to mean that no connections should be
-queued. Other systems may add a fudge factor to the queue length that
-the caller specifies. Servers that don't want additional connections
-queued should <B>close()</B> the listening file descriptor after a
-successful call to <B>G_sock_accept()</B>. This function is a simple
-wrapper around the system <B>listen()</B> function.
-
-<P>
-int G_sock_accept() accept a connection on the listening
-socket
-
-Takes the file descriptor returned by a successful call to
-<B>G_sock_bind()</B>, for which a successful call to
-<B>G_sock_listen()</B> has also been made, and waits for an incoming
-connection. When a connection arrives, the file descriptor for the
-connection is returned. This function normally blocks indefinitely.
-However, an interrupt like <B>SIGINT</B> may cause this function to
-return without a valid connection. In this case, the return value
-will be -1 and the global error number will be set to <B>EINTR</B>.
-Servers should handle this possibility by calling
-<B>G_sock_accept()</B> again. A typical server might have a call to
-<B>fork()</B> after a successful return from <B>G_sock_accept()</B>.
-A server might also use <B>select()</B> to see if an a connection is
-ready prior to calling <B>G_sock_accept()</B>. This function is a
-simple wrapper around the system's <B>accept()</B> function, with the
-second and third arguments being <B>NULL</B>.
-
-<P>
-int G_sock_connect() make a connection to a server process
-
-Takes the full path to a socket file and attempts to make a connection
-to a server listening for connections. If successful, the file
-descriptor for the socket connection is returned. Otherwise, -1 is
-returned and the global <B>errno</B> may be set. This function and
-<B>G_sock_get_fname()</B> are the only functions a client program
-really needs to worry about. If the caller wants to be sure that the
-global error number was set from an unsuccessful call to this
-function, she should zero <B>errno</B> prior to the call. Failures
-due to a non-existent socket file or a path name that exceeds system
-limits, will not change the global error number.
-
-\subsection Trivial_Socket_Server_Example Trivial Socket Server
-Example
-
-\verbatim
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <grass/gis.h>
-
-int main (int argc, char *argv[])
-{
- int listenfd, rwfd;
- char *path;
- pid_t pid;
-
- /* Path is built using server's name */
- if (NULL == (path = G_sock_get_fname (argv[0])))
- exit (EXIT_FAILURE);
-
- /* Make sure another instance isn't running */
- if (G_sock_exists (path))
- {
- if ((listenfd = G_sock_connect (path)) != -1)
- {
- close (listenfd);
- exit (EXIT_FAILURE);
- }
- remove (path);
- }
-
- /* Bind the socket */
- if ((listenfd = G_sock_bind (path)) < 0)
- exit (EXIT_FAILURE);
-
- /* Begin listening on the socket */
- if (G_sock_listen (listenfd, 1) != 0)
- exit (EXIT_FAILURE);
-
- /* Loop forever waiting for connections */
- for (;;)
- {
- if ((rwfd = G_sock_accept (listenfd)) < 0)
- {
- if (errno == EINTR)
- continue;
- }
- else
- exit (EXIT_FAILURE);
-
- /* Fork connection */
- if ((pid = fork()) == 0)
- {
- char c;
- /* child closes listenfd */
- close (listenfd);
- while (read (rwfd, &c, 1) > 0)
- write (rwfd, &c, 1);
- close (rwfd);
- return 0;
- }
- else if (pid > 0)
- {
- /* parent closes rwfd
- * a well behaved server would limit
- * the number of forks.
- */
- close (rwfd);
- }
- else
- exit (EXIT_FAILURE);
-
- }
- G_free (path);
- return 0;
-}
-\endverbatim
-
\subsection Miscellaneous Miscellaneous
-
-<P>
A number of general purpose routines have been provided.
-<P>
-char * G_date() current date and time
+ - G_date()
Returns a pointer to a string which is the current date and time. The
-format is the same as that produced by the UNIX <I>date</I> command.
+format is the same as that produced by the UNIX <tt>date</tt> command.
-<P>
-char * G_gets() get a line of input (detect ctrl-z)
+ - G_home()
-This routine does a <I>gets()</I> from stdin into <B>buf.</B> It exits
-if end-of-file is detected. If stdin is a tty (i.e., not a pipe or
-redirected) then ctrl-z is detected. Returns 1 if the read was
-successful, or 0 if ctrl-z was entered.
-
-<P>
-<B>Note.</B> This is very useful for allowing a module to reprompt when a
-module is restarted after being stopped with a ctrl-z. If this routine returns
-0, then the calling module should reprint a prompt and call <I>G_gets()</I>
-again. For example:
-
-\verbatim
-char buf[1024];
-
-do{
- fprintf(stdout, "Enter some input: ") ;
-} while ( ! G_gets(buf) ) ;
-\endverbatim
-
-
-<P>
-char * G_home() user's home directory
-
Returns a pointer to a string which is the full path name of the
user's home directory.
-<P>
-char G_intr_char() return interrupt char
+ - G_percent()
-This routine returns the user's keyboard interrupt character. This is
-the character that generates the SIGINT signal from the keyboard.
+This routine prints a percentage complete message to stderr. Example:
-<P>
-See also <I>G_unctr()</I> for converting this character to a printable format.
+\code
+#include<grass/gis.h>
+#include<grass/glocale.h>
-<P>
-int G_percent(int n, int total, int incr) print percent complete
- messages
-
-This routine prints a percentage complete message to stderr. The
-percentage complete is (<B>n</B>/ <B>total</B>)*100, and these are
-printed only for each <B>incr</B> percentage. This is perhaps best
-explained by example:
-
-\verbatim
-# include <stdio.h>
-
int row;
int nrows;
nrows = 1352; /* 1352 is not a special value - example only */
-fprintf (stderr, "Percent complete: ");
+G_message(_("Percent complete:"));
for (row = 0; row < nrows; row++)
- G_percent (row, nrows, 10);
+ G_percent(row, nrows, 10);
\endverbatim
+This will print completion messages at 10% increments; i.e., 10%, 20%,
+30%, etc., up to 100%. Each message does not appear on a new line, but
+rather erases the previous message. After 100%, a new line is printed.
-<P>
-This will print completion messages at 10% increments; i.e., 10%, 20%, 30%,
-etc., up to 100%. Each message does not appear on a new line, but rather erases
-the previous message. After 100%, a new line is printed.
+ - G_program_name() return module name
-<P>
-char * G_program_name() return module name
-
Routine returns the name of the module as set by the call to
<I>G_gisinit().</I>
Modified: grass/trunk/lib/gis/home.c
===================================================================
--- grass/trunk/lib/gis/home.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/home.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,34 +1,30 @@
-/*
- ****************************************************************
- * char *
- * G_home ()
+/*!
+ * \file gis/home.c
*
- * returns char pointer to home directory for user
- * dies if can't determine
+ * \brief GIS Library - Get user's home directory.
*
- * char *
- * G__home()
+ * (C) 2001-2009 by the GRASS Development Team
*
- * returns char pointer to home directory for user
- * NULL if can't determine
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- ***************************************************************/
+ * \author Original author CERL
+ */
+
#include <stdlib.h>
#include <string.h>
#include <grass/gis.h>
#include <grass/glocale.h>
-
/*!
- * \brief user's home directory
+ * \brief Get user's home directory
*
- * Returns a pointer to a string
- * which is the full path name of the user's home directory.
+ * Returns a pointer to a string which is the full path name of the
+ * user's home directory.
*
- * \param ~
- * \return char *
+ * \return pointer to string
+ * \return NULL on error
*/
-
const char *G_home(void)
{
const char *home = G__home();
@@ -36,10 +32,20 @@
if (home)
return home;
- G_fatal_error(_("unable to determine user's home directory"));
+ G_fatal_error(_("Unable to determine user's home directory"));
+
return NULL;
}
+/*!
+ * \brief Get user's home directory
+ *
+ * Returns a pointer to a string which is the full path name of the
+ * user's home directory.
+ *
+ * \return pointer to string
+ * \return NULL on error
+ */
const char *G__home(void)
{
static int initialized;
Modified: grass/trunk/lib/gis/location.c
===================================================================
--- grass/trunk/lib/gis/location.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/location.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,18 +1,18 @@
/*!
- \file location.c
+ \file gis/location.c
+
+ \brief GIS library - environment routines (location)
+
+ (C) 2001-2008 by the GRASS Development Team
+
+ This program is free software under the
+ GNU General Public License (>=v2).
+ Read the file COPYING that comes with GRASS
+ for details.
+
+ \author Original author CERL
+*/
- \brief GIS library - environment routines (location)
-
- (C) 2001-2008 by the GRASS Development Team
-
- This program is free software under the
- GNU General Public License (>=v2).
- Read the file COPYING that comes with GRASS
- for details.
-
- \author Original author CERL
- */
-
#include <stdio.h>
#include <string.h>
#include <unistd.h>
Modified: grass/trunk/lib/gis/mapset.c
===================================================================
--- grass/trunk/lib/gis/mapset.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/mapset.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,33 +1,34 @@
+/*!
+ \file gis/mapset.c
+
+ \brief GIS library - environment routines (mapset)
+
+ (C) 2001-2009 by the GRASS Development Team
+
+ This program is free software under the
+ GNU General Public License (>=v2).
+ Read the file COPYING that comes with GRASS
+ for details.
-/**********************************************************************
- *
- * char *
- * G_mapset()
- *
- * returns: pointer to string containing the one word mapset
- * name.
- * NULL if user does not have access to mapset.
- *
- **********************************************************************/
+ \author Original author CERL
+ */
#include <string.h>
#include <stdlib.h>
#include <grass/gis.h>
#include <grass/glocale.h>
-
/*!
- * \brief current mapset name
+ * \brief Get current mapset name
*
- * Returns the name of the
- * current mapset in the current location. This routine is often used when
- * accessing files in the current mapset. See Mapsets for an
- * explanation of mapsets.
+ * Returns the name of the current mapset in the current
+ * location. This routine is often used when accessing files in the
+ * current mapset. See Mapsets for an explanation of mapsets.
*
- * \param void
- * \return char *
+ * G_fatal_error() is called on error.
+ *
+ * \return pointer mapset name
*/
-
const char *G_mapset(void)
{
const char *m = G__mapset();
@@ -38,6 +39,12 @@
return m;
}
+/*!
+ * \brief Get current mapset name
+ *
+ * \return pointer mapset name
+ * \return NULL on error
+ */
const char *G__mapset(void)
{
return G__getenv("MAPSET");
Modified: grass/trunk/lib/gis/myname.c
===================================================================
--- grass/trunk/lib/gis/myname.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/myname.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,35 +1,31 @@
-
-/**
- * \file myname.c
+/*!
+ * \file gis/myname.c
*
* \brief GIS Library - Database name functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <string.h>
#include <grass/gis.h>
#include <grass/glocale.h>
-
-/**
+/*!
* \brief Returns location title.
*
- * Returns a one line title for the database location. This title is
- * read from the file MYNAME in the PERMANENT mapset. See also
- * Permanent_Mapset for a discussion of the PERMANENT mapset.<br>
+ * Returns a one line title for the database location. This title is
+ * read from the file MYNAME in the PERMANENT mapset. See also \ref
+ * Permanent_Mapset for a discussion of the PERMANENT mapset.
*
* <b>Note:</b> This name is the first line in the file
* $GISDBASE/$LOCATION_NAME/PERMANENT/MYNAME
*
- * \return Pointer to a string
+ * \return pointer to a string
*/
char *G_myname(void)
Modified: grass/trunk/lib/gis/nme_in_mps.c
===================================================================
--- grass/trunk/lib/gis/nme_in_mps.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/nme_in_mps.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,34 +1,37 @@
/*!
- \file nme_in_mps.c
+ \file gis/nme_in_mps.c
- \brief GIS Library - check map name
+ \brief GIS Library - check map name
- (C) 2001-2008 by the GRASS Development Team
+ (C) 2001-2009 by the GRASS Development Team
- This program is free software under the
- GNU General Public License (>=v2).
- Read the file COPYING that comes with GRASS
- for details.
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
- \author Original author CERL
- */
+ \author Original author CERL
+*/
#include <string.h>
#include <grass/gis.h>
/*!
- \brief Check if map name is fully qualified (map @ mapset)
+ \brief Check if map name is fully qualified (map @ mapset)
+
+ Returns a fully qualified name for the file <i>name</i> in
+ <i>mapset</i>. Currently this string is in the form
+ <i>name at mapset</i>, but the programmer should pretend not to know this
+ and always call this routine to get the fully qualified name.
- Note:
- - <b>name</b> is char array of size GNAME_MAX
- - <b>mapset</b> is char array of size GMAPSET_MAX
+ Note:
+ - <i>name</i> is char array of size GNAME_MAX
+ - <i>mapset</i> is char array of size GMAPSET_MAX
- \param fullname full map name
- \param[out] name map name
- \param[out] mapset mapset name
-
- \return 1 if input map name is fully qualified
- \return 0 if input map name is not fully qualified
+ \param fullname full map name
+ \param[out] name map name
+ \param[out] mapset mapset name
+
+ \return 1 if input map name is fully qualified
+ \return 0 if input map name is not fully qualified
*/
int G__name_is_fully_qualified(const char *fullname, char *name, char *mapset)
{
Modified: grass/trunk/lib/gis/open.c
===================================================================
--- grass/trunk/lib/gis/open.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/open.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,9 +1,9 @@
/*!
* \file gis/open.c
*
- * \brief GIS Library - open file functions
+ * \brief GIS Library - Open file functions
*
- * (C) 1999-2008 by the GRASS Development Team
+ * (C) 1999-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public
* License (>=v2). Read the file COPYING that comes with GRASS
Modified: grass/trunk/lib/gis/parser.c
===================================================================
--- grass/trunk/lib/gis/parser.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/parser.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,12 +1,12 @@
-
-/**
- * \file parser.c
+/*!
+ * \file gis/parser.c
*
* \brief GIS Library - Argument parsing functions.
*
* Parses the command line provided through argc and argv. Example:
* Assume the previous calls:
*
+ * \code
* opt1 = G_define_option() ;
* opt1->key = "map",
* opt1->type = TYPE_STRING,
@@ -29,28 +29,37 @@
* opt3->answer = "12345.67",
* opt3->options = "0-99999",
* opt3->description= "Number to test parser" ;
+ * \endcode
*
* G_parser() will respond to the following command lines as described:
*
+ * \verbatim
* command (No command line arguments)
+ * \endverbatim
* Parser enters interactive mode.
*
+ * \verbatim
* command map=map.name
+ * \endverbatim
* Parser will accept this line. Map will be set to "map.name", the
* 'a' and 'b' flags will remain off and the num option will be set
* to the default of 5.
*
+ * \verbatim
* command -ab map=map.name num=9
* command -a -b map=map.name num=9
* command -ab map.name num=9
* command map.name num=9 -ab
* command num=9 -a map=map.name -b
+ * \endverbatim
* These are all treated as acceptable and identical. Both flags are
* set to on, the map option is "map.name" and the num option is "9".
* Note that the "map=" may be omitted from the command line if it
* is part of the first option (flags do not count).
*
+ * \verbatim
* command num=12
+ * \endverbatim
* This command line is in error in two ways. The user will be told
* that the "map" option is required and also that the number 12 is
* out of range. The acceptable range (or list) will be printed.
@@ -60,10 +69,7 @@
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author Radim Blazek
- *
- * \date 2003-2009
- *
+ * \author Original author CERL
*/
#include <grass/config.h>
@@ -145,17 +151,15 @@
static void G_usage_html(void);
static void G_script(void);
-
-/**
+/*!
* \brief Disables the ability of the parser to operate interactively.
*
- * When a user calls a command with no arguments on the command line,
- * the parser will enter its own standardized interactive session in
- * which all flags and options are presented to the user for input. A
- * call to <i>G_disable_interactive()</i> disables the parser's
- * interactive prompting.
+ * When a user calls a command with no arguments on the command line,
+ * the parser will enter its own standardized interactive session in
+ * which all flags and options are presented to the user for input. A
+ * call to G_disable_interactive() disables the parser's interactive
+ * prompting.
*
- * \return always returns 0
*/
void G_disable_interactive(void)
@@ -163,20 +167,18 @@
st->no_interactive = 1;
}
-
-/**
+/*!
* \brief Initializes a Flag struct.
*
- * Allocates memory for the Flag structure and returns a pointer to this
- * memory (of <i>type struct Flag *</i>).<br>
+ * Allocates memory for the Flag structure and returns a pointer to
+ * this memory.
*
- * Flags are always represented by single letters. A user "turns them on"
- * at the command line using a minus sign followed by the character
- * representing the flag.
+ * Flags are always represented by single letters. A user "turns them
+ * on" at the command line using a minus sign followed by the
+ * character representing the flag.
*
- * \return Flag * Pointer to a Flag struct
+ * \return Pointer to a Flag struct
*/
-
struct Flag *G_define_flag(void)
{
struct Flag *flag;
@@ -216,23 +218,21 @@
return (flag);
}
-
-/**
+/*!
* \brief Initializes an Option struct.
*
* Allocates memory for the Option structure and returns a pointer to
- * this memory (of <i>type struct Option *</i>).<br>
+ * this memory.
*
* Options are provided by user on command line using the standard
- * format: <i>key=value</i>. Options identified as REQUIRED must be
- * specified by user on command line. The option string can either
- * specify a range of values (e.g. "10-100") or a list of acceptable
- * values (e.g. "red,orange,yellow"). Unless the option string is NULL,
- * user provided input will be evaluated agaist this string.
+ * format: <i>key=value</i>. Options identified as REQUIRED must be
+ * specified by user on command line. The option string can either
+ * specify a range of values (e.g. "10-100") or a list of acceptable
+ * values (e.g. "red,orange,yellow"). Unless the option string is
+ * NULL, user provided input will be evaluated agaist this string.
*
- * \return Option * Pointer to an Option struct
+ * \return pointer to an Option struct
*/
-
struct Option *G_define_option(void)
{
struct Option *opt;
@@ -286,14 +286,13 @@
return (opt);
}
-
-/**
+/*!
* \brief Create standardised Option structure.
*
- * This function will create a standardised Option structure
- * defined by parameter opt. A list of valid parameters can be found in gis.h.
- * It allocates memory for the Option structure and returns a pointer to
- * this memory (of <i>type struct Option *</i>).<br>
+ * This function will create a standardised Option structure defined
+ * by parameter opt. A list of valid parameters can be found in gis.h.
+ * It allocates memory for the Option structure and returns a pointer
+ * to this memory.
*
* If an invalid parameter was specified a empty Option structure will
* be returned (not NULL).
@@ -339,9 +338,9 @@
* - G_OPT_V_CAT
* - G_OPT_V_CATS
*
- * \param[in] opt Type of Option struct to create
+ * \param opt type of Option struct to create
*
- * \return Option * Pointer to an Option struct
+ * \return pointer to an Option struct
*/
struct Option *G_define_standard_option(int opt)
@@ -690,12 +689,11 @@
}
-/**
+/*!
* \brief Initializes a new module.
*
- * \return GModule * Pointer to a GModule struct
+ * \return pointer to a GModule struct
*/
-
struct GModule *G_define_module(void)
{
struct GModule *module;
@@ -711,43 +709,40 @@
return (module);
}
-/* The main parsing routine */
-
-/**
+/*!
* \brief Parse command line.
*
- * The command line parameters <b>argv</b> and the number of parameters
- * <b>argc</b> from the main() routine are passed directly to
- * <i>G_parser()</i>. <i>G_parser()</i> accepts the command line input
- * entered by the user, and parses this input according to the input
- * options and/or flags that were defined by the programmer.<br>
+ * The command line parameters <i>argv</i> and the number of
+ * parameters <i>argc</i> from the main() routine are passed directly
+ * to G_parser(). G_parser() accepts the command line input entered by
+ * the user, and parses this input according to the input options
+ * and/or flags that were defined by the programmer.
*
* <b>Note:</b> The only functions which can legitimately be called
- * before G_parser() are:<br>
- * <ul>
- * <li>G_gisinit()</li>
- * <li>G_no_gisinit()</li>
- * <li>G_define_module()</li>
- * <li>G_define_flag()</li>
- * <li>G_define_option()</li>
- * <li>G_define_standard_option()</li>
- * <li>G_disable_interactive()</li>
- * </ul>
+ * before G_parser() are:
+ *
+ * - G_gisinit()
+ * - G_no_gisinit()
+ * - G_define_module()
+ * - G_define_flag()
+ * - G_define_option()
+ * - G_define_standard_option()
+ * - G_disable_interactive()
*
- * The usual order a module calls functions is:<br>
- * <ul>
- * <li>G_gisinit()</li>
- * <li>G_define_module()</li>
- * <li>G_define_{flag,option}()</li>
- * <li>G_parser()</li>
- * </ul>
+ * The usual order a module calls functions is:
*
- * \param[in] argc number of arguments
- * \param[in] argv argument list
+ * # G_gisinit()
+ * # G_define_module()
+ * # G_define_flag()
+ * # G_define_option()
+ * # G_parser()
+ *
+ * \param argc number of arguments
+ * \param argv argument list
+ *
* \return 0 on success
- * \return -1 on error and calls <b>G_usage()</b>
+ * \return -1 on error and calls G_usage()
*/
-
int G_parser(int argc, char **argv)
{
int need_first_opt;
@@ -1025,29 +1020,26 @@
return 0;
}
-
-/**
+/*!
* \brief Command line help/usage message.
*
- * Calls to <i>G_usage()</i> allow the programmer to print the usage
+ * Calls to G_usage() allow the programmer to print the usage
* message at any time. This will explain the allowed and required
* command line input to the user. This description is given according
* to the programmer's definitions for options and flags. This function
* becomes useful when the user enters options and/or flags on the
* command line that are syntactically valid to the parser, but
- * functionally invalid for the command (e.g. an invalid file name.)<br>
- * For example, the parser logic doesn't directly support grouping
- * options. If two options be specified together or not at all, the
- * parser must be told that these options are not required and the
- * programmer must check that if one is specified the other must be as
- * well. If this additional check fails, then <i>G_parser()</i> will
- * succeed, but the programmer can then call <i>G_usage()</i> to print
- * the standard usage message and print additional information about how
- * the two options work together.
+ * functionally invalid for the command (e.g. an invalid file name.)
*
- * \return
+ * For example, the parser logic doesn't directly support grouping
+ * options. If two options be specified together or not at all, the
+ * parser must be told that these options are not required and the
+ * programmer must check that if one is specified the other must be as
+ * well. If this additional check fails, then G_parser() will succeed,
+ * but the programmer can then call G_usage() to print the standard
+ * usage message and print additional information about how the two
+ * options work together.
*/
-
void G_usage(void)
{
struct Option *opt;
@@ -1219,14 +1211,12 @@
}
}
-
-/**
+/*!
* \brief Formats text for XML.
*
* \param[in,out] fp file to write to
- * \param[in] str string to write
+ * \param str string to write
*/
-
static void print_escaped_for_xml(FILE * fp, const char *str)
{
for (; *str; str++) {
@@ -1247,7 +1237,7 @@
}
-/**
+/*!
* \brief Format text for HTML output
*/
#define do_escape(c,escaped) case c: fputs(escaped,f);break
@@ -1269,9 +1259,9 @@
#undef do_escape
-/**
- \brief Print module usage description in XML format.
-**/
+/*!
+ \brief Print module usage description in XML format.
+*/
static void G_usage_xml(void)
{
struct Option *opt;
@@ -1507,9 +1497,9 @@
fprintf(stdout, "</task>\n");
}
-/**
- \brief Print module usage description in HTML format.
-**/
+/*!
+ \brief Print module usage description in HTML format.
+*/
static void G_usage_html(void)
{
struct Option *opt;
@@ -1735,9 +1725,9 @@
fprintf(stdout, "</body>\n</html>\n");
}
-/**
- \brief Print a module parameter template to assist with creating shell script wrappers.
-**/
+/*!
+ \brief Print a module parameter template to assist with creating shell script wrappers.
+*/
static void G_script(void)
{
FILE *fp = stdout;
@@ -1852,9 +1842,9 @@
"fi\n" "\n" "# CODE GOES HERE\n" "\n");
}
-/**
- \brief Build wxPython GUI dialog
-**/
+/*!
+ \brief Build wxPython GUI dialog.
+*/
static void G_gui_wx(void)
{
char script[GPATH_MAX];
@@ -1869,13 +1859,13 @@
G_spawn(getenv("GRASS_PYTHON"), "menuform.py", script, st->pgm_name, NULL);
}
-/**
- \brief Invoke GUI dialog
+/*!
+ \brief Invoke GUI dialog
- Use G_gui_wx() to generate GUI dialog.
+ Use G_gui_wx() to generate GUI dialog.
- G_gui_wx() is called by default (if GRASS_GUI is not defined)
-**/
+ G_gui_wx() is called by default (if GRASS_GUI is not defined)
+*/
static void G_gui(void)
{
G_gui_wx();
@@ -2442,13 +2432,13 @@
*ptr2 = '\0';
}
-/**
+/*!
* \brief Creates command to run non-interactive.
*
* Creates a command-line that runs the current command completely
* non-interactive.
*
- * \return char * Pointer to a char string
+ * \return pointer to a char string
*/
char *G_recreate_command(void)
{
Modified: grass/trunk/lib/gis/plot.c
===================================================================
--- grass/trunk/lib/gis/plot.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/plot.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,5 +1,8 @@
-
-/*****************************************************************
+/*
+ * \file gis/plot.c
+ *
+ * \brief GIS Library - Plotting functions.
+ *
* Plot lines and filled polygons. Input space is database window.
* Output space and output functions are user defined.
* Converts input east,north lines and polygons to output x,y
@@ -12,7 +15,15 @@
*
* Note:
* Hopefully, cartographic style projection plotting will be added later.
- *******************************************************************/
+ *
+ * (C) 2001-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <stdlib.h>
#include <math.h>
#include <grass/gis.h>
@@ -54,57 +65,32 @@
static struct state *st = &state;
-/*!
- * \brief returns east larger than west
- *
- * If the region projection is
- * PROJECTION_LL, then this routine returns an equivalent <b>east</b> that is
- * larger, but no more than 360 degrees larger, than the coordinate for the
- * western edge of the region. Otherwise no adjustment is made and the original
- * <b>east</b> is returned.
- *
- * \param east
- * \param region
- * \return double
- */
+#define OK 0
+#define TOO_FEW_EDGES 2
+#define NO_MEMORY 1
+#define OUT_OF_SYNC -1
-/*
- * G_setup_plot (t, b, l, r, Move, Cont)
- * double t, b, l, r;
- * int (*Move)(), (*Cont)();
- *
- * initialize the plotting capability.
- * t,b,l,r: top, bottom, left, right of the output x,y coordinate space.
- * Move,Cont: subroutines that will draw lines in x,y space.
- * Move(x,y) move to x,y (no draw)
- * Cont(x,y) draw from previous position to x,y
- * Notes:
- * Cont() is responsible for clipping.
- * The t,b,l,r are only used to compute coordinate transformations.
- * The input space is assumed to be the current GRASS window.
- */
-
/*!
- * \brief initialize plotting routines
+ * \brief Initialize plotting routines
*
- * Initializes the plotting
- * capability. This routine must be called once before calling the
- * <b>G_plot_*(~)</b> routines described below.
- * The parameters <b>t, b, l, r</b> are the top, bottom, left, and right of the
- * output x,y coordinate space. They are not integers, but doubles to allow for
- * subpixel registration of the input and output coordinate spaces. The input
- * coordinate space is assumed to be the current GRASS region, and the routines
- * supports both planimetric and latitude- longitude coordinate systems.
+ * Initializes the plotting capability. This routine must be called
+ * once before calling the G_plot_*() routines described below. The
+ * parameters <i>t, b, l, r</i> are the top, bottom, left, and right
+ * of the output x,y coordinate space. They are not integers, but
+ * doubles to allow for subpixel registration of the input and output
+ * coordinate spaces. The input coordinate space is assumed to be the
+ * current GRASS region, and the routines supports both planimetric
+ * and latitude-longitude coordinate systems.
+
* <b>Move</b> and <b>Cont</b> are subroutines that will draw lines in x,y
* space. They will be called as follows:
- * Move(x, y) move to x,y (no draw)
- * Cont(x, y) draw from previous position
- * to x,y. Cont(~) is responsible for clipping
+ * - Move(x, y) move to x,y (no draw)
+ * - Cont(x, y) draw from previous position to x,y. Cont(~) is responsible for clipping
*
- * \param ~
- * \return
+ * \param t,b,l,r top, bottom, left, right
+ * \param move Move function
+ * \param Cont Cont function
*/
-
void G_setup_plot(double t, double b, double l, double r,
int (*Move) (int, int), int (*Cont) (int, int))
{
@@ -132,15 +118,14 @@
}
/*!
- * \brief set row_fill routine to row_solid_fill or row_dotted_fill
+ * \brief Set row_fill routine to row_solid_fill or row_dotted_fill
*
- * After calling this function, <b>G_plot_polygon()</b> and
- * <b>G_plot_area()</b> fill shapes with solid or dotted lines. If gap is
- * greater than zero, this value will be used for row_dotted_fill. Otherwise,
+ * After calling this function, G_plot_polygon() and G_plot_area()
+ * fill shapes with solid or dotted lines. If gap is greater than
+ * zero, this value will be used for row_dotted_fill. Otherwise,
* row_solid_fill is used.
*
- * \param int
- * \return
+ * \param gap
*/
void G_setup_fill(int gap)
{
@@ -160,36 +145,32 @@
/*!
- * \brief east,north to x,y
+ * \brief Converts east,north to x,y
*
- * The map coordinates <b>east,north</b> are converted
- * to pixel coordinates <b>x,y.</b>
+ * The map coordinates <i>east,north</i> are converted
+ * to pixel coordinates <i>x,y</i>.
*
- * \param east
- * \param north
- * \param x
- * \param y
- * \return
+ * \param east easting
+ * \param north nothing
+ * \param x x coordinate
+ * \param y y coordinate
*/
-
void G_plot_where_xy(double east, double north, int *x, int *y)
{
*x = ifloor(X(G_adjust_easting(east, &st->window)) + 0.5);
*y = ifloor(Y(north) + 0.5);
}
-
/*!
- * \brief x,y to east,north
+ * \brief Converts x,y to east,north
*
- * The pixel coordinates <b>x,y</b> are converted to map
- * coordinates <b>east,north.</b>
+ * The pixel coordinates <i>x,y</i> are converted to map
+ * coordinates <i>east,north</i>.
*
- * \param x
- * \param y
- * \param east
- * \param north
- * \return
+ * \param x x coordinate
+ * \param y y coordinate
+ * \param east easting
+ * \param north northing
*/
void G_plot_where_en(int x, int y, double *east, double *north)
@@ -198,6 +179,12 @@
*north = NORTH(y);
}
+/*!
+ \brief Plot point
+
+ \param east easting
+ \param north northing
+*/
void G_plot_point(double east, double north)
{
int x, y;
@@ -207,32 +194,31 @@
st->cont(x, y);
}
-/*
- * Line in map coordinates is plotted in output x,y coordinates
- * This routine handles global wrap-around for lat-long databses.
- *
- */
-
/*!
- * \brief plot line between latlon coordinates
+ * \brief Plot line between latlon coordinates (fastline)
*
- * A line from <b>east1,north1</b>
- * to <b>east2,north2</b> is plotted in output x,y coordinates (e.g. pixels for
- * graphics.) This routine handles global wrap-around for latitude-longitude
- * databases.
+ * A line from <i>east1,north1</i> to <i>east2,north2</i> is plotted
+ * in output x,y coordinates (e.g. pixels for graphics.) This routine
+ * handles global wrap-around for latitude-longitude databases.
*
- * \param east1
- * \param north1
- * \param east2
- * \param north2
- * \return
+ * \param east1, north1 first point (start line node)
+ * \param east2, north2 second point (end line node)
*/
-
void G_plot_line(double east1, double north1, double east2, double north2)
{
plot_line(east1, north1, east2, north2, fastline);
}
+/*!
+ * \brief Plot line between latlon coordinates (slowline)
+ *
+ * A line from <i>east1,north1</i> to <i>east2,north2</i> is plotted
+ * in output x,y coordinates (e.g. pixels for graphics.) This routine
+ * handles global wrap-around for latitude-longitude databases.
+ *
+ * \param east1, north1 first point (start line node)
+ * \param east2, north2 second point (end line node)
+ */
void G_plot_line2(double east1, double north1, double east2, double north2)
{
plot_line(east1, north1, east2, north2, slowline);
@@ -241,7 +227,6 @@
/* fastline converts double rows/cols to ints then plots
* this is ok for graphics, but not the best for vector to raster
*/
-
static void fastline(double x1, double y1, double x2, double y2)
{
st->move(ifloor(x1 + 0.5), ifloor(y1 + 0.5));
@@ -359,24 +344,6 @@
}
}
-/*
- * G_plot_polygon (x, y, n)
- *
- * double *x x coordinates of vertices
- * double *y y coordinates of vertices
- * int n number of verticies
- *
- * polygon fill from map coordinate space to plot x,y space.
- * for lat-lon, handles global wrap-around as well as polar polygons.
- *
- * returns 0 ok, 2 n<3, -1 weird internal error, 1 no memory
- */
-
-#define OK 0
-#define TOO_FEW_EDGES 2
-#define NO_MEMORY 1
-#define OUT_OF_SYNC -1
-
static double nearest(double e0, double e1)
{
while (e0 - e1 > 180)
@@ -389,17 +356,20 @@
/*!
- * \brief plot filled polygon with n vertices
+ * \brief Plot filled polygon with n vertices
*
- * The polygon, described by the <b>n</b> vertices
- * <b>east,north</b>, is plotted in the output x,y space as a filled polygon.
+ * The polygon, described by the <i>n</i> vertices
+ * <i>east,north</i>, is plotted in the output x,y space as a filled polygon.
*
- * \param east
- * \param north
- * \param n
- * \return int
+ * \param x coordinates of vertices
+ * \param y coordinates of vertices
+ * \param n number of verticies
+ *
+ * \return 0 on success
+ * \return 2 n < 3
+ * \return -1 weird internal error
+ * \return 1 no memory
*/
-
int G_plot_polygon(const double *x, const double *y, int n)
{
int i;
@@ -507,32 +477,24 @@
return OK;
}
-/*
- * G_plot_area (xs, ys, rpnts, rings)
- * double **xs; -- pointer to pointer for X's
- * double **ys; -- pointer to pointer for Y's
- * int *rpnts; -- array of ints w/ num points per ring
- * int rings; -- number of rings
- *
- * Essentially a copy of G_plot_polygon, with minor mods to
- * handle a set of polygons. return values are the same.
- */
-
/*!
- * \brief plot multiple polygons
+ * \brief Plot multiple polygons
*
- * Like G_plot_polygon, except it takes a set of polygons,
- * each with \textbf{npts[<i>i</i>]} vertices, where the number of polygons
- * is specified with the <b>rings</b> argument. It is especially useful for
+ * Like G_plot_polygon(), except it takes a set of polygons, each with
+ * npts[<i>i</i>] vertices, where the number of polygons is specified
+ * with the <i>rings</i> argument. It is especially useful for
* plotting vector areas with interior islands.
*
- * \param xs
- * \param ys
- * \param npts
- * \param rings
- * \return int
+ * \param xs pointer to pointer for X's
+ * \param ys pointer to pointer for Y's
+ * \param rpnts array of ints w/ num points per ring
+ * \param rings number of rings
+ *
+ * \return 0 on success
+ * \return 2 n < 3
+ * \return -1 weird internal error
+ * \return 1 no memory
*/
-
int G_plot_area(double *const *xs, double *const *ys, int *rpnts, int rings)
{
int i, j, n;
@@ -783,24 +745,17 @@
return i;
}
-/*
- * G_plot_fx(e1,e2)
- *
- * plot f(x) from x=e1 to x=e2
- */
-
-
/*!
- * \brief plot f(east1) to f(east2)
+ * \brief Plot f(east1) to f(east2)
*
- * The function <b>f(east)</b> is plotted from
- * <b>east1</b> to <b>east2.</b> The function <b>f(east)</b> must return
- * the map northing coordinate associated with east.
+ * The function <i>f(east)</i> is plotted from <i>east1</i> to
+ * <i>east2</i>. The function <i>f(east)</i> must return the map
+ * northing coordinate associated with east.
*
- * \param ~
- * \return int
+ * \param f plotting function
+ * \param east1 easting (first point)
+ * \param east2 easting (second point)
*/
-
void G_plot_fx(double (*f) (double), double east1, double east2)
{
double east, north, north1;
Modified: grass/trunk/lib/gis/pole_in_poly.c
===================================================================
--- grass/trunk/lib/gis/pole_in_poly.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/pole_in_poly.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,40 +1,37 @@
-#include <grass/gis.h>
+/*!
+ \file gis/pole_in_poly.c
-/**********************************************************
- * G_pole_in_polygon(x, y, n)
- * double *x, *y, n;
- *
- * For lat-lon coordinates, this routine determines if the polygon
- * defined by the n verticies x,y contain one of the poles
- *
- * returns
- * -1 if it contains the south pole,
- * 1 if it contains the north pole,
- * 0 no pole
- *
- * Note: don't use this routine if the projection isn't PROJECTION_LL
- * no check is made by this routine for valid projection
- ***********************************************************/
+ \brief GIS Library - Pole in polygon
+
+ (C) 2001-2009 by the GRASS Development Team
-static void mystats(double, double, double, double, double *, double *);
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+ \author CERL
+ */
+#include <grass/gis.h>
+
+static void mystats(double, double, double, double, double *, double *);
+
/*!
- * \brief pole in polygon
+ * \brief Check if pole is in polygon
*
* For latitude-longitude coordinates, this routine determines if the polygon
- * defined by the <b>n</b> coordinate vertices <b>x,y</b> contains one of the
+ * defined by the <i>n</i> coordinate vertices <i>x,y</i> contains one of the
* poles.
- * Returns -1 if it contains the south pole; 1 if it contains the north pole; 0
- * if it contains neither pole.
- * <b>Note.</b> Use this routine only if the projection is PROJECTION_LL.
*
- * \param x
- * \param y
- * \param n
- * \return int
+ * <b>Note:</b> Use this routine only if the projection is PROJECTION_LL.
+ *
+ * \param x array of x coordinates
+ * \param y array of y coordinates
+ * \param n number of coordinates
+ *
+ * \return -1 if it contains the south pole
+ * \return 1 if it contains the north pole
+ * \return 0 if it contains neither pole.
*/
-
int G_pole_in_polygon(const double *x, const double *y, int n)
{
int i;
Modified: grass/trunk/lib/gis/proj1.c
===================================================================
--- grass/trunk/lib/gis/proj1.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/proj1.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,16 +1,16 @@
/*!
- \file proj1.c
+ \file gis/proj1.c
+ *
+ * \brief GIS Library - Projection support
+ *
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
- \brief GIS Library - Get projection info
-
- (C) 1999-2009 by the GRASS Development Team
-
- This program is free software under the GNU General Public License
- (>=v2). Read the file COPYING that comes with GRASS for details.
-
- \author Original author CERL
-*/
-
#include <grass/gis.h>
/*!
@@ -18,7 +18,6 @@
This routine returns a code indicating the projection for the active region. The current
values are:
-
- PROJECTION_XY 0 - x,y (Raw imagery)
- PROJECTION_UTM 1 - UTM Universal Transverse Mercator
- PROJECTION_SP 2 - State Plane (in feet)
Modified: grass/trunk/lib/gis/proj2.c
===================================================================
--- grass/trunk/lib/gis/proj2.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/proj2.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,6 +1,26 @@
+/*!
+ \file gis/proj2.c
+
+ \brief GIS Library - Projection support
+
+ (C) 2001-2009 by the GRASS Development Team
+
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+
+ \author Original author CERL
+ */
+
#include <grass/gis.h>
#include <grass/glocale.h>
+/*!
+ \brief Get units code
+
+ \param n project code
+
+ \retun units code
+*/
int G__projection_units(int n)
{
switch (n) {
@@ -17,6 +37,14 @@
}
}
+/*!
+ \brief Get units name
+
+ \param unit units code
+ \param plural plural form
+
+ \return units name
+*/
const char *G__unit_name(int unit, int plural)
{
switch (unit) {
@@ -33,6 +61,13 @@
}
}
+/*!
+ \brief Get projection name
+
+ \param n projection code
+
+ \return projection name
+*/
const char *G__projection_name(int n)
{
switch (n) {
Modified: grass/trunk/lib/gis/proj3.c
===================================================================
--- grass/trunk/lib/gis/proj3.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/proj3.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,3 +1,16 @@
+/*!
+ \file gis/proj3.c
+
+ \brief GIS Library - Projection support
+
+ (C) 2001-2009 by the GRASS Development Team
+
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+
+ \author Original author CERL
+ */
+
#include <string.h>
#include <grass/gis.h>
#include <grass/glocale.h>
@@ -22,16 +35,16 @@
}
/*!
- * \brief database units
+ * \brief Get database units
*
- * Returns a
- * string describing the database grid units. It returns a plural form (eg. feet)
- * if <b>plural</b> is true. Otherwise it returns a singular form (eg. foot).
+ * Returns a string describing the database grid units. It returns a
+ * plural form (eg. feet) if <i>plural</i> is true. Otherwise it
+ * returns a singular form (eg. foot).
*
- * \param plural
- * \return char *
+ * \param plural plural form if true
+ *
+ * \return units name
*/
-
const char *G_database_unit_name(int plural)
{
int n;
@@ -54,16 +67,14 @@
/*!
- * \brief query cartographic projection
+ * \brief Query cartographic projection
*
* Returns a pointer to a string which is a printable name for
- * projection code <b>proj</b> (as returned by <i>G_projection</i>). Returns
- * NULL if <b>proj</b> is not a valid projection.
+ * projection code <i>proj</i> (as returned by G_projection). Returns
+ * NULL if <i>proj</i> is not a valid projection.
*
- * \param proj
- * \return char *
+ * \return projection name
*/
-
const char *G_database_projection_name(void)
{
int n;
@@ -84,18 +95,15 @@
return name;
}
-
/*!
- * \brief conversion to meters
+ * \brief Conversion to meters
*
* Returns a factor which converts the grid unit to meters (by
- * multiplication). If the database is not metric (eg. imagery) then 0.0 is
- * returned.
+ * multiplication). If the database is not metric (eg. imagery) then
+ * 0.0 is returned.
*
- * \param void
- * \return double
+ * \return value
*/
-
double G_database_units_to_meters_factor(void)
{
const char *unit;
@@ -130,26 +138,16 @@
return factor;
}
-/***********************************************************************
- * G_database_datum_name(void)
- *
- * return name of datum of current database
- *
- * returns pointer to valid name if ok
- * NULL otherwise
- ***********************************************************************/
-
-
/*!
- * \brief get datum name for database
+ * \brief Get datum name for database
*
- * Returns a pointer to the name of the map datum of the current database. If
- * there is no map datum explicitely associated with the acutal database, the
- * standard map datum WGS84 is returned, on error a NULL pointer is returned.
+ * Returns a pointer to the name of the map datum of the current
+ * database. If there is no map datum explicitely associated with the
+ * acutal database, the standard map datum WGS84 is returned, on error
+ * a NULL pointer is returned.
*
- * \return char *
+ * \return datum name
*/
-
const char *G_database_datum_name(void)
{
const char *name;
@@ -170,15 +168,12 @@
return NULL;
}
-/***********************************************************************
- * G_database_ellipse_name(void)
- *
- * return name of ellipsoid of current database
- *
- * returns pointer to valid name if ok
- * NULL otherwise
- ***********************************************************************/
-
+/*!
+ \brief Get ellipsoid name of current database
+
+ \return pointer to valid name if ok
+ \return NULL on error
+*/
const char *G_database_ellipse_name(void)
{
const char *name;
Modified: grass/trunk/lib/gis/put_window.c
===================================================================
--- grass/trunk/lib/gis/put_window.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/put_window.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,34 +1,35 @@
-/*
- **********************************************************************
- *
- * G_put_window (window)
- * write the current mapset window
- **********************************************************************
- *
- * G__put_window (window, dir, name)
- * write the window 'name' in 'mapset'
- * returns -1 error
- * 1 ok
- *********************************************************************/
+/*!
+ \file gis/put_window.c
+ \brief GIS Library - Modify window (i.e. GRASS region)
+
+ (C) 2001-2009 by the GRASS Development Team
+
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+
+ \author Original author CERL
+*/
+
#include <stdlib.h>
#include <grass/gis.h>
/*!
- * \brief write the database region
+ * \brief Write the database region
*
* Writes the database region file (WIND) in the user's current mapset
- * from <b>region.</b> Returns 1 if the region is written ok. Returns -1 if not
- * (no diagnostic message is printed).
- * <b>Warning.</b> Since this routine actually changes the database region, it
- * should only be called by modules which the user knows will change the region.
- * It is probably fair to say that under GRASS 3.0 only the <i>g.region</i>,
- * and <i>d.zoom</i> modules should call this routine.
+ * from region.
+
+ * <b>Warning:</b> Since this routine actually changes the database
+ * region, it should only be called by modules which the user knows
+ * will change the region. It is probably fair to say that only the
+ * <tt>g.region</tt>.
*
- * \param region
- * \return int
+ * \param[in,out] window pointer to Cell_head
+ *
+ * \return 1 on success
+ * \return -1 on error (no diagnostic message is printed)
*/
-
int G_put_window(const struct Cell_head *window)
{
char *wind = getenv("WIND_OVERRIDE");
@@ -37,6 +38,24 @@
: G__put_window(window, "", "WIND");
}
+/*!
+ * \brief Write the database region
+ *
+ * Writes the database region file (WIND) in the user's current mapset
+ * from region.
+
+ * <b>Warning:</b> Since this routine actually changes the database
+ * region, it should only be called by modules which the user knows
+ * will change the region. It is probably fair to say that only the
+ * <tt>g.region</tt>.
+ *
+ * \param[in,out] window pointer to Cell_head
+ * \param dir directory name
+ * \param name file name
+ *
+ * \return 1 on success
+ * \return -1 on error (no diagnostic message is printed)
+ */
int G__put_window(const struct Cell_head *window, const char *dir, const char *name)
{
FILE *fd;
Modified: grass/trunk/lib/gis/radii.c
===================================================================
--- grass/trunk/lib/gis/radii.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/radii.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,75 +1,82 @@
-/* TODO:
+/*!
+ \file gis/radii.c
- Suggestion: all "lon"s in the file "radii.c" should read as "lat"
+ \brief GIS Library - Calculating the Meridional Radius of Curvature
+
+ \todo Suggestion: all "lon"s in the file "radii.c" should read as "lat"
+
+ Comments:
+ on page http://www.mentorsoftwareinc.com/cc/gistips/TIPS0899.HTM
+ down where it says "Meridional Radius of Curvature" is the exact formula
+ out of "radii.c".
+ Quote: "essentially, the radius of curvature, at a specific latitude ...".
+
+ See also http://williams.best.vwh.net/ellipsoid/node1.html which has a nice
+ picture showning the parametric latitude and phi, the geodetic latitude.
+ On the next page,
+ http://williams.best.vwh.net/ellipsoid/node2.html, in equation 3, the
+ Meridional Radius of Curvature shows up.
+
+ So, it looks like you are calculating the Meridional Radius of Curvature
+ as a function of GEODETIC LATITUDE.
- Comments:
- on page http://www.mentorsoftwareinc.com/cc/gistips/TIPS0899.HTM
- down where it says "Meridional Radius of Curvature" is the exact formula
- out of "radii.c".
- Quote: "essentially, the radius of curvature, at a specific latitude ...".
-
- See also http://williams.best.vwh.net/ellipsoid/node1.html which has a nice
- picture showning the parametric latitude and phi, the geodetic latitude.
- On the next page,
- http://williams.best.vwh.net/ellipsoid/node2.html, in equation 3, the
- Meridional Radius of Curvature shows up.
-
- So, it looks like you are calculating the Meridional Radius of Curvature
- as a function of GEODETIC LATITUDE.
- */
-
-#include <math.h>
-#include <grass/gis.h>
-#include "pi.h"
-
-
-/****************************************************************
Various formulas for the ellipsoid.
Reference: Map Projections by Peter Richardus and Ron K. Alder
University of Illinois Library Call Number: 526.8 R39m
Parameters are:
- lon = longitude of the meridian
- a = ellipsoid semi-major axis
- e2 = ellipsoid eccentricity squared
+ - lon = longitude of the meridian
+ - a = ellipsoid semi-major axis
+ - e2 = ellipsoid eccentricity squared
meridional radius of curvature (p. 16)
+ \verbatim
2
a ( 1 - e )
M = ------------------
2 2 3/2
(1 - e sin lon)
-
+ \endverbatim
transverse radius of curvature (p. 16)
-
+ \verbatim
a
N = ------------------
2 2 1/2
(1 - e sin lon)
-
+ \endverbatim
radius of the tangent sphere onto which angles are mapped
conformally (p. 24)
-
+ \verbatim
R = sqrt ( N * M )
+ \endverbatim
+
+ (C) 2001-2009 by the GRASS Development Team
-***************************************************************************/
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+ \author CERL
+ */
+
+#include <math.h>
+#include <grass/gis.h>
+#include "pi.h"
+
/*!
- * \brief meridional radius of curvature
+ * \brief Meridional radius of curvature
*
- * Returns the meridional radius of
- * curvature at a given longitude:
+ * Returns the meridional radius of curvature at a given longitude:
+ *
\f$
\rho = \frac{a (1-e^2)}{(1-e^2\sin^2 lon)^{3/2}}
\f$
- *
*
- * \param lon
- * \param a
- * \param e2
- * \return double
+ * \param lon longitude
+ * \param a ellipsoid semi-major axis
+ * \param e2 ellipsoid eccentricity squared
+ *
+ * \return radius value
*/
-
double G_meridional_radius_of_curvature(double lon, double a, double e2)
{
double x;
@@ -81,24 +88,21 @@
return a * (1 - e2) / (x * sqrt(x));
}
-
-
/*!
- * \brief transverse radius of curvature
+ * \brief Transverse radius of curvature
*
- * Returns the transverse radius of
- * curvature at a given longitude:
+ * Returns the transverse radius of curvature at a given longitude:
+ *
\f$
\nu = \frac{a}{(1-e^2\sin^2 lon)^{1/2}}
\f$
*
+ * \param lon longitude
+ * \param a ellipsoid semi-major axis
+ * \param e2 ellipsoid eccentricity squared
*
- * \param lon
- * \param a
- * \param e2
- * \return double
+ * \return radius value
*/
-
double G_transverse_radius_of_curvature(double lon, double a, double e2)
{
double x;
@@ -110,23 +114,22 @@
return a / sqrt(x);
}
-
/*!
- * \brief radius of conformal tangent sphere
+ * \brief Radius of conformal tangent sphere
*
- * Returns the radius of the
- * conformal sphere tangent to ellipsoid at a given longitude:
+ * Returns the radius of the conformal sphere tangent to ellipsoid at
+ * a given longitude:
+ *
\f$
r = \frac{a (1-e^2)^{1/2}}{(1-e^2\sin^2 lon)}
\f$
*
+ * \param lon longitude
+ * \param a ellipsoid semi-major axis
+ * \param e2 ellipsoid eccentricity squared
*
- * \param lon
- * \param a
- * \param e2
- * \return double
+ * \return radius value
*/
-
double G_radius_of_conformal_tangent_sphere(double lon, double a, double e2)
{
double x;
Modified: grass/trunk/lib/gis/remove.c
===================================================================
--- grass/trunk/lib/gis/remove.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/remove.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
- * \file remove.c
+/*!
+ * \file gis/remove.c
*
* \brief GIS Library - File remove functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/config.h>
@@ -28,18 +25,19 @@
static int G__remove(int misc, const char *dir, const char *element,
const char *name);
-/**
+/*!
* \brief Remove a database file.
*
- * The file or directory <b>name</b> under the database <b>element</b> directory
- * in the current mapset is removed.<br>
+ * The file or directory <i>name</i> under the database <i>element</i>
+ * directory in the current mapset is removed.
*
- * <b>Note:</b> If <b>name</b> is a directory, everything within the
- * directory is removed as well.
+ * If <i>name</i> is a directory, everything within the directory is
+ * removed as well.
*
- * \param[in] element element name
- * \param[in] name file nane
- * \return 0 if <b>name</b> does not exist
+ * \param element element name
+ * \param name file name
+ *
+ * \return 0 if <i>name</i> does not exist
* \return 1 if successful
* \return -1 on error
*/
@@ -49,18 +47,19 @@
return G__remove(0, NULL, element, name);
}
-/**
+/*!
* \brief Remove a database misc file.
*
- * The file or directory <b>name</b> under the database <b>element</b> directory
- * in the current mapset is removed.<br>
+ * The file or directory <i>name</i> under the database <i>element</i>
+ * directory in the current mapset is removed.
*
- * <b>Note:</b> If <b>name</b> is a directory, everything within the
- * directory is removed as well.
+ * If <i>name</i> is a directory, everything within the directory is
+ * removed as well.
*
- * \param[in] element element name
- * \param[in] name file name
- * \return 0 if <b>name</b> does not exist
+ * \param element element name
+ * \param name file name
+ *
+ * \return 0 if <i>name</i> does not exist
* \return 1 if successful
* \return -1 on error
*/
Modified: grass/trunk/lib/gis/rename.c
===================================================================
--- grass/trunk/lib/gis/rename.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/rename.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
- * \file rename.c
+/*!
+ * \file gis/rename.c
*
* \brief GIS Library - Rename file functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2006
+ * \author Original author CERL
*/
#include <stdio.h>
@@ -21,17 +18,17 @@
#include <grass/gis.h>
-/**
- **\brief Rename a file in the filesystem.
- **
- **The file or directory <b>oldname</b> is renamed to <b>newname</b>.<br>
- **
- ** \param[in] oldname
- ** \param[in] newname
- ** \return 0 if successful
- ** \return -1 on error
- **/
+/*!
+ \brief Rename a file in the filesystem.
+
+ The file or directory <i>oldname</i> is renamed to <i>newname</i>.
+ \param oldname current name
+ \param newname new name
+
+ \return 0 if successful
+ \return -1 on error
+*/
int G_rename_file(const char *oldname, const char *newname)
{
@@ -42,28 +39,28 @@
return rename(oldname, newname);
}
-/**
- * \brief Rename a database file.
- *
- * The file or directory <b>oldname</b> under the database <b>element</b>
- * directory in the current mapset is renamed to <b>newname</b>.<br>
- *
- * <b>Bug:</b> This routine does not check to see if the <b>newname</b>
- * name is a valid database file name.
- *
- * \param[in] element
- * \param[in] oldname
- * \param[in] newname
- * \return 0 if <b>oldname</b> does not exist
- * \return 1 if successful
- * \return -1 on error
- */
+/*!
+ \brief Rename a database file.
+ The file or directory <i>oldname</i> under the database <i>element</i>
+ directory in the current mapset is renamed to <i>newname</i>.
+
+ \bug This routine does not check to see if the <i>newname</i>
+ name is a valid database file name.
+
+ \param element element name
+ \param oldname current name
+ \param newname new name
+
+ \return 0 if <i>oldname</i> does not exist
+ \return 1 if successful
+ \return -1 on error
+*/
int G_rename(const char *element, const char *oldname, const char *newname)
{
const char *mapset;
char xname[GNAME_MAX], xmapset[GMAPSET_MAX];
- char from[512], to[512];
+ char from[GPATH_MAX], to[GPATH_MAX];
/* name in mapset legal only if mapset is current mapset */
mapset = G_mapset();
Modified: grass/trunk/lib/gis/set_window.c
===================================================================
--- grass/trunk/lib/gis/set_window.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/set_window.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,31 +1,27 @@
-
-/**
- * \file set_window.c
+/*!
+ * \file gis/set_window.c
*
- * \brief Set window
+ * \brief GIS Library - Set window (map region)
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2007
+ * \author Original author CERL
*/
#include <grass/gis.h>
#include <grass/glocale.h>
#include "G.h"
-/**
- * \brief Get the current working window.
+/*!
+ * \brief Get the current working window (region)
*
* The current working window values are returned in the structure
- * 'window'.
+ * <i>window</i>.
*
- * \param[out] window window structure to be set
- * \return
+ * \param[in,out] window window structure to be set
*/
void G_get_set_window(struct Cell_head *window)
{
@@ -34,12 +30,12 @@
}
-/**
+/*!
* \brief Establishes 'window' as the current working window.
*
* Any opened cell files has its file-to-window mapping reworked.
*
- * \param[in] window window to become operative window
+ * \param window window to become operative window
*
* \return -1 on error
* \return 1 on success
@@ -129,9 +125,8 @@
fcb->min_null_row = (-1) * NULL_ROWS_INMEM;
if(fcb->null_cur_row > 0)
{
- G_warning(
- "Calling G_set_window() in the middle of writing map %s",
- fcb->name);
+ G_warning(_("Calling G_set_window() in the middle of writing map %s"),
+ fcb->name);
fcb->null_cur_row = 0;
}
#endif
Modified: grass/trunk/lib/gis/short_way.c
===================================================================
--- grass/trunk/lib/gis/short_way.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/short_way.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,33 +1,28 @@
-
-/**
- * \file short_way.c
+/*!
+ * \file gis/short_way.c
*
* \brief GIS Library - Shortest path functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
-
-/**
+/*!
* \brief Shortest way between two eastings.
*
- * For lat-lon projection (<i>PROJECTION_LL</i>), <b>east1</b>,
- * <b>east2</b> are changed so that they are no more than 180 degrees
+ * For lat-lon projection (<tt>PROJECTION_LL</tt>), <i>east1</i>,
+ * <i>east2</i> are changed so that they are no more than 180 degrees
* apart. Their true locations are not changed. For all other
* projections, this function does nothing.
*
- * \param[in] east1 east (x) coordinate of first point
- * \param[in] east2 east (x) coordinate of second point
- * \return
+ * \param[in,out] east1 east (x) coordinate of first point
+ * \param[in,out] east2 east (x) coordinate of second point
*/
void G_shortest_way(double *east1, double *east2)
Modified: grass/trunk/lib/gis/strings.c
===================================================================
--- grass/trunk/lib/gis/strings.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/strings.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -65,7 +65,7 @@
return 0;
}
-/**
+/*!
* \brief Copy string to allocated memory.
*
* This routine allocates enough memory to hold the string <b>s</b>,
@@ -323,7 +323,7 @@
return count;
}
-/**
+/*!
* \brief Remove superfluous white space.
*
* Leading and trailing white space is removed from the string
Modified: grass/trunk/lib/gis/system.c
===================================================================
--- grass/trunk/lib/gis/system.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/system.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
- * \file system.c
+/*!
+ * \file gis/system.c
*
* \brief GIS Library - Command execution functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/config.h>
@@ -27,7 +24,7 @@
#include <grass/glocale.h>
-/**
+/*!
* \brief Run a shell level command.
*
* This is essentially the UNIX <i>system()</i> call, except for the
@@ -43,11 +40,11 @@
* parent and the command being run, set them yourself and use
* the UNIX <i>system()</i> call instead.
*
- * \param[in] command
+ * \param command
+ *
* \return -1 on error
* \return status on success
*/
-
int G_system(const char *command)
{
int status;
@@ -82,7 +79,7 @@
}
if (pid < 0) {
- G_warning(_("Can not create a new process!"));
+ G_warning(_("Unable to create a new process!"));
status = -1;
}
else {
Modified: grass/trunk/lib/gis/tempfile.c
===================================================================
--- grass/trunk/lib/gis/tempfile.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/tempfile.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
- * \file tempfile.c
+/*!
+ * \file gis/tempfile.c
*
* \brief GIS Library - Temporary file functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <string.h>
@@ -22,6 +19,9 @@
static struct Counter unique;
static int initialized;
+/*!
+ \brief Initialize environment for creating tempfiles.
+*/
void G_init_tempfile(void)
{
if (G_is_initialized(&initialized))
@@ -32,44 +32,42 @@
G_initialize_done(&initialized);
}
-/**
+/*!
* \brief Returns a temporary file name.
*
* This routine returns a pointer to a string containing a unique
* temporary file name that can be used as a temporary file within the
- * module. Successive calls to <i>G_tempfile()</i> will generate new
+ * module. Successive calls to G_tempfile() will generate new
* names. Only the file name is generated. The file itself is not
* created. To create the file, the module must use standard UNIX
* functions which create and open files, e.g., <i>creat()</i> or
- * <i>fopen()</i>.<br>
+ * <i>fopen()</i>.
*
* Successive calls will generate different names the names are of the
* form pid.n where pid is the programs process id number and n is a
- * unique identifier.<br>
+ * unique identifier.
*
* <b>Note:</b> It is recommended to <i>unlink()</i> (remove) the
* temp file on exit/error. Only if GRASS is left with 'exit', the GIS
- * mapset manangement will clean up the temp directory (ETC/clean_temp).
+ * mapset management will clean up the temp directory (ETC/clean_temp).
*
* \return pointer to a character string containing the name. The name
* is copied to allocated memory and may be released by the unix free()
* routine.
*/
-
char *G_tempfile(void)
{
return G__tempfile(getpid());
}
-/**
+/*!
* \brief Create tempfile from process id.
*
- * See <i>G_tempfile()</i>.
+ * See G_tempfile().
*
- * \param[in] pid
- * \return Pointer to string path
+ * \param pid
+ * \return pointer to string path
*/
-
char *G__tempfile(int pid)
{
char path[GPATH_MAX];
@@ -91,14 +89,11 @@
return G_store(path);
}
-
-/**
- * \brief Populates <b>element</b> with a path string.
+/*!
+ * \brief Populates element with a path string.
*
- * \param[in,out] element
- * \return
+ * \param[out] element element name
*/
-
void G__temp_element(char *element)
{
const char *machine;
Modified: grass/trunk/lib/gis/trim_dec.c
===================================================================
--- grass/trunk/lib/gis/trim_dec.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/trim_dec.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,31 +1,25 @@
-
-/**
+/*!
* \file trim_dec.c
*
* \brief GIS Library - Trim string decimal functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
-
-/**
+/*!
* \brief Removes trailing zeros from decimal number.
*
* Example: 23.45000 would come back as 23.45
*
* \param[in,out] buf
- * \return
*/
-
void G_trim_decimal(char *buf)
{
char *mark;
Modified: grass/trunk/lib/gis/wind_format.c
===================================================================
--- grass/trunk/lib/gis/wind_format.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/wind_format.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,38 +1,31 @@
-
-/**
- * \file wind_format.c
+/*!
+ * \file gis/wind_format.c
*
* \brief GIS Library - Window formatting functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <stdio.h>
#include <grass/gis.h>
-
static void format_double(double, char *);
-
-/**
+/*!
* \brief Northing to ASCII.
*
- * Converts the double representation of the <b>north</b> coordinate to
- * its ASCII representation (into <b>buf</b>).
+ * Converts the double representation of the <i>north</i> coordinate to
+ * its ASCII representation (into <i>buf</i>).
*
- * \param[in] north northing
- * \param[in,out] buf buffer to hold formatted string
- * \param[in] projection
- * \return
+ * \param north northing
+ * \param[out] buf buffer to hold formatted string
+ * \param projection projection code
*/
-
void G_format_northing(double north, char *buf, int projection)
{
if (projection == PROJECTION_LL)
@@ -41,19 +34,16 @@
format_double(north, buf);
}
-
-/**
+/*!
* \brief Easting to ASCII.
*
- * Converts the double representation of the <b>east</b> coordinate to
- * its ASCII representation (into <b>buf</b>).
+ * Converts the double representation of the <i>east</i> coordinate to
+ * its ASCII representation (into <i>buf</i>).
*
- * \param[in] east easting
- * \param[in,out] buf buffer to hold formatted string
- * \param[in] projection
- * \return
+ * \param east easting
+ * \param[out] buf buffer to hold formatted string
+ * \param projection projection code
*/
-
void G_format_easting(double east, char *buf, int projection)
{
if (projection == PROJECTION_LL)
@@ -62,19 +52,16 @@
format_double(east, buf);
}
-
-/**
+/*!
* \brief Resolution to ASCII.
*
- * Converts the double representation of the <b>resolution</b> to its
- * ASCII representation (into <b>buf</b>).
+ * Converts the double representation of the <i>resolution</i> to its
+ * ASCII representation (into <i>buf</i>).
*
- * \param[in] resolution
- * \param[in,out] buf buffer to hold formatted string
- * \param[in] projection
- * \return
+ * \param resolution resolution value
+ * \param[out] buf buffer to hold formatted string
+ * \param projection projection code
*/
-
void G_format_resolution(double res, char *buf, int projection)
{
if (projection == PROJECTION_LL)
Modified: grass/trunk/lib/gis/wind_scan.c
===================================================================
--- grass/trunk/lib/gis/wind_scan.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/wind_scan.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,39 +1,34 @@
-
-/**
- * \file wind_scan.c
+/*!
+ * \file gis/wind_scan.c
*
* \brief GIS Library - Window scanning functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <stdio.h>
#include <grass/gis.h>
-
static int scan_double(const char *, double *);
-
-/**
+/*!
* \brief ASCII northing to double.
*
- * Converts the ASCII "northing" coordinate string in <b>buf</b> to its
- * double representation (into <b>northing</b>).
+ * Converts the ASCII "northing" coordinate string in <i>buf</i> to its
+ * double representation (into <i>northing</i>).
*
- * \param[in] buf buffer hold string northing
- * \param[in,out] northing
- * \param[in] projection
+ * \param buf buffer hold string northing
+ * \param[out] northing northing
+ * \param projection projection code
+ *
* \return 0 on error
* \return 1 on success
*/
-
int G_scan_northing(const char *buf, double *northing, int projection)
{
if (projection == PROJECTION_LL) {
@@ -48,20 +43,19 @@
return scan_double(buf, northing);
}
-
-/**
+/*!
* \brief ASCII easting to double.
*
- * Converts the ASCII "easting" coordinate string in <b>buf</b> to its
- * double representation (into <b>easting</b>).
+ * Converts the ASCII "easting" coordinate string in <i>buf</i> to its
+ * double representation (into <i>easting</i>).
*
- * \param[in] buf buffer containing string easting
- * \param[in,out] easting
- * \param[in] projection
+ * \param buf buffer containing string easting
+ * \param[out] easting easting
+ * \param projection projection code
+ *
* \return 0 on error
* \return 1 on success
*/
-
int G_scan_easting(const char *buf, double *easting, int projection)
{
if (projection == PROJECTION_LL) {
@@ -80,20 +74,19 @@
return scan_double(buf, easting);
}
-
-/**
+/*!
* \brief ASCII resolution to double.
*
- * Converts the ASCII "resolution" string in <b>buf</b> to its double
+ * Converts the ASCII "resolution" string in <i>buf</i> to its double
* representation (into resolution).
*
- * \param[in] buf buffer containing string resolution
- * \param[in,out] resolution
- * \param[in] projection
+ * \param buf buffer containing string resolution
+ * \param[out] resolution resolution value
+ * \param projection projection code
+ *
* \return 0 on error
* \return 1 on success
*/
-
int G_scan_resolution(const char *buf, double *res, int projection)
{
if (projection == PROJECTION_LL) {
@@ -104,7 +97,6 @@
return (scan_double(buf, res) && *res > 0.0);
}
-
static int scan_double(const char *buf, double *value)
{
char junk[2];
Modified: grass/trunk/lib/gis/window_map.c
===================================================================
--- grass/trunk/lib/gis/window_map.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/window_map.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,17 +1,14 @@
-
-/**
+/*!
* \file window_map.c
*
* \brief GIS Library - Window mapping functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <stdlib.h>
@@ -22,17 +19,15 @@
#define alloc_index(n) (COLUMN_MAPPING *) G_malloc((n)*sizeof(COLUMN_MAPPING))
-/**
+/*!
* \brief Create window mapping.
*
* Creates mapping from cell header into window. The boundaries and
* resolution of the two spaces do not have to be the same or aligned in
* any way.
*
- * \param[in] fd file descriptor
- * \return
+ * \param fd file descriptor
*/
-
void G__create_window_mapping(int fd)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -112,16 +107,18 @@
}
-/**
+/*!
* \brief Northing to row.
*
- * Converts a <b>north</b>ing relative to a <b>window</b> to a row.<br>
+ * Converts a <i>north</i>ing relative to a <i>window</i> to a row.
+
* <b>Note:</b> The result is a double. Casting it to an integer will
* give the row number.
*
- * \param[in] north
- * \param[in] window
- * \return row id
+ * \param north northing value
+ * \param window pointer to Cell_head
+ *
+ * \return row number
*/
double G_northing_to_row(double north, const struct Cell_head *window)
@@ -130,20 +127,21 @@
}
-/**
+/*!
* \brief Adjust east longitude.
*
- * This routine returns an equivalent <b>east</b> that is
- * larger, but no more than 360 larger than the <b>west</b>
- * coordinate.<br>
- * <b>Note:</b> This routine should be used only with latitude-longitude
- * coordinates.
+ * This routine returns an equivalent <i>east</i> that is
+ * larger, but no more than 360 larger than the <i>west</i>
+ * coordinate.
+
+ * <b>Note:</b> This routine should be used only with
+ * latitude-longitude coordinates.
*
- * \param[in,out] east
- * \param[in] west
+ * \param east east coordinate
+ * \param west west coordinate
+ *
* \return east coordinate
*/
-
double G_adjust_east_longitude(double east, double west)
{
while (east > west + 360.0)
@@ -155,17 +153,18 @@
}
-/**
+/*!
* \brief Returns east larger than west.
*
- * If the region projection is <i>PROJECTION_LL</i>, then this routine
- * returns an equivalent <b>east</b> that is larger, but no more than
+ * If the region projection is <tt>PROJECTION_LL</tt>, then this routine
+ * returns an equivalent <i>east</i> that is larger, but no more than
* 360 degrees larger, than the coordinate for the western edge of the
* region. Otherwise no adjustment is made and the original
- * <b>east</b> is returned.
+ * <i>east</i> is returned.
*
- * \param[in,out] east
- * \param[in] window
+ * \param east east coordinate
+ * \param window pointer to Cell_head
+ *
* \return east coordinate
*/
@@ -180,17 +179,18 @@
return east;
}
-
-/**
+/*!
* \brief Easting to column.
*
- * Converts <b>east</b> relative to a <b>window</b> to a column.<br>
+ * Converts <i>east</i> relative to a <i>window</i> to a column.
+
* <b>Note:</b> The result is a <i>double</i>. Casting it to an
* <i>int</i> will give the column number.
*
- * \param[in] east
- * \param[in] window
- * \return column id
+ * \param east east coordinate
+ * \param window pointer to Cell_head
+ *
+ * \return column number
*/
double G_easting_to_col(double east, const struct Cell_head *window)
@@ -200,74 +200,72 @@
return (east - window->west) / window->ew_res;
}
-
-/**
+/*!
* \brief Row to northing.
*
- * Converts a <b>row</b> relative to a <b>window</b> to a
- * northing.<br>
+ * Converts a <i>row</i> relative to a <i>window</i> to a
+ * northing.
+
* <b>Note:</b> row is a double:
- * - row+0.0 will return the northing for the northern edge of the row.<br>
- * - row+0.5 will return the northing for the center of the row.<br>
- * - row+1.0 will return the northing for the southern edge of the row.<br>
- * <b>Note:</b> The result is a <i>double</i>. Casting it to an
+ * - row+0.0 will return the northing for the northern edge of the row.
+ * - row+0.5 will return the northing for the center of the row.
+ * - row+1.0 will return the northing for the southern edge of the row.
+ *
+ * <b>Note:</b> The result is a <i>double</i>. Casting it to an
* <i>int</i> will give the column number.
*
- * \param[in] row
- * \param[in] window
+ * \param row row number
+ * \param[in] window pointer to Cell_head
+ *
* \return north coordinate
*/
-
double G_row_to_northing(double row, const struct Cell_head *window)
{
return window->north - row * window->ns_res;
}
-
-/**
+/*!
* \brief Column to easting.
*
- * Converts a <b>col</b> relative to a <b>window</b> to an easting.<br>
- * <b>Note:</b> <b>col</b> is a <i>double</i>:<br>
- * - col+0.0 will return the easting for the western edge of the column.<br>
- * - col+0.5 will return the easting for the center of the column.<br>
- * - col+1.0 will return the easting for the eastern edge of the column.<br>
+ * Converts a <i>col</i> relative to a <i>window</i> to an easting.
*
- * \param[in] col
- * \param[in] window
+ * <b>Note:</b> <i>col</i> is a <i>double</i>:
+ * - col+0.0 will return the easting for the western edge of the column.
+ * - col+0.5 will return the easting for the center of the column.
+ * - col+1.0 will return the easting for the eastern edge of the column.
+ *
+ * \param col column number
+ * \param[in] window pointer to Cell_head
+ *
* \return east coordinate
*/
-
double G_col_to_easting(double col, const struct Cell_head *window)
{
return window->west + col * window->ew_res;
}
-
-/**
+/*!
* \brief Number of rows in active window.
*
* This routine returns the number of rows in the active module window.
* Before raster files can be read or written, it is necessary to
- * known how many rows are in the active window. For example:<br>
+ * known how many rows are in the active window. For example:
\code
- int nrows, cols;
- int row, col;
- nrows = G_window_rows( );
- ncols = G_window_cols( );
- for (row = 0; row < nrows; row++)
- {
- <i>read</i> row ...
- for (col = 0; col < ncols; col++)
- {
- process col ...
- }
- }
+int nrows, cols;
+int row, col;
+
+nrows = G_window_rows();
+ncols = G_window_cols();
+for (row = 0; row < nrows; row++) {
+ // read row ...
+ for (col = 0; col < ncols; col++) {
+ // process col ...
+ }
+}
\endcode
*
- * \return number of rows
+ * \return number of rows
*/
-
int G_window_rows(void)
{
G__init_window();
@@ -275,32 +273,30 @@
return G__.window.rows;
}
-
-/**
+/*!
* \brief Number of columns in active window.
*
- * These
- * routines return the number of rows and columns (respectively) in the active
- * module region. Before raster maps can be read or written, it is necessary to
- * known how many rows and columns are in the active region. For example:<br>
+ * These routines return the number of rows and columns (respectively)
+ * in the active module region. Before raster maps can be read or
+ * written, it is necessary to known how many rows and columns are in
+ * the active region. For example:
+ *
\code
- int nrows, cols;
- int row, col;
- nrows = G_window_rows( );
- ncols = G_window_cols( );
- for (row = 0; row < nrows; row++)
- {
- <i>read</i> row ...
- for (col = 0; col < ncols; col++)
- {
- process col ...
- }
- }
+int nrows, cols;
+int row, col;
+
+nrows = G_window_rows();
+ncols = G_window_cols();
+for (row = 0; row < nrows; row++) {
+ // read row ...
+ for (col = 0; col < ncols; col++) {
+ // process col ...
+ }
+}
\endcode
*
* \return number of columns
*/
-
int G_window_cols(void)
{
G__init_window();
@@ -308,13 +304,10 @@
return G__.window.cols;
}
-
-/**
+/*!
* \brief Initialize window.
*
- * \return
*/
-
void G__init_window(void)
{
if (G_is_initialized(&G__.window_set))
@@ -325,20 +318,19 @@
G_initialize_done(&G__.window_set);
}
-
-/**
+/*!
* \brief Loops rows until mismatch?.
*
- * This routine works fine if the mask is not set. It may give incorrect
- * results with a mask, since the mask row may have a different repeat
- * value. The issue can be fixed by doing it for the mask as well and
- * using the smaller value.
+ * This routine works fine if the mask is not set. It may give
+ * incorrect results with a mask, since the mask row may have a
+ * different repeat value. The issue can be fixed by doing it for the
+ * mask as well and using the smaller value.
*
- * \param[in] fd file descriptor
- * \param[in] row starting row
+ * \param fd file descriptor
+ * \param row starting row
+ *
* \return number of rows completed
*/
-
int G_row_repeat_nomask(int fd, int row)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
Modified: grass/trunk/lib/gis/zone.c
===================================================================
--- grass/trunk/lib/gis/zone.c 2009-06-05 14:18:25 UTC (rev 37743)
+++ grass/trunk/lib/gis/zone.c 2009-06-05 15:17:52 UTC (rev 37744)
@@ -1,25 +1,22 @@
-
-/**
- * \file zone.c
+/*!
+ * \file gis/zone.c
*
- * \brief Cartographic zone functions.
+ * \brief GIS Library - Cartographic zone functions.
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2006
+ * \author Original author CERL
*/
#include <grass/gis.h>
-/**
+/*!
* \brief Query cartographic zone.
*
- * This routine returns the zone for the active region. The meaning for
- * the zone depends on the projection. For example, zone 18 for
+ * This routine returns the zone for the active region. The meaning
+ * for the zone depends on the projection. For example, zone 18 for
* projection type 1 would be UTM zone 18.
*
* \return int cartographic zone
More information about the grass-commit
mailing list