vectorlib.dox: splitted to several pages (files), proper usage of subpage

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@52585 15284696-431f-4ddb-bdfa-cd5b030d7da7

grasslib.dox

@@ -108,10 +108,11 @@ href="http://grass.osgeo.org">http://grass.osgeo.org</a>
 
 \subsection vectoribs Vector Libraries
 
+ - %vector: \ref vectorlib
+  - dglib: \ref dglib
+  - vedit: \ref veditlib - %vector editing
+  - neta: \ref netalib
  - sites:	Old Sites library, now interfaced to \ref vectorlib - \ref sites
- - %vector:	\ref vectorlib (GRASS Vector and Direct Graph Library)
-  - vedit:      \ref veditlib - %vector editing
-  - neta:       \ref netalib
 
 \subsection dblibs Database Management Libraries
 

lib/vector/vectorlib_ascii.dox

@@ -0,0 +1,118 @@
+/*! \page vlibAscii Vector ASCII Format
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\section vlibAsciiMain Vector ASCII Format Specifications
+
+The GRASS ASCII vector map format may contain a mix of primitives
+including points, lines, boundaries, centroids, faces, and
+kernels. The format may also contain a header with various metadata
+(see example below).
+
+Vector map can be converted to the ASCII representation at user level
+by <tt>v.out.ascii format=standard</tt> command.
+
+See \ref vlibAsciiFn for list of related functions.
+
+The header is similar as the head file of vector binary format (see
+\ref vlibHeadFileFormat) but contains bounding box also. Keywords are:
+
+\verbatim
+ORGANIZATION
+DIGIT DATE
+DIGIT NAME
+MAP NAME
+MAP DATE
+MAP SCALE
+OTHER INFO
+ZONE
+WEST EDGE
+EAST EDGE
+SOUTH EDGE
+NORTH EDGE
+MAP THRESH
+\endverbatim
+
+Example:
+
+\verbatim
+ORGANIZATION: NC OneMap
+DIGIT DATE:   
+DIGIT NAME:   helena
+MAP NAME:     North Carolina selected bridges (points map)
+MAP DATE:     Mon Nov  6 15:32:39 2006
+MAP SCALE:    1
+OTHER INFO:   
+ZONE:         0
+MAP THRESH:   0.000000
+\endverbatim
+
+The body begins with the row:
+
+\verbatim
+VERTI:
+\endverbatim
+
+followed by records of primitives:
+
+\verbatim
+TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
+ X Y [Z]
+....
+ X Y [Z]
+[ LAYER CATEGORY]
+....
+[ LAYER CATEGORY]
+\endverbatim
+
+Everything above in <tt>[]</tt> is optional. 
+
+The primitive codes are as follows:
+
+- 'P': point
+- 'L': line
+- 'B': boundary
+- 'C': centroid
+- 'F': face (3D boundary)
+- 'K': kernel (3D centroid)
+- 'A': area (boundary) - better use 'B'; kept only for backward
+compatibility
+
+The coordinates are listed following the initial line containing the
+primitive code, the total number of vectors in the series, and (optionally)
+the number of categories (1 for a single layer, higher for multiple layers).
+Below that 1 or several lines follow to indicate the layer number and
+the category number (ID).
+
+The order of coordinates is
+\verbatim
+  X Y [Z]
+\endverbatim
+
+Note: The points are stored as y, x (i.e., east, north), which is the
+reserve of the way GRASS usually represents geographic coordinates.
+
+Example:
+
+\verbatim
+P  1 1
+ 375171.4992779 317756.72097616
+ 1     1 
+B  5
+ 637740       219580      
+ 639530       219580      
+ 639530       221230      
+ 637740       221230      
+ 637740       219580      
+C  1 1
+ 638635       220405      
+ 1     2
+\endverbatim
+
+In this example, the first vector feature is a point with category
+number 1. The second vector feature is a boundary composed by 5
+points. The third feature is a centroid with category number 2. The
+boundary and the centroid form an area with category number 2. All
+vector feature mentioned above are located in layer 1.
+
+*/

lib/vector/vectorlib_files.dox

