Updated the expressions document on quoting of qoutes (#3706). Tried …

…to update on attribute binding in the expressions document and the class document (text parameter). Also some restructuring of the expression document and styling of the class document.

git-svn-id: http://svn.osgeo.org/mapserver/trunk@11858 7532c77e-422f-0410-93f4-f0b67bdd69e2

en/mapfile/class.txt

@@ -14,9 +14,10 @@ COLOR [r] [g] [b]
     pair: DEBUG; CLASS
 
 DEBUG [on|off]
-    Enables debugging of the class object. Verbose output is generated and sent 
-    to the standard error output (STDERR) or the MapServer logfile if one is 
-    set using the LOG parameter in the :ref:`WEB` object.  
+    Enables debugging of the class object. Verbose output is generated
+    and sent to the standard error output (STDERR) or the MapServer
+    logfile if one is set using the LOG parameter in the :ref:`WEB`
+    object.
 
     .. seealso::
 
@@ -26,49 +27,52 @@ DEBUG [on|off]
     pair: EXPRESSION; CLASS
 
 :ref:`EXPRESSION <expressions>` [string]
-    Four types of expressions are now supported to define class membership. 
-    String comparisons, regular expressions, simple logical expressions, and 
-    string functions. If no expression is given, then all features are said 
-    to belong to this class.
-
-    - String comparisons are case sensitive and are the fastest to evaluate. 
-      No special delimiters are necessary although string must be quoted if they 
-      contain special characters. (As a matter of good habit, it is recommended 
-      you quote all strings).
+    Four types of expressions are now supported to define class
+    membership.  String comparisons, regular expressions, simple
+    logical expressions, and string functions (see
+    :ref:`EXPRESSIONS`). If no expression is given, then all features
+    are said to belong to this class.
+
+    - String comparisons are case sensitive and are the fastest to
+      evaluate.  No special delimiters are necessary although string
+      must be quoted if they contain special characters. (As a matter
+      of good habit, it is recommended you quote all strings).
 
-    - Regular expressions function just like previous versions of MapServer. 
-      However, you must now delimit a regular expression using /regex/. No 
-      quotes should be used.
-
-    - Logical expressions allow you to build fairly complex tests based on one 
-      or more attributes and therefore are only available with shapefiles. 
-      Logical expressions are delimited by parentheses "(expression)". 
-      Attribute names are delimited by square brackets "[ATTRIBUTE]". These 
-      names are case sensitive and must match the items in the shapefile. 
-      For example: EXPRESSION ([POPULATION] > 50000 AND '[LANGUAGE]' eq 
-      'FRENCH') ... The following logical operators are supported: 
-      =,>,<,<=,>=,=,or,and,lt,gt,ge,le,eq,ne. As you might expect this level 
-      of complexity is slower to process.
-
-    - One string function exists: length(). This obviously computes the length 
-      of a string. An example follows:
+    - Regular expressions function just like previous versions of
+      MapServer.  However, you must now delimit a regular expression
+      using /regex/. No quotes should be used.
+
+    - Logical expressions allow you to build fairly complex tests
+      based on one or more attributes and therefore are only available
+      with shapefiles.  Logical expressions are delimited by
+      parentheses "(expression)".  Attribute names are delimited by
+      square brackets "[ATTRIBUTE]". These names are case sensitive
+      and must match the items in the shapefile.  For example:
+      EXPRESSION ([POPULATION] > 50000 AND '[LANGUAGE]' eq 'FRENCH')
+      ... The following logical operators are supported:
+      =,>,<,<=,>=,=,or,and,lt,gt,ge,le,eq,ne. As you might expect this
+      level of complexity is slower to process.
+
+    - One string function exists: length(). This obviously computes
+      the length of a string. An example follows:
 
       ::
 
          EXPRESSION (length('[NAME_E]') < 8)                      
 
-      String comparisons and regular expressions work from the classitem defined 
-      at the layer level. You may mix expression types within the different 
-      classes of a layer.
+      String comparisons and regular expressions work from the
+      classitem defined at the layer level. You may mix expression
+      types within the different classes of a layer.
 
 .. index::
     pair: GROUP; CLASS
 
 GROUP [string]
-    Allows for grouping of classes. It is only used when a CLASSGROUP at the
-    :ref:`LAYER` level is set. If the CLASSGROUP parameter is set, only classes that
-    have the same group name would be considered at rendering time.  An example
-    of a layer with grouped classes might contain:
+    Allows for grouping of classes. It is only used when a CLASSGROUP
+    at the :ref:`LAYER` level is set. If the CLASSGROUP parameter is
+    set, only classes that have the same group name would be
+    considered at rendering time.  An example of a layer with grouped
+    classes might contain:
 
     .. code-block:: mapfile
 
@@ -101,9 +105,9 @@ GROUP [string]
 .. _KEYIMAGE:
 
 KEYIMAGE [filename]
-    Full filename of the legend image for the :ref:`CLASS`. This image is used
-    when building a legend (or requesting a legend icon via MapScript or the
-    :ref:`CGI application <cgi>`).
+    Full filename of the legend image for the :ref:`CLASS`. This image
+    is used when building a legend (or requesting a legend icon via
+    MapScript or the :ref:`CGI application <cgi>`).
 
 :ref:`LABEL`
     Signals the start of a :ref:`LABEL` object.
@@ -112,20 +116,21 @@ KEYIMAGE [filename]
     pair: MAXSCALEDENOM; CLASS
 
 MAXSCALEDENOM [double]
-    Minimum scale at which this :ref:`CLASS` is drawn. Scale is given as the
-    denominator of the actual scale fraction, for example for a map at a scale
-    of 1:24,000 use 24000. Implemented in MapServer 5.0, to replace the
-    deprecated MAXSCALE parameter. 
+    Minimum scale at which this :ref:`CLASS` is drawn. Scale is given
+    as the denominator of the actual scale fraction, for example for a
+    map at a scale of 1:24,000 use 24000. Implemented in MapServer
+    5.0, to replace the deprecated MAXSCALE parameter.
 
     .. seealso::
 
         :term:`Map Scale`
 
 MAXSCALE [double] - deprecated
-    Since MapServer 5.0 the proper parameter to use is MAXSCALEDENOM instead.
-    The deprecated MAXSCALE is the minimum scale at which this CLASS is drawn.
-    Scale is given as the denominator of the actual scale fraction, for
-    example for a map at a scale of 1:24,000 use 24000. 
+    Since MapServer 5.0 the proper parameter to use is MAXSCALEDENOM
+    instead.  The deprecated MAXSCALE is the minimum scale at which
+    this CLASS is drawn.  Scale is given as the denominator of the
+    actual scale fraction, for example for a map at a scale of
+    1:24,000 use 24000.
 
     .. deprecated:: 5.0
 
@@ -136,76 +141,91 @@ MAXSIZE [integer]
     pair: MINSCALEDENOM; CLASS
 
 MINSCALEDENOM [double]
-    Maximum scale at which this :ref:`CLASS` is drawn.  Scale is given as the
-    denominator of the actual scale fraction, for example for a map at a scale
-    of 1:24,000 use 24000.  Implemented in MapServer 5.0, to replace the
-    deprecated MINSCALE parameter. 
+    Maximum scale at which this :ref:`CLASS` is drawn.  Scale is given
+    as the denominator of the actual scale fraction, for example for a
+    map at a scale of 1:24,000 use 24000.  Implemented in MapServer
+    5.0, to replace the deprecated MINSCALE parameter.
 
     .. seealso::
 
         :term:`Map Scale`
 
 MINSCALE [double] - deprecated
-    Since MapServer 5.0 the proper parameter to use is MINSCALEDENOM instead.
-    The deprecated MINSCALE is the maximum scale at which this CLASS is drawn.
-    Scale is given as the denominator of the actual scale fraction, for
-    example for a map at a scale of 1:24,000 use 24000. 
+    Since MapServer 5.0 the proper parameter to use is MINSCALEDENOM
+    instead.  The deprecated MINSCALE is the maximum scale at which
+    this CLASS is drawn.  Scale is given as the denominator of the
+    actual scale fraction, for example for a map at a scale of
+    1:24,000 use 24000.
 
     .. deprecated:: 5.0
 
 MINSIZE [integer]
     Minimum size in pixels to draw a symbol. Default is 0.
 
 NAME [string]
-    Name to use in legends for this class. If not set class won't show up in
-    legend.
+    Name to use in legends for this class. If not set class won't show
+    up in legend.
 
 OUTLINECOLOR [r] [g] [b]
-    Color to use for outlining polygons and certain marker symbols. Line
-    symbols do not support outline colors.
+    Color to use for outlining polygons and certain marker
+    symbols. Line symbols do not support outline colors.
 
 SIZE [integer]
-    Height, in pixels, of the symbol/pattern to be used. Only useful with
-    scalable symbols. For vector (and ellipse) symbol types the default size
-    is based on the range of Y values in the POINTS defining the symbol. For
-    pixmaps, the default is the vertical size of the image. Default size is 1
-    for TTF symbols.
+    Height, in pixels, of the symbol/pattern to be used. Only useful
+    with scalable symbols. For vector (and ellipse) symbol types the
+    default size is based on the range of Y values in the POINTS
+    defining the symbol. For pixmaps, the default is the vertical size
+    of the image. Default size is 1 for TTF symbols.
 
 STATUS [on|off]
-    Sets the current display status of the class.  Default turns the class on.
+    Sets the current display status of the class.  Default turns the
+    class on.
 
 :ref:`STYLE`
-    Signals the start of a :ref:`STYLE` object. A class can contain multiple
-    styles.
+    Signals the start of a :ref:`STYLE` object.  A class can contain
+    multiple styles.  Multiple styles can be used create complex
+    symbols (by overlay/stacking).  See :ref:`sym_construction` for
+    more information on advanced symbol construction.
 
 :ref:`SYMBOL` [integer|string|filename]
-    The symbol name or number to use for all features if attribute tables are
-    not used. The number is the index of the symbol in the symbol file,
-    starting at 1, the 5th symbol in the file is therefore symbol number 5.
-    You can also give your symbols names using the NAME keyword in the symbol
-    definition file, and use those to refer to them. Default is 0, which
-    results in a single pixel, single width line, or solid polygon fill,
-    depending on layer type.
+    The symbol name or number to use for all features if attribute
+    tables are not used. The number is the index of the symbol in the
+    symbol file, starting at 1, the 5th symbol in the file is
+    therefore symbol number 5.  You can also give your symbols names
+    using the NAME parameter in the symbol definition file, and use
+    those to refer to them. Default is 0, which results in a single
+    pixel, single width line, or solid polygon fill, depending on
+    layer type.
 
-    You can also specify a gif or png filename. The path is relative to the
-    location of the mapfile.
+    You can also specify a gif or png filename. The path is relative
+    to the location of the mapfile.
 
+    See :ref:`sym_construction` for more information on advanced
+    symbol construction.
+
 :ref:`TEMPLATE <template>` [filename]
-    Template file or URL to use in presenting query results to the user.  See
-    :ref:`template` for more info.
+    Template file or URL to use in presenting query results to the
+    user.  See :ref:`template` for more info.
 
 TEXT [string]
-    Static text to label features in this class with. This overrides values obtained 
-    from the LABELITEM. The string may be given as an expression delimited using 
-    the ()'s. This allows you to concatenate multiple attributes into a single 
-    label. For example: ([FIRSTNAME],[LASTNAME]).
+    Static text to label features in this class with. This overrides
+    values obtained from the `LABELITEM`.  The string may be given as
+    an expression (see :ref:`EXPRESSIONS`).  This allows you to
+    concatenate multiple attributes into a single label.  You can for
+    example concatenate the attributes FIRSTNAME and LASTNAME like
+    this:
+
+    ::
+
+       TEXT '[FIRSTNAME] [LASTNAME]'
 
-You can also "stack" 2 symbols to achieve interesting effects. You define the second 
-symbol, which effectively sits "on top" of the symbol normally defined above.  
-See :ref:`sym_construction` for more information.
+Although the recommended way of making stacked symbols to achieve
+interesting effects is to use `STYLE`\s, you can also "stack" 2
+symbols without using `STYLE`\s. You define the second symbol, which
+effectively sits "on top" of the first symbol (as defined above).
 
-The following parameters allow you to define the symbol, and they are equivalent 
-to their non-overlay counterparts:
+The following parameters allow you to define the second symbol, and
+they are equivalent to their non-overlay counterparts:
 
 - OVERLAYBACKGROUNDCOLOR
 - OVERLAYCOLOR