[mapserver-commits] r8147 - trunk/docs/development/rfc
svn at osgeo.org
svn at osgeo.org
Sun Nov 30 16:05:00 EST 2008
Author: hobu
Date: 2008-11-30 16:05:00 -0500 (Sun, 30 Nov 2008)
New Revision: 8147
Modified:
trunk/docs/development/rfc/ms-rfc-27.txt
trunk/docs/development/rfc/ms-rfc-28.txt
trunk/docs/development/rfc/ms-rfc-29.txt
trunk/docs/development/rfc/ms-rfc-3.txt
trunk/docs/development/rfc/ms-rfc-30.txt
trunk/docs/development/rfc/ms-rfc-31.txt
Log:
styling, break at 80, formatting
Modified: trunk/docs/development/rfc/ms-rfc-27.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-27.txt 2008-11-30 20:57:35 UTC (rev 8146)
+++ trunk/docs/development/rfc/ms-rfc-27.txt 2008-11-30 21:05:00 UTC (rev 8147)
@@ -14,27 +14,39 @@
Overview
--------
-MapServer 4.10 and older used a last in first out (LIFO) mechanism to plot labels on a map. This resulted in excessive use of ANNOTATION layers to make certain labels more prominent. This RFC introduces a new PRIORITY parameter on the LABEL object to control the order in which labels are rendered.
+MapServer 4.10 and older used a last in first out (LIFO) mechanism to plot
+labels on a map. This resulted in excessive use of ANNOTATION layers to make
+certain labels more prominent. This RFC introduces a new PRIORITY parameter
+on the LABEL object to control the order in which labels are rendered.
Technical Solution
------------------
-PRIORITY is a new LABEL parameter that takes an integer value between 1 (lowest) and MS_MAX_LABEL_PRIORITY (highest). The default value is 1.
+PRIORITY is a new LABEL parameter that takes an integer value between 1
+(lowest) and MS_MAX_LABEL_PRIORITY (highest). The default value is 1.
-MS_MAX_LABEL_PRIORITY is defined and can be altered in map.h, its default value is 10.
+MS_MAX_LABEL_PRIORITY is defined and can be altered in map.h, its default
+value is 10.
-The prioritization is handled by maintaining an array of MS_MAX_LABEL_PRIORITY cache lists in the label cache. When a label is added to the label cache, its priority index is used to decide in which cache list it should be added.
+The prioritization is handled by maintaining an array of MS_MAX_LABEL_PRIORITY
+cache lists in the label cache. When a label is added to the label cache,
+its priority index is used to decide in which cache list it should be added.
-Then at rendering time, we loop through the cache lists, starting with the highest priority list.
+Then at rendering time, we loop through the cache lists, starting with the
+highest priority list.
-Specifying an out of range PRIORITY value inside a map file will result in a parsing error. An out of range value set via MapScript or coming from a shape attribute will be clamped to the min/max values in msAddLabel().
+Specifying an out of range PRIORITY value inside a map file will result in a
+parsing error. An out of range value set via MapScript or coming from a shape
+attribute will be clamped to the min/max values in msAddLabel().
There is no expected impact on performance for using label priorities.
Support for attribute binding
-----------------------------
-The PRIORITY parameter can also be bound to an attribute using the attribute bindings mechanism defined in RFC-19. This means two ways to set LABEL PRIORITY:
+The PRIORITY parameter can also be bound to an attribute using the attribute
+bindings mechanism defined in RFC-19. This means two ways to set LABEL
+PRIORITY:
::
@@ -60,15 +72,22 @@
Modifications to the source code
--------------------------------
-* PRIORITY will be added to the LABEL object in map.h, in the mapfile parser/writer (mapfile.c) and in MapScript
+* PRIORITY will be added to the LABEL object in map.h, in the mapfile
+ parser/writer (mapfile.c) and in MapScript
-* A MS_IS_VALID_LABEL_PRIORITY() macro will be defined to validate priority ranges in a consistent way everywhere.
+* A MS_IS_VALID_LABEL_PRIORITY() macro will be defined to validate
+ priority ranges in a consistent way everywhere.
-* The label cache code (maplabel.c) will be modified to work with an array of MS_MAX_LABEL_PRIORITY cache lists instead of a single list
+* The label cache code (maplabel.c) will be modified to work with an
+ array of MS_MAX_LABEL_PRIORITY cache lists instead of a single list
-* The various msDrawLabelCacheXX() functions will be modified to replace the current loop on cache items with two nested loops: the outer loop will iterate on cache lists (from highest to lowest), and the inner loop will iterate on the cache items inside each list.
+* The various msDrawLabelCacheXX() functions will be modified to replace the
+ current loop on cache items with two nested loops: the outer loop will
+ iterate on cache lists (from highest to lowest), and the inner loop will
+ iterate on the cache items inside each list.
-* msBindLayerToShape() will be updated to support binding PRIORITY to a shape attribute field.
+* msBindLayerToShape() will be updated to support binding PRIORITY to a
+ shape attribute field.
MapScript Implications
----------------------
@@ -101,7 +120,8 @@
* 1619: https://trac.osgeo.org/mapserver/ticket/1619
-* Bug 206 also made mention of label priority but has been closed as duplicate of 1619: https://trac.osgeo.org/mapserver/ticket/206
+* Bug 206 also made mention of label priority but has been closed as
+ duplicate of 1619: https://trac.osgeo.org/mapserver/ticket/206
Voting history
--------------
@@ -113,4 +133,9 @@
Questions/Comments from the review period
-----------------------------------------
-* Q: Why use an array of cache lists instead of doing a quicksort on all cache entries? A: Mainly for performance reason, but it was also pointed out that quicksort is not stable and could result in different orderings depending on the set of labels.
\ No newline at end of file
+* Q: Why use an array of cache lists instead of doing a quicksort on all
+ cache entries?
+
+ A: Mainly for performance reason, but it was also pointed out that
+ quicksort is not stable and could result in different orderings
+ depending on the set of labels.
\ No newline at end of file
Modified: trunk/docs/development/rfc/ms-rfc-28.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-28.txt 2008-11-30 20:57:35 UTC (rev 8146)
+++ trunk/docs/development/rfc/ms-rfc-28.txt 2008-11-30 21:05:00 UTC (rev 8147)
@@ -172,11 +172,20 @@
The MS_DEBUGLEVEL environment variable
--------------------------------------
-Debug level can also be set using the (optional) MS_DEBUGLEVEL environment variable.
+Debug level can also be set using the (optional) MS_DEBUGLEVEL environment
+variable.
-When set, this value is used as the default debug level value for all map and layer objects as they are loaded by the mapfile parser. This option also sets the debug level for any msDebug() call located outside of the context of a map or layer object, for instance for debug statements relating to initialization before a map is loaded. If a DEBUG value is also specified in the mapfile in some map or layer objects then the local value (in the mapfile) takes precedence over the value of the environment variable.
+When set, this value is used as the default debug level value for all map and
+layer objects as they are loaded by the mapfile parser. This option also sets
+the debug level for any msDebug() call located outside of the context of a map
+or layer object, for instance for debug statements relating to initialization
+before a map is loaded. If a DEBUG value is also specified in the mapfile in
+some map or layer objects then the local value (in the mapfile) takes
+precedence over the value of the environment variable.
-This option is mostly useful when tuning applications by enabling timing/debug output before the map is loaded, to capture the full process initialization and map loading time, for instance.
+This option is mostly useful when tuning applications by enabling timing/debug
+output before the map is loaded, to capture the full process initialization
+and map loading time, for instance.
MapScript Implications
Modified: trunk/docs/development/rfc/ms-rfc-29.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-29.txt 2008-11-30 20:57:35 UTC (rev 8146)
+++ trunk/docs/development/rfc/ms-rfc-29.txt 2008-11-30 21:05:00 UTC (rev 8147)
@@ -73,7 +73,11 @@
END
-In the example above, if for a given shape we have v1006=1000, v1007=600 and v1008=400 then the actual pie slices for each class will be respectively 50%, 30% and 20% of the total pie size. If we produced bar charts then the values would represent the relative height of the bars with the largest value (highest bar) being 100% of the chart height.
+In the example above, if for a given shape we have v1006=1000, v1007=600 and
+v1008=400 then the actual pie slices for each class will be respectively 50%,
+30% and 20% of the total pie size. If we produced bar charts then the values
+would represent the relative height of the bars with the largest value
+(highest bar) being 100% of the chart height.
The following attachment to ticket 1800 contains a sample map produced
by the layer definition above:
@@ -157,14 +161,23 @@
Questions/Comments from the review period
-----------------------------------------
-* Q: Does this assume a POLYGON data type input only? Can LINE and POINT data sources also be supported?
+* Q: Does this assume a POLYGON data type input only? Can LINE and POINT data
+ sources also be supported?
- A: The current implementation works only for polygon data sources. I could extend it to work on point data sources as well fairly easily I think.
+ A: The current implementation works only for polygon data sources. I could
+ extend it to work on point data sources as well fairly easily I think.
- I'm not sure about line data sources though. I guess we could do like we do for ANNOTATION layers and use msPolylineLabelPoint() to determine the location of the chart.
+ I'm not sure about line data sources though. I guess we could do like we do
+ for ANNOTATION layers and use msPolylineLabelPoint() to determine the
+ location of the chart.
- Ticket #2145 has been opened to track this enhancement: https://trac.osgeo.org/mapserver/ticket/2145
+ Ticket #2145 has been opened to track this enhancement:
+ https://trac.osgeo.org/mapserver/ticket/2145
-* Q: Could we support attribute binding in CHART_SIZE = [size]? This would allow you to show the relative size of hits at a point and have the chart show the percentage contributions in the wedges.
+* Q: Could we support attribute binding in CHART_SIZE = [size]? This would
+ allow you to show the relative size of hits at a point and have the chart
+ show the percentage contributions in the wedges.
- A: While this would be a nice feature, we will keep it as a potential enhancement for a future release. See ticket #2136: https://trac.osgeo.org/mapserver/ticket/2136
+ A: While this would be a nice feature, we will keep it as a potential
+ enhancement for a future release. See
+ ticket #2136: https://trac.osgeo.org/mapserver/ticket/2136
Modified: trunk/docs/development/rfc/ms-rfc-3.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-3.txt 2008-11-30 20:57:35 UTC (rev 8146)
+++ trunk/docs/development/rfc/ms-rfc-3.txt 2008-11-30 21:05:00 UTC (rev 8147)
@@ -388,7 +388,7 @@
Bug 1477_
-.. _1477: http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1477
+.. _1477: http://trac.osgeo.org/mapserver/ticket/1477
Modified: trunk/docs/development/rfc/ms-rfc-30.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-30.txt 2008-11-30 20:57:35 UTC (rev 8146)
+++ trunk/docs/development/rfc/ms-rfc-30.txt 2008-11-30 21:05:00 UTC (rev 8147)
@@ -18,8 +18,8 @@
WMS support to version 1.3.0 of the specification.
MapServer already includes mechanisms to support multiple WMS versions (and
-already supports WMS versions 1.0.0, 1.1.0 and 1.1.1) so in theory this upgrade should
-be straightforward and shouldn't require a RFC. Unfortunately, WMS 1.3.0
+already supports WMS versions 1.0.0, 1.1.0 and 1.1.1) so in theory this upgrade
+should be straightforward and shouldn't require a RFC. Unfortunately, WMS 1.3.0
contains some tricky changes that while they are not exactly backwards
incompatible are likely to make the life of users of WMS miserable.
@@ -93,8 +93,16 @@
Questions/Comments from the review period
-----------------------------------------
-* Q: Can libxml2 be used to generate XML responses to continue the work started in mapowscommon.c?
+* Q: Can libxml2 be used to generate XML responses to continue the work started
+ in mapowscommon.c?
- A: I'll keep libxml2 in mind during the implementation, but I do not plan to refactor and risk breaking any code to convert it to libxml2 as part of this upgrade.
+ A: I'll keep libxml2 in mind during the implementation, but I do not plan to
+ refactor and risk breaking any code to convert it to libxml2 as part of
+ this upgrade.
- Since WMS 1.3.0 doesn't implement OWS common, it won't benefit from any of the code that's already using libxml2. It will actually mostly reuse existing printf-based code that's already well tested and working. I think the right time to switch to libxml2 for WMS would be when it will support OWS common and then there will be real benefits by reusing functions from mapowscommon.c.
+ Since WMS 1.3.0 doesn't implement OWS common, it won't benefit from any of
+ the code that's already using libxml2. It will actually mostly reuse
+ existing printf-based code that's already well tested and working. I think
+ the right time to switch to libxml2 for WMS would be when it will support
+ OWS common and then there will be real benefits by reusing functions from
+ mapowscommon.c.
Modified: trunk/docs/development/rfc/ms-rfc-31.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-31.txt 2008-11-30 20:57:35 UTC (rev 8146)
+++ trunk/docs/development/rfc/ms-rfc-31.txt 2008-11-30 21:05:00 UTC (rev 8147)
@@ -10,19 +10,31 @@
:Version: 5.0
:Status: Accepted (2007/06/22)
-Description: This RFC addresses the ability of the MapServer tokenizer (in maplexer.l and mapfile.c) to work from strings as well as files. A mapfile-wide ability was added to 5.0 source and this RFC looks at loading MapServer objects (layers, scalebars, etc...) via MapScript and via URLs.
+Description: This RFC addresses the ability of the MapServer tokenizer
+(in maplexer.l and mapfile.c) to work from strings as well as files. A
+mapfile-wide ability was added to 5.0 source and this RFC looks at loading
+MapServer objects (layers, scalebars, etc...) via MapScript and via URLs.
Current State
~~~~~~~~~~~~~
-Presently MapServer can load entire mapfile's from a text block using msLoadMapFromString. This is a new capability in 5.0. MapServer has long been able to load/modify individual values via URL using a map_object_property syntax (e.g. map_scalebar_units).
+Presently MapServer can load entire mapfile's from a text block using
+msLoadMapFromString. This is a new capability in 5.0. MapServer has long been
+able to load/modify individual values via URL using a map_object_property
+syntax (e.g. map_scalebar_units).
-The problem with the URL support is that it is cumbersome for the user and results in a ton of duplicative code in mapfile.c making maintenance difficult. Developers will often add a parameter but forget to add a URL equivalent. This proposal removes that redundant code and relies on a single tokenizing function for each object.
+The problem with the URL support is that it is cumbersome for the user and
+results in a ton of duplicative code in mapfile.c making maintenance difficult.
+Developers will often add a parameter but forget to add a URL equivalent. This
+proposal removes that redundant code and relies on a single tokenizing function
+for each object.
C API Changes
~~~~~~~~~~~~~
-All major objects would get a new ...LoadFromString function (e.g. msLoadLayerFromString and so on). These functions would be very simple and would take an existing reference to an object and a string snippet. They would:
+All major objects would get a new ...LoadFromString function (e.g.
+msLoadLayerFromString and so on). These functions would be very simple and
+would take an existing reference to an object and a string snippet. They would:
1) establish lexer thread locks
2) set lexer state to MS_TOKENIZE_STRING
@@ -32,20 +44,34 @@
The loadObject functions would need minor changes:
-1) Each function would need to remove restrictions for duplicate properties. That is setting a parameter twice should not generate an error as is does now.
-2) Properties with allocated memory (e.g. char * ) should be free'd if they already have values and are being updated.
-3) the object main keyword (e.g. LAYER or CLASS) should be allowed as a token within that object loader. When parsing a file the object identifier (e.g. LAYER) is stripped off with the parent object. For example, a CLASS is recognized by loadLayer so that token never is encountered by loadClass. It makes the most sense to pass entire object definitions including the object identifier for ease of use.
+1) Each function would need to remove restrictions for duplicate properties.
+ That is setting a parameter twice should not generate an error as is
+ does now.
+2) Properties with allocated memory (e.g. char * ) should be free'd if they
+ already have values and are being updated.
+3) the object main keyword (e.g. LAYER or CLASS) should be allowed as a token
+ within that object loader. When parsing a file the object identifier
+ (e.g. LAYER) is stripped off with the parent object. For example, a CLASS
+ is recognized by loadLayer so that token never is encountered by loadClass.
+ It makes the most sense to pass entire object definitions including the
+ object identifier for ease of use.
MapScript
~~~~~~~~~
-I'm open to suggestions but I think the easiest thing to do would be to add an updateFromString method to all major objects. It would simply take a string snippet and would wrap the ...LoadFromString methods mentioned above. They would return MS_SUCCESS or MS_FAILURE. Might consider adding a "clear" method to (freeObject then initObject) so that users could clean things out and reload from a string. I'm not sure about the effects on reference counting here.
+I'm open to suggestions but I think the easiest thing to do would be to add an
+updateFromString method to all major objects. It would simply take a string
+snippet and would wrap the ...LoadFromString methods mentioned above. They
+would return MS_SUCCESS or MS_FAILURE. Might consider adding a "clear" method
+to (freeObject then initObject) so that users could clean things out and reload
+from a string. I'm not sure about the effects on reference counting here.
URL
~~~
-I propose removing all the loadObjectValue (e.g. loadLayerValue) functions in favor of entire object loading. So, instead of doing something like:
+I propose removing all the loadObjectValue (e.g. loadLayerValue) functions in
+favor of entire object loading. So, instead of doing something like:
...map_scalebar_units=meters&map_scalebar_intervals=5&map_scalebar_size=300+2...
@@ -53,23 +79,50 @@
...map_scalebar=UNITS+METERS+INTERVALS+5+SIZE+300+2...
-The major objects would still be referenced by map_scalebar or map_legend or map_layername, but all other properties would be loaded through snippets.
+The major objects would still be referenced by map_scalebar or map_legend or
+map_layername, but all other properties would be loaded through snippets.
-The function msLoadMapParameter would become msUpdateMapFromURL and it would set the lexer state, acquire a thread lock and then call the appropriate loadObject function.
+The function msLoadMapParameter would become msUpdateMapFromURL and it would
+set the lexer state, acquire a thread lock and then call the appropriate
+loadObject function.
-One issue is that the loadObject functions have traditionally worked just from files so there are no limitations on what can be altered. Obviously from a URL you can't allow just anything to be altered (e.g. CONNECTION, DUMP and so on). So, we would create a new lexer state, MS_TOKENIZE_URL, that would only recognize the parameters that we want. In that state the lexer would not return tokens like DUMP or CONNECTION so the loadObject functions would not handle those cases. This is a simple addition to the lexer. Any parameter exposed to URL modification will have the relevant loading block examined so that there are no memory leaks or buffer overflow possibilities.
+One issue is that the loadObject functions have traditionally worked just
+from files so there are no limitations on what can be altered. Obviously from
+a URL you can't allow just anything to be altered (e.g. CONNECTION, DUMP
+and so on). So, we would create a new lexer state, MS_TOKENIZE_URL, that
+would only recognize the parameters that we want. In that state the lexer
+would not return tokens like DUMP or CONNECTION so the loadObject functions
+would not handle those cases. This is a simple addition to the lexer. Any
+parameter exposed to URL modification will have the relevant loading block
+examined so that there are no memory leaks or buffer overflow possibilities.
-In addition, it was pointed out that URL configuration should not be a default behavior but should be enabled explicitly. Enabling this feature would happen by way of a new parameter within the webObj- URLCONFIG [pattern], with a default of NULL. The pattern would be a regular expression that would be applied against any map_* variables. So, one could limit changes to just the scalebar object with URLCONFIG 'scalebar' or allow more with URLCONFIG '.'. The default would not to be allow any URL configuration.
+In addition, it was pointed out that URL configuration should not be a
+default behavior but should be enabled explicitly. Enabling this feature
+would happen by way of a new parameter within the webObj- URLCONFIG [pattern],
+with a default of NULL. The pattern would be a regular expression that would
+ be applied against any map_* variables. So, one could limit changes to just
+ the scalebar object with URLCONFIG 'scalebar' or allow more with
+ URLCONFIG '.'. The default would not to be allow any URL configuration.
Backwards Compatibility
~~~~~~~~~~~~~~~~~~~~~~~
-The URL change will break backwards compatibility but I feel this is a relatively lightly used option and this change will be very beneficial.
+The URL change will break backwards compatibility but I feel this is a
+relatively lightly used option and this change will be very beneficial.
Post Implementation Notes
~~~~~~~~~~~~~~~~~~~~~~~~~
-Apparently a number of folks are having trouble with porting applications to use the new url configuration. Below are more examples and lists of supported keywords by object type. Rule of thumb one: when there is the opportunity for more than one of a particular object (e.g. layers, classes and styles) the syntax must uniquely identify the object in question in the variable name (e.g. map.layer[lakes]) and then the mapfile snippet to modify the object is given as the variable value. We have no way to modify 5 styles at once because the mapfile syntax is so freeform. Rule of thumb two: any parameters or objects that hang off the mapObj must be referenced in the variable name (e.g. map.imagetype).
+Apparently a number of folks are having trouble with porting applications to
+use the new url configuration. Below are more examples and lists of supported
+keywords by object type. Rule of thumb one: when there is the opportunity for
+more than one of a particular object (e.g. layers, classes and styles) the
+syntax must uniquely identify the object in question in the variable name
+(e.g. map.layer[lakes]) and then the mapfile snippet to modify the object is
+given as the variable value. We have no way to modify 5 styles at once because
+the mapfile syntax is so freeform. Rule of thumb two: any parameters or
+objects that hang off the mapObj must be referenced in the variable name
+(e.g. map.imagetype).
Example 1, changing a scalebar object:
More information about the mapserver-commits
mailing list