@@ -0,0 +1,319 @@
+/*! \page vlibFormat Vector format description
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibDirectoryStructure
+- \ref vlibDblnFileFormat
+- \ref vlibCoorFileFormat
+ - \ref vlibCoorFileHead
+ - \ref vlibCoorFileBody
+
+\section vlibDirectoryStructure Directory structure
+
+Vector map is stored in a number of data files. Vector map directory
+structure and file names were changed in GRASS 6 with respect to
+previous GRASS versions. All vector files for one vector map are
+stored in one directory:
+
+\verbatim
+$MAPSET/vector/vector_name/
+\endverbatim
+
+This directory contains these files:
+
+- <b>coor</b> - binary file, coordinates [former dig/ file] (see \ref vlibCoorFileFormat)
+- <b>topo</b> - binary file, topology [former dig_plus/ file] (see \ref vlibTopoFileFormat)
+- <b>sidx</b> - binary file, spatial index (see \ref vlibSidxFileFormat)
+- <b>cidx</b> - binary file, category index (see \ref vlibCidxFileFormat)
+- <b>head</b> - text file, header information [former part of dig/ file] (see \ref vlibHeadFileFormat)
+- <b>dbln</b> - text file, link(s) to attribute table(s) (see \ref vlibDblnFileFormat)
+- <b>hist</b> - text file, vector map change history
+- <b>frmt</b> - text file, format description (external formats only)
+- <b>fidx</b> - binary file, feature index (OGR format only)
+
+\section vlibHeadFileFormat Header file format specification
+
+The header contains meta information, a description of the
+vector map and many other information. The file is an unordered list
+of key/value entries. The <i>key</i> is a string separated from
+<i>value</i> by a colon and optional whitespace.
+
+Keywords are:
+
+- ORGANIZATION - organization that digitized the data
+- DIGIT DATE - date the data was digitized
+- DIGIT NAME - person who digitized the data
+- MAP NAME - title of the original source map
+- MAP DATE - date of the original source map
+- MAP SCALE - scale of the original source map
+- OTHER INFO - other comments about the map
+- ZONE - zone of the map (e.g., UTM zone)
+- MAP THRESH - digitizing threshold
+
+This information holds \ref dig_head data structure.
+
+
+\section vlibDblnFileFormat DB link file format specification
+
+Each vector maps has its own DBMI settings stored in the
+'$MAPSET/vector/vector_name/dbln' text file. For each pair <em>vector map +
+layer</em>, all of <em>table, key column, database, driver</em> must be
+defined in a new row. This definition must be written to
+'$MAPSET/vector/vector_name/dbln' text file. Each row in the 'dbln'
+file contains names separated by spaces in following order ([ ] -
+optional):
+
+\verbatim
+map[@mapset] layer table [key [database [driver]]]
+\endverbatim
+
+If key, database or driver are omitted (on second and higher row only)
+the last definition is used. When reading a vector map from another
+mapset (if mapset is specified along with map name), definitions in
+the related "dbln" file may overwrite the DBMI definition in the
+current mapset. This means that the map-wise definition is always
+"stronger".
+
+Wild cards <b>*</b> and <b>?</b> may be used in map and mapset names.
+
+Variables $GISDBASE, $LOCATION_NAME, $MAPSET, and $MAP may be used in
+table, key, database and driver names (function
+Vect_subst_var()). Note that $MAPSET is not the current mapset but
+mapset of the map the rule is defined for.
+
+Note that vector features in GRASS vector maps may have attributes in
+different tables or may be without attributes. Boundaries form areas
+but it may happen that some boundaries are not closed (such boundaries
+would not appear in polygon layer).  Boundaries may have
+attributes. All types may be mixed in one vector map.
+
+The link to the table is permanent and it is stored in 'dbln' file in
+vector directory. Tables are considered to be a part of the vector and
+the command <tt>g.remove</tt>, for example, deletes linked tables of
+the vector. Attributes must be joined with geometry.
+
+Information about database links holds \ref dblinks data structure.
+
+<b>Examples:</b>
+
+Examples are written mostly for the DBF driver, where database is full
+path to the directory with dbf files and table name is the name of dbf
+file without .dbf extension:
+
+\verbatim
+* 1 mytable id $GISDBASE/$LOCATION_NAME/$MAPSET/vector/$MAP dbf
+\endverbatim
+
+This definition says that entities with category of layer 1 are linked
+to dbf tables with names "mytable.dbf" saved in vector directories of
+each map. The attribute column containing the category numbers is
+called "id".
+
+\verbatim
+* 1 $MAP id $GISDBASE/$LOCATION_NAME/$MAPSET/dbf dbf
+\endverbatim 
+
+Similar as above but all dbf files are in one directory dbf/ in mapset
+and names of dbf files are $MAP.dbf
+
+\verbatim
+water* 1 rivers id /home/grass/dbf dbf
+water* 2 lakes lakeid /home/guser/mydb
+trans* 1 roads key basedb odbc
+trans* 5 rails
+\endverbatim
+
+These definitions define more layers (called "field" in the API) for
+one vector map i.e. in one vector map may be more features linked to
+more attribute tables. Definitions on first 2 rows are applied for
+example on maps water1, water2, ... so that more maps may share one
+table.
+
+\verbatim
+water@PERMANENT 1 myrivers id /home/guser/mydbf dbf
+\endverbatim
+
+This definion overwrites the definition saved in PERMANENT/VAR and
+links the water map from PERMANENT mapset to the user's table.
+
+Modules should be written so that connections to databases for each
+vector layer are independent. It should be possible to read attributes
+of an input vector map from one database and write to some other and
+even with some other driver (should not be a problem).
+
+There are open questions, however. For one, how does one distinguish when
+new tables should be written and when not? For example, definitions:
+
+\verbatim
+river 1 river id water odbc
+river.backup* 1 NONE
+\endverbatim
+
+could be used to say that tables should not be copied for backups of
+map river because table is stored in a reliable RDBMS.
+
+\section vlibs Vector libraries
+
+Besides internal library functions there are two main libraries:
+
+- Vlib (Vector library), see \ref vlibIntro
+- DGLib (Directed Graph Library), see \ref vlibDglib
+
+For historical reasons, there are two internal libraries:
+
+- diglib (with dig_*() functions), GRASS 3.x/4.x
+- Vlib (with V1_*(), V2_*() and Vect_*() functions), since GRASS 4.x
+  (except for the 5.7 interim version)
+
+The vector library was introduced in GRASS 4.0 to hide internal vector
+files' formats and structures.  In GRASS 6/7, everything is accessed via
+Vect_*() functions, for example:
+
+Old 4.x code:
+
+\code
+    xx = Map.Att[Map.Area[area_num].att].x;
+\endcode
+
+New 6.x/7.x functions:
+
+\code
+    centroid = Vect_get_area_centroid(Map, area_num);
+    Vect_read_line(Map, line_p, NULL, centroid);
+    Vect_line_get_point(line_p, 0, &xx, NULL, NULL);
+\endcode
+
+In GRASS 6/7, all internal, mostly non-topological vector functions are
+hidden from the modules' API (mainly dig_*(), V1_*() and V2_*()
+functions). All available Vect_*() functions are topological vector
+functions.
+
+
+The following include file contains definitions and structures
+required by some of the routines in this library. The programmer
+should therefore include this file in any code that uses the vector
+library:
+
+\code
+#include <grass/vector.h>
+\endcode
+
+<i>Note: For details please read Blazek et al. 2002 (see below) as
+well as the references in this document.</i>
+
+\subsection vlibHistory Historical notes
+
+The vector library in GRASS 4.0 changed significantly from the
+<em>Digit Library</em> (diglib) used in GRASS 3.1. Below is an
+overview of why the changes were made.
+
+The Digit Library was a collage of subroutines created for developing
+the map development programs. Few of these subroutines were actually
+designed as a user access library. They required individuals to assume
+too much responsibility and control over what happened to the data
+file. Thus when it came time to change vector data file formats for
+GRASS 4.0, many modules also required modification. The two different
+access levels for 3.0 vector files provided very different ways of
+calling the library; they offered little consistency for the user.
+
+The Digit Library was originally designed to only have one file open
+for read or write at a time. Although it was possible in some cases to
+get around this, one restriction was the global head structure. Since
+there was only one instance of this, there could only be one copy of
+that information, and thus, only one open vector file.
+
+The solution to these problems was to design a new user library as an
+interface to the vector data files. This new library was designed to
+provide a simple consistent interface, which hides as much of the
+details of the data format as possible. It also could be extended for
+future enhancements without the need to change existing programs.
+
+The new vector library in GRASS 4 provided routines for opening,
+closing, reading, and writing vector files, as well as several support
+functions. The Digit Library has been replaced, so that all existing
+modules was converted to use the new library. Those routines that
+existed in the Digit Library and were not affected by these changes
+continue to exist in unmodified form, and were included in the vector
+library. Most of the commonly used routines have been discarded, and
+replaced by the new vector routines.
+
+Instead the global head structure was used own local version of
+it. The structure that replaced structure head is structure \ref
+dig_head. There were still two levels of interface to the vector files
+(future releases may include more). Level one provided access only to
+arc (i.e. polyline) information and to the type of line (AREA, LINE,
+DOT). Level two provided access to polygons (areas), attributes, and
+network topology.
+
+
+\subsection vlibCoorFileFormat Coor file format specification
+
+In the coor file the following is stored: 'line' (element) type,
+number of attributes and layer number for each category. Coordinates
+in binary file are stored as double (8 bytes). See \ref Coor_info data
+structure.
+
+\subsubsection vlibCoorFileHead Header
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+<tr><td>Version_Major</td> <td>C</td> <td>1</td> <td>file version (major)</td></tr>
+<tr><td>Version_Minor</td> <td>C</td> <td>1</td> <td>file version (minor)</td></tr>
+<tr><td>Back_Major</td>    <td>C</td> <td>1</td> <td>supported from GRASS version (major)</td></tr>
+<tr><td>Back_Minor</td>    <td>C</td> <td>1</td> <td>supported from GRASS version (minor)</td></tr>
+<tr><td>byte_order</td>    <td>C</td> <td>1</td> <td>little or big endian flag</td></tr>
+<tr><td>head_size</td>     <td>L</td> <td>1</td> <td>header size of coor file</td></tr>
+<tr><td>with_z</td>        <td>C</td> <td>1</td> <td>2D or 3D flag; zero for 2D</td></tr>
+<tr><td>size</td>          <td>L</td> <td>1</td> <td>coor file size</td></tr>
+</table>
+
+\section vlibCoorFileBody Body
+
+The body consists of line records:
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+<tr><td>record header</td><td>C</td><td>1</td><td>
+ - 0. bit: 1 - alive, 0 - dead line
+ - 1. bit: 1 - categories, 0 - no categories
+ - 2.-3. bit: type - one of: GV_POINT, GV_LINE, GV_BOUNDARY, GV_CENTROID, GV_FACE, GV_KERNEL
+ - 4.-7. bit: reserved, not used 
+</td></tr>
+
+<tr><td>ncats</td><td>I</td><td>1</td><td>number of categories 
+    (written only if categories exist) </td></tr>
+
+<tr><td>field</td><td>I</td><td>ncats</td><td>field identifier,
+    distinguishes between more categories append to one feature (written
+    only if categories exist; field is called "layer" at user
+    level)</td></tr>
+
+<tr><td>cat</td><td>I</td><td>ncats</td><td>category value (written
+    only if categories exist)</td></tr>
+
+<tr><td>ncoor</td><td>I</td><td>1</td><td>written for GV_LINES and GV_BOUNDARIES 
+    only</td></tr>
+
+<tr><td>x</td><td>D</td><td>ncoor</td><td>x coordinate</td></tr>
+
+<tr><td>y</td><td>D</td><td>ncoor</td><td>y coordinate</td></tr>
+
+<tr><td>z</td><td>D</td><td>ncoor</td><td>z coordinate; present if
+    with_z in head is set to 1</td></tr> </table>
+
+Types used in coor file:
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Type</b></td><td><b>Name</b></td><td><b>Size in Bytes</b></td></tr>
+<tr><td>D</td><td>Double</td><td>8</td></tr>
+<tr><td>L</td><td>Long  </td><td>4</td></tr>
+<tr><td>I</td><td>Int   </td><td>4</td></tr>
+<tr><td>S</td><td>Short </td><td>4</td></tr>
+<tr><td>C</td><td>Char  </td><td>1</td></tr>
+</table>
+
+
+
+*/

