[mapserver-commits] r12949 - trunk/docs/en/mapfile

[svn at osgeo.org]

Author: havatv
Date: 2012-01-03 06:30:15 -0800 (Tue, 03 Jan 2012)
New Revision: 12949

Added:
   trunk/docs/en/mapfile/include.txt
Log:
updated filename

Added: trunk/docs/en/mapfile/include.txt
===================================================================
--- trunk/docs/en/mapfile/include.txt	                        (rev 0)
+++ trunk/docs/en/mapfile/include.txt	2012-01-03 14:30:15 UTC (rev 12949)
@@ -0,0 +1,101 @@
+.. index::
+   single: Include
+
+.. index::
+   pair: MAP; INCLUDE
+
+.. _include:
+
+*****************************************************************************
+ INCLUDE
+*****************************************************************************
+
+When this directive is encountered parsing switches to the included file
+immediately. As a result the included file can be comprised of any valid
+mapfile syntax. For example:
+
+.. code-block:: mapfile
+
+    INCLUDE 'myLayer.map'
+
+Performance does not seem to be seriously impacted with limited use, however
+in high performance instances you may want to use includes in a pre-processing
+step to build a production mapfile. The C pre-processor can also be used
+(albeit with a different syntax) and is far more powerful.
+
+Notes
+-----
+
+- Supported in versions 4.10 and higher.
+
+- The name of the file to be included **MUST be quoted** (single or
+  double quotes).
+
+- Includes may be nested, up to 5 deep.
+
+- File location can be given as a full path to the file, or (in MapServer >=
+  4.10.1) as a path relative to the mapfile.
+
+- Debugging can be problematic because: 
+
+  1) the file an error occurs in does not get output to the user
+
+  2) the line number counter is not reset for each file. Here is one possible
+     error that is thrown when the include file cannot be found:
+
+     ::
+
+          msyylex(): Unable to access file. Error opening included file "parks_include.map"
+
+Example
+-------
+
+.. code-block:: mapfile
+
+  MAP
+   NAME "include_mapfile"
+   EXTENT 0 0 500 500
+   SIZE 250 250
+
+   INCLUDE "test_include_symbols.map"
+   INCLUDE "test_include_layer.map"
+  END
+
+where test_include_symbols.map contains:
+
+.. code-block:: mapfile
+
+  SYMBOL
+     NAME 'square'
+     TYPE VECTOR
+     FILLED TRUE
+     POINTS 0 0 0 1 1 1 1 0 0 0 END
+  END
+
+and test_include_layer.map contains:
+
+.. code-block:: mapfile
+
+  LAYER
+    TYPE POINT
+    STATUS DEFAULT
+    FEATURE
+      POINTS 10 10 40 20 300 300 400 10 10 400 END
+    END
+    CLASS
+      NAME 'Church'
+      COLOR 0 0 0
+      SYMBOL 'square'
+      SIZE 7
+      STYLE
+        SYMBOL "square"
+        SIZE 5
+        COLOR 255 255 255
+      END
+      STYLE
+        SYMBOL "square"
+        SIZE 3
+        COLOR 0 0 255
+      END
+    END
+  END