lib/vector/vectorlib_libraries.dox

@@ -0,0 +1,106 @@
+/*! \page vlibs Vector libraries
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\tableofcontents
+
+\par Table of contents
+
+- \ref vlibsAboutIntro
+- \ref vlibsHistory
+
+\section vlibsAboutIntro Introduction
+
+Besides internal library functions there are two main libraries:
+
+- Vlib (Vector library), see \ref vlibIntro
+- DGLib (Directed Graph Library), see \ref dglib
+
+For historical reasons, there are two internal libraries:
+
+- diglib (with dig_*() functions), GRASS 3.x/4.x
+- Vlib (with V1_*(), V2_*() and Vect_*() functions), since GRASS 4.x
+  (except for the 5.7 interim version)
+
+The vector library was introduced in GRASS 4.0 to hide internal vector
+files' formats and structures.  In GRASS 6/7, everything is accessed via
+Vect_*() functions, for example:
+
+Old 4.x code:
+
+\code
+    xx = Map.Att[Map.Area[area_num].att].x;
+\endcode
+
+New 6.x/7.x functions:
+
+\code
+    centroid = Vect_get_area_centroid(Map, area_num);
+    Vect_read_line(Map, line_p, NULL, centroid);
+    Vect_line_get_point(line_p, 0, &xx, NULL, NULL);
+\endcode
+
+In GRASS 6/7, all internal, mostly non-topological vector functions are
+hidden from the modules' API (mainly dig_*(), V1_*() and V2_*()
+functions). All available Vect_*() functions are topological vector
+functions.
+
+
+The following include file contains definitions and structures
+required by some of the routines in this library. The programmer
+should therefore include this file in any code that uses the vector
+library:
+
+\code
+#include <grass/vector.h>
+\endcode
+
+<i>Note: For details please read Blazek et al. 2002 (see below) as
+well as the references in this document.</i>
+
+\section vlibsHistory Historical notes
+
+The vector library in GRASS 4.0 changed significantly from the
+<em>Digit Library</em> (diglib) used in GRASS 3.1. Below is an
+overview of why the changes were made.
+
+The Digit Library was a collage of subroutines created for developing
+the map development programs. Few of these subroutines were actually
+designed as a user access library. They required individuals to assume
+too much responsibility and control over what happened to the data
+file. Thus when it came time to change vector data file formats for
+GRASS 4.0, many modules also required modification. The two different
+access levels for 3.0 vector files provided very different ways of
+calling the library; they offered little consistency for the user.
+
+The Digit Library was originally designed to only have one file open
+for read or write at a time. Although it was possible in some cases to
+get around this, one restriction was the global head structure. Since
+there was only one instance of this, there could only be one copy of
+that information, and thus, only one open vector file.
+
+The solution to these problems was to design a new user library as an
+interface to the vector data files. This new library was designed to
+provide a simple consistent interface, which hides as much of the
+details of the data format as possible. It also could be extended for
+future enhancements without the need to change existing programs.
+
+The new vector library in GRASS 4 provided routines for opening,
+closing, reading, and writing vector files, as well as several support
+functions. The Digit Library has been replaced, so that all existing
+modules was converted to use the new library. Those routines that
+existed in the Digit Library and were not affected by these changes
+continue to exist in unmodified form, and were included in the vector
+library. Most of the commonly used routines have been discarded, and
+replaced by the new vector routines.
+
+Instead the global head structure was used own local version of
+it. The structure that replaced structure head is structure \ref
+dig_head. There were still two levels of interface to the vector files
+(future releases may include more). Level one provided access only to
+arc (i.e. polyline) information and to the type of line (AREA, LINE,
+DOT). Level two provided access to polygons (areas), attributes, and
+network topology.
+
+
+*/

lib/vector/vectorlib_ogr.dox

@@ -0,0 +1,74 @@
+/*! \page vlibOgr OGR interface
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibOgrIface
+ - \ref vlibFrmtFileFormat
+ - \ref vlibFidxFileFormat
+
+
+\section vlibOgrIface OGR interface
+
+\subsection vLibPseudoTopo Pseudo-topology
+
+Reduced topology: each boundary is attached to one area only,
+i.e. smoothing, simplification, removing small areas etc. will not
+work properly for adjacent areas or areas within areas.
+
+Full topology is only available for native GRASS vectors or can only
+be built after all polygons are converted to areas and cleaned as done
+by <tt>v.in.ogr</tt>.
+
+\subsection vlibFrmtFileFormat Frmt file format specification
+
+Frmt is a plain text file which contains basic information about
+external format of linked vector map. Each line contains key, value
+pairs separated by comma.
+
+OGR specific format is described by:
+
+ - FORMAT - ogr
+ - DSN - OGR datasource name
+ - LAYER - OGR layer name
+
+Example:
+
+\verbatim
+FORMAT: ogr
+DSN: /path/to/shapefiles
+LAYER: cities
+\endverbatim
+
+OGR layer can be linked via <tt>v.external</tt> command. When linking
+OGR layer pseudo-topology ('topo') is built including spatial index
+file ('sidx') and category index file ('cidx'). Additionally also
+feature index file (see \ref vlibFidxFileFormat) is created.
+
+\subsection vlibFidxFileFormat Fidx file format specification
+
+Note: <tt>finfo</tt> is an instance of \ref Format_info structure.
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+
+<tr><td>Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>byte_order</td><td>C</td><td>1</td><td>little or big endian
+                  flag; files are written in machine native order but
+                  files in both little and big endian order may be
+                  readl; zero for little endian</td></tr>
+
+<tr><td>length</td><td>L</td><td>1</td><td>header size</td></tr>
+
+<tr><td>fInfo.ogr.offset_num</td><td>I</td><td>1</td><td>number of records</td></tr>
+
+<tr><td>fInfo.ogr.offset</td><td>I</td><td>offset_num</td><td>offsets</td></tr>
+
+</table>
+
+*/

lib/vector/vectorlib_spatialindex.dox

@@ -0,0 +1,234 @@
+/*! \page vlibSpatialIndex Spatial index
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibSpidx
+ - \ref vlibSidxFileFormat
+- \ref vlibCidx
+ - \ref vlibCidxFileFormat
+  - \ref vlibCidxFileHead
+
+
+\section vlibSpidx Vector library spatial index management
+
+Spatial index (based on R*-tree) is created with topology, see \ref
+RTree data structure.
+
+Spatial index occupies a lot of memory but it is necessary for 
+topology building. Also, it takes some time to release the memory
+occupied by spatial index (see dig_spidx_free()). The spatial index can
+also be built in file to save memory by setting the environment variable
+GRASS_VECTOR_LOWMEM.
+
+The function building topology - Vect_build() - is usually called at
+the end of modules (before Vect_close()) so it is faster to call
+<tt>exit()</tt> and operating system releases all the memory much
+faster.  By default the memory is not released.
+
+It is possible to call Vect_set_release_support() before Vect_close()
+to enforce memory release, but it takes some time on large files.
+
+The spatial index is stored in file and not loaded for old vectors that
+are not updated, saving a lot of memory. Spatial queries are done in 
+file.
+
+Currently most of the modules do not release the memory occupied for
+spatial index and work like this (pseudocode):
+
+\code
+int main
+{
+     Vect_open_new();
+     /* writing new vector */
+
+     Vect_build();
+     Vect_close();  /* memory is not released */
+}
+\endcode
+
+In general it is possible to free the memory with Vect_set_release_support()
+such as:
+
+\code
+int main
+{
+     Vect_open_new();
+     /* writing new vector */
+
+     Vect_build();
+     Vect_set_release_support();
+     Vect_close();  /* memory is released */
+}
+\endcode
+
+but it takes a bit longer. 
+
+It makes sense to release the spatial index if it is used only at the beginning
+of a module or in permanently running programs like QGIS. Note that this
+applies only when creating a new vector or updating an old vector.
+For example:
+
+\code
+int main
+{
+     Vect_open_update();
+     /* select features using spatial index, e.g.  Vect_select_lines_by_box() */
+     Vect_set_release_support();
+     Vect_close();  /* memory is released */
+
+     /* do some processing which needs memory */
+}
+\endcode
+
+See also \ref spatial_index data structure.
+
+\subsection vlibSidxFileFormat Sidx file format specification
+
+Spatial index file ('sidx') is read by Vect_open_sidx().
+
+\subsubsection vlibSidxFileHead Header
+
+Note: <tt>plus</tt> is instance of \ref Plus_head structure.
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+
+<tr><td>plus->spidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>plus->spidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>plus->spidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>plus->spidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>plus->spidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
+                  flag; files are written in machine native order but
+                  files in both little and big endian order may be
+                  readl; zero for little endian</td></tr>
+
+<tr><td>plus->spidx_port.off_t_size</td><td>C</td><td>1</td><td>off_t size (LFS)</td></tr>
+
+<tr><td>plus->spidx_head_size</td><td>L</td><td>1</td><td>header size</td></tr>
+
+<tr><td>plus->spidx_with_z</td><td>C</td><td>1</td><td>2D/3D vector data</td></tr>
+
+<tr><td>ndims</td><td>C</td><td>1</td><td>Number of dimensions</td></tr>
+
+<tr><td>nsides</td><td>C</td><td>1</td><td>Number of sides</td></tr>
+
+<tr><td>nodesize</td><td>I</td><td>1</td><td>%Node size</td></tr>
+
+<tr><td>nodecard</td><td>I</td><td>1</td><td>%Node card (?)</td></tr>
+
+<tr><td>leafcard</td><td>I</td><td>1</td><td>Leaf card (?)</td></tr>
+
+<tr><td>min_node_fill</td><td>I</td><td>1</td><td>Minimum node fill (?)</td></tr>
+
+<tr><td>min_leaf_fill</td><td>I</td><td>1</td><td>Minimum leaf fill (?)</td></tr>
+
+<tr><td>plus->Node_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Node_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Node_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Node_spidx_offset</td><td>O</td><td>1</td><td>%Node offset</td></tr>
+
+<tr><td>plus->Line_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Line_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Line_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Line_spidx_offset</td><td>O</td><td>1</td><td>Line offset</td></tr>
+
+<tr><td>plus->Area_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Area_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Area_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Area_spidx_offset</td><td>O</td><td>1</td><td>Area offset</td></tr>
+
+<tr><td>plus->Isle_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
+
+<tr><td>plus->Isle_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
+
+<tr><td>plus->Isle_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
+
+<tr><td>plus->Isle_spidx_offset</td><td>O</td><td>1</td><td>Isle offset</td></tr>
+
+<tr><td>plus->Face_spidx_offset</td><td>O</td><td>1</td><td>Face offset</td></tr>
+
+<tr><td>plus->Volume_spidx_offset</td><td>O</td><td>1</td><td>Volume offset</td></tr>
+
+<tr><td>plus->Hole_spidx_offset</td><td>O</td><td>1</td><td>Hole offset</td></tr>
+
+<tr><td>plus->coor_size</td><td>O</td><td>1</td><td>Coor file size</td></tr>
+</table>
+
+\section vlibCidx Vector library category index management
+
+The category index (stored in the cidx file) improves the performance
+of all selections by cats/attributes (SQL, e.g. <tt>d.vect
+cats=27591</tt>, <tt>v.extract list=20000-21000</tt>). This avoids
+that all selections have to be made by looping through all vector
+lines.  Category index is also essential for simple feature
+representation of GRASS vectors.
+
+Category index is created for each field. In memory, it is stored in
+\ref Cat_index data structure.
+
+Category index is built with topology, but it is <b>not updated</b> if
+vector is edited on level 2.  Category index is stored in 'cidx' file,
+'cat' array is written/read by one call of dig__fwrite_port_I() or
+dig__fread_port_I().
+
+Stored values can be retrieved either by index in 'cat' array (if all
+features of given field are required) or by category value (one or few
+features), always by <tt>Vect_cidx_*()</tt> functions.
+
+To create category index, it will be necessary to rebuild topology for
+all existing vectors.  This is an opportunity to make (hopefully) last
+changes in 'topo', 'cidx' formats.
+
+\subsection vlibCidxFileFormat Cidx file format specification
+
+Category index file ('cidx') is read by Vect_cidx_open().
+
+\subsubsection vlibCidxFileHead Header
+
+Note: <tt>plus</tt> is instance of \ref Plus_head structure.
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+
+<tr><td>plus->cpidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>plus->cpidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>plus->cpidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>plus->cpidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>plus->cidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
+                  flag; files are written in machine native order but
+                  files in both little and big endian order may be
+                  readl; zero for little endian</td></tr>
+
+<tr><td>plus->cidx_head_size</td><td>L</td><td>1</td><td>cidx head size</td></tr>
+
+<tr><td>plus->n_cidx</td><td>I</td><td>1</td><td>number of fields</td></tr>
+
+<tr><td>field</td><td>I</td><td>n_cidx</td><td>field number</td></tr>
+
+<tr><td>n_cats</td><td>I</td><td>n_cidx</td><td>number of categories</td></tr>
+
+<tr><td>n_ucats</td><td>I</td><td>n_cidx</td><td>number of unique categories</td></tr>
+
+<tr><td>n_types</td><td>I</td><td>n_cidx</td><td>number of feature types</td></tr>
+
+<tr><td>rtype</td><td>I</td><td>n_cidx * n_types</td><td>Feature type</td></tr>
+
+<tr><td>type[t]</td><td>I</td><td>n_cidx * n_types</td><td>Number of items</td></tr>
+
+</table>
+
+
+*/

lib/vector/vectorlib_tin.dox

@@ -0,0 +1,13 @@
+/*! \page vlibTin Vector TINs
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+<em>This page needs to be enhanced.</em>
+
+\section vlibTinIntro Short introduction
+
+TINs are simply created as 2D/3D vector polygons consisting of 
+3 vertices. See Vect_tin_get_z().
+
+
+*/

lib/vector/vectorlib_topology.dox

@@ -0,0 +1,460 @@
+/*! \page vlibTopology Topology
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+\par Table of contents
+
+- \ref vlibTopoManagement
+ - \ref vlibTopoFileFormat
+  - \ref vlibTopoFileHead
+  - \ref vlibTopoFileBody
+ - \ref vlibTopoLevels
+ - \ref vlibTopoExamples
+ - \ref vlibTopoMemory
+
+
+
+\section vlibTopoManagement Vector library topology management
+
+Topology general characteristics:
+
+- geometry and attributes are stored separately
+   (don't read both if it is not necessary - usually it is not)
+- the format is topological (areas build from boundaries)
+- currently only 2D topology is supported
+
+Topology is written for native GRASS vector format; in case of
+linked OGR sources (see <tt>v.external</tt> module), only
+pseudo-topology (boundaries constructed from polygons) is written.
+
+The following rules apply to the vector data:
+
+- Boundaries should not cross each other (i.e., boundaries which would
+  cross must be split at their intersection to form distict boundaries).
+  On the contrary, lines can cross each other, e.g. bridges over rivers.
+- Lines and boundaries share nodes only if their endpoints are identical.
+  Lines or boundaries can be forced to share a common node by snapping
+  them together. This is particulary important since nodes
+  are not represented in the coor file, but only implicitly as
+  endpoints of lines and boundaries.
+- Common area boundaries should appear only once (i.e., should not be
+  double digitized).
+- Areas must be explicitly closed. This means that it must be possible
+  to complete each area by following one or more boundaries that are
+  connected by common nodes, and that such tracings result in closed
+  areas.
+- It is recommended that area features and linear features be placed
+  in separate layers. However if area features and linear features
+  must appear in one layer, common boundaries should be digitized only
+  once. For example, a boundary that is also a line (e.g., a road which
+  is also a field boundary), should be digitized as a boundary to 
+  complete the area(s), and a boundary which is functionally also a line
+  should be labeled as a line by a distinct category number.
+
+Vector map topology can be cleaned at user level by <tt>v.clean</tt>
+command.
+
+\subsection vlibTopoFileFormat Topo file format specification
+
+Topo file is read by Vect_open_topo().
+
+\subsubsection vlibTopoFileHead Header
+
+<i>Note:</i> <tt>plus</tt> is an instance of \ref Plus_head data structure.
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+
+<tr><td>plus->Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
+<tr><td>plus->Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
+<tr><td>plus->Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
+<tr><td>plus->Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
+
+<tr><td>plus->port->byte_order</td><td>C</td><td>1</td><td>little or big endian
+                  flag; files are written in machine native order but
+                  files in both little and big endian order may be
+                  readl; zero for little endian</td></tr>
+
+<tr><td>plus->head_size</td><td>L</td><td>1</td><td>header size</td></tr>
+
+<tr><td>plus->with_z</td><td>C</td><td>1</td><td>2D or 3D flag; zero for 2D</td></tr>
+
+<tr><td>plus->box</td><td>D</td><td>6</td><td>Bounding box coordinates (N,S,E,W,T,B)</td></tr>
+
+<tr><td>plus->n_nodes, plus->n_lines, etc.</td><td>I</td><td>7</td><td>Number of
+nodes, edges, lines, areas, isles, volumes and holes</td></tr>
+
+<tr><td>plus->n_plines, plus->n_llines, etc.</td><td>I</td><td>7</td><td>Number of
+points, lines, boundaries, centroids, faces and kernels</td></tr>
+
+<tr><td>plus->Node_offset, plus->Edge_offset,
+etc.</td><td>L</td><td>7</td><td>Offset value for nodes, edges, lines,
+areas, isles, volumes and holes</td></tr>
+
+<tr><td>plus->coor_size</td><td>L</td><td>1</td><td>File size</td></tr>
+</table>
+
+\subsubsection vlibTopoFileBody Body (nodes, lines, areas, isles)
+
+<b>Nodes</b>
+
+For each node (plus->n_nodes):
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+<tr><td>n_lines</td><td>I</td><td>1</td><td>Number of lines (0 for dead node)</td></tr>
+<tr><td>lines</td><td>I</td><td>n_lines</td><td>Line ids (negative id for line which ends at the node)</td></tr>
+<tr><td>angles</td><td>D</td><td>n_lines</td><td>Angle value</td></tr>
+<tr><td>n_edges</td><td>I</td><td>1</td><td>Reserved for edges (only for <tt>with_z</tt>)</td></tr>
+<tr><td>x,y</td><td>D</td><td>2</td><td>Coordinate pair (2D)</td></tr>
+<tr><td>z</td><td>D</td><td>1</td><td>Only for <tt>with_z</tt> (3D)</td></tr>
+</table>
+
+See \ref P_node data structure.
+
+<b>Lines</b>
+
+For each line (plus->n_lines):
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+<tr><td>feature type</td><td>C</td><td>1</td><td>0 for dead line</td></tr>
+<tr><td>offset</td><td>L</td><td>1</td><td>Line offset</td></tr>
+<tr><td>N1</td><td>I</td><td>1</td><td>Start node id (only if feature type is GV_LINE or GV_BOUNDARY)</td></tr>
+<tr><td>N2</td><td>I</td><td>1</td><td>End node id (only if feature type is GV_LINE or GV_BOUNDARY)</td></tr>
+<tr><td>left</td><td>I</td><td>1</td><td>Left area id for feature type GV_BOUNDARY / Area id for feature type GV_CENTROID</td></tr>
+<tr><td>right</td><td>I</td><td>1</td><td>Right area id (for feature type GV_BOUNDARY)</td></tr>
+<tr><td>vol</td><td>I</td><td>1</td><td>Reserved for kernel (volume number, for feature type GV_KERNEL)</td></tr>
+</table>
+
+See \ref P_line data structure.
+
+<b>Areas</b>
+
+For each area (plus->n_areas):
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+<tr><td>n_lines</td><td>I</td><td>1</td><td>number of boundaries</td></tr>
+<tr><td>lines</td><td>I</td><td>n_lines</td><td>Line ids forming exterior boundary (clockwise order, negative id for backward direction)</td></tr>
+<tr><td>n_isles</td><td>I</td><td>1</td><td>Number of isles</td></tr>
+<tr><td>isles</td><td>I</td><td>n_isles</td><td>Isle ids</td></tr>
+<tr><td>centroid</td><td>I</td><td>1</td><td>Centroid id</td></tr>
+</table>
+
+See \ref P_area data structure.
+
+<b>Isles</b>
+
+For each isle (plus->n_isle):
+
+<table border="1" style="border-collapse: collapse" cellpadding="5">
+<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
+<tr><td>n_lines</td><td>I</td><td>1</td><td>number of boundaries</td></tr>
+<tr><td>lines</td><td>I</td><td>n_lines</td><td>Line ids forming exterior boundary (counter-clockwise order, negative id for backward direction)</td></tr>
+<tr><td>area</td><td>I</td><td>1</td><td>Outer area id</td></tr>
+</table>
+
+See \ref P_isle data structure.
+
+\subsection vlibTopoLevels Topology levels
+
+The vector library defines more <i>topology levels</i> (only for level
+of access 2):
+
+- GV_BUILD_NONE
+- GV_BUILD_BASE
+- GV_BUILD_AREAS
+- GV_BUILD_ATTACH_ISLES
+- GV_BUILD_CENTROIDS
+- GV_BUILD_ALL
+
+<i>Note:</i> Only the geometry type GV_BOUNDARY is used to build
+areas. The geometry type GV_LINE cannot form an area.
+
+\subsection vlibTopoExamples Topology examples
+
+<b>Points</b>
+
+\verbatim
+One point (nodes: 0, lines: 1, areas: 0, isles: 0)
+
+    + N1/L1
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 1 (GV_POINT)
+\endverbatim
+
+<b>Lines</b>
+
+\verbatim
+One line (nodes: 2, lines: 1, areas: 0, isles: 0)
+
+
+   +----L1----+
+   N1         N2
+\endverbatim
+
+%Node N1 (see \ref P_node)
+
+\verbatim
+node = 1, n_lines = 1, xyz = 634624.746450, 223557.302231, 0.000000
+  line =   1, type = 2 (GV_LINE), angle = -0.436257
+\endverbatim
+
+%Node N2 (see \ref P_node)
+
+\verbatim
+node = 2, n_lines = 1, xyz = 638677.484787, 221667.849899, 0.000000
+  line =  -1, type = 2 (GV_LINE), angle = 2.705335
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 2 (GV_LINE), n1 = 1, n2 = 2
+\endverbatim
+
+<b>Areas without holes</b>
+
+\verbatim
+Two lines (nodes: 1, lines: 2, areas: 1, isles: 1)
+
+          +N1
+         /   \
+        /     \
+       /       \
+      /   +L2   \
+     /           \
+    -------L1------
+\endverbatim
+
+%Node N1 (see \ref P_node)
+
+\verbatim
+node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
+  line =   1, type = 4 (GV_BOUNDARY), angle = -2.245537
+  line =  -1, type = 4 (GV_BOUNDARY), angle = -0.842926
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 4 (GV_BOUNDARY), n1 = 1, n2 = 1, left = 1, right = -1
+\endverbatim
+
+Line L2 (see \ref P_line)
+
+\verbatim
+line = 2, type = 8 (GV_CENTROID), area = 1
+\endverbatim
+
+Area A1 (see \ref P_area)
+
+\verbatim
+area = 1, n_lines = 1, n_isles = 0 centroid = 2
+  line =  -1
+\endverbatim
+
+Isle I1 (see \ref P_isle)
+
+\verbatim
+isle = 1, n_lines = 1 area = 0
+  line =   1
+\endverbatim
+
+<b>Areas with holes</b>
+
+\verbatim
+Three lines (nodes: 2, lines: 3, areas: 2, isles: 2)
+
+             +N1
+            / \
+           /   \
+          /     \
+         /       \
+        /    +L2  \
+       /           \
+      /   +N2       \
+     /   /\          \
+    /   /  \          \
+   /   /    \          \
+  /    ---L3--          \
+ /                       \
+------------L1-------------
+\endverbatim
+
+%Node N1 (see \ref P_node)
+
+\verbatim
+node = 1, n_lines = 2, xyz = 635720.081136, 225063.387424, 0.000000
+  line =   1, type = 4 (GV_BOUNDARY), angle = -2.245537
+  line =  -1, type = 4 (GV_BOUNDARY), angle = -0.842926
+\endverbatim
+
+%Node N2 (see \ref P_node)
+
+\verbatim
+node = 2, n_lines = 2, xyz = 636788.032454, 223173.935091, 0.000000
+  line =   3, type = 4 (GV_BOUNDARY), angle = -2.245537
+  line =  -3, type = 4 (GV_BOUNDARY), angle = -0.866302
+\endverbatim
+
+Line L1 (see \ref P_line)
+
+\verbatim
+line = 1, type = 4 (GV_BOUNDARY), n1 = 1, n2 = 1, left = 1, right = -1
+\endverbatim
+
+Line L2 (see \ref P_line)
+
+\verbatim
+line = 2, type = 8 (GV_CENTROID), area = 1
+\endverbatim
+
+Line L3 (see \ref P_line)
+
+\verbatim
+line = 3, type = 4 (GV_BOUNDARY), n1 = 3, n2 = 3, left = 2, right = -2
+\endverbatim
+
+Area A1 (see \ref P_area)
+
+\verbatim
+area = 1, n_lines = 1, n_isles = 1 centroid = 2
+  line =  -1
+  isle =   2
+\endverbatim
+
+Area A2 (see \ref P_area)
+
+\verbatim
+area = 2, n_lines = 1, n_isles = 0 centroid = 0
+  line =  -3
+\endverbatim
+
+Isle I1 (see \ref P_isle)
+
+\verbatim
+isle = 1, n_lines = 1 area = 0
+  line =   1
+\endverbatim
+
+Isle I2 (see \ref P_isle)
+
+\verbatim
+isle = 2, n_lines = 1 area = 1
+  line =   3
+\endverbatim
+
+<b>Example 1</b>
+
+A polygon may be formed by many boundaries (several connected primitives).
+One boundary is shared by adjacent areas.
+
+\verbatim
++--1--+--5--+
+|     |     |
+2  A  4  B  6
+|     |     |
++--3--+--7--+
+
+1,2,3,4,5,6,7 = 7 boundaries (primitives)
+A,B = 2 areas
+A+B = 1 isle
+\endverbatim
+
+<b>Example 2</b>
+
+This is handled correctly in GRASS: A can be filled, B filled differently.
+
+\verbatim
++---------+
+|    A    |
++-----+   |
+|  B  |   |
++-----+   |
+|         |
++---------+
+
+A, B = 2 areas
+A+B  = 1 isle
+\endverbatim
+
+In GRASS, whenever an 'inner' ring touches the boundary of an outside
+area, even in one point, it is no longer an 'inner' ring (isle in
+GRASS topology), it is simply another area. A, B above can never be
+exported from GRASS as polygon A with inner ring B because there are
+only 2 areas A and B and one island formed by A and B together.
+
+<b>Example 3</b>
+
+This is handled correctly in GRASS: Areas A1, A2, and A3 can be filled differently.
+
+\verbatim
++---------------------+
+|  A1                 |
++   +------+------+   |
+|   |  A2  |  A3  |   |
++   +------+------+   |
+|          I1         |
++---------------------+
+
+A1,A2,A3 = 3 areas
+A1,A2+A3 = 2 isles
+\endverbatim
+
+In GRASS, whenever an 'inner' ring does not touch the boundary of an
+outside area, also not in one point, it is an 'inner' ring (isle). The
+areas A2 and A3 form a single isle I1 located within area A1. The size
+of isle I1 is substracted from the size of area A1 when calculating
+the size of area A1. Any centroids falling into isle I1 are excluded
+when searching for a centroid that can be attached to area A1. A1
+above can be exported from GRASS as polygon A1 with inner ring I1.
+
+<b>Example 4</b>
+
+<tt>v.in.ogr/v.clean</tt> can identify dangles and change the type
+from boundary to line (in TIGER data for example). Distinction
+between line and boundary isn't important only for dangles. Example:
+
+\verbatim
++-----+-----+
+|     .     |
+|     .     |
++.....+.....+
+|     .     |
+|  x  .     |
++-----+-----+
+
+----  road + boundary of one parcel => type boundary
+....  road => type line
+x     parcel centroid (identifies whole area)
+\endverbatim
+
+Because lines are not used to build areas, we have only one
+area/centroid, instead of 4 which would be necessary in TIGER.
+
+\subsection vlibTopoMemory Topology memory management
+
+Topology is generated for all kinds of vector types.  Memory is not
+released by default. The programmer can force the library to release
+the memory by using Vect_set_release_support(). But: The programmer
+cannot run Vect_set_release_support() in mid process because all
+vectors are needed in the spatial index, which is needed to build topology.
+
+Topology is also necessary for points in case of a vector network
+because the graph is built using topology information about lines
+and points.
+
+The topology structure does not only store the topology but also
+the 'line' bounding box and line offset in coor file (index).
+The existing spatial index is using line ID in 'topology' structure
+to identify lines in 'coor' file. Currently it is not possible to build
+spatial index without topology.
+
+
+*/