| Date: | 2007/04/21 |
|---|---|
| Author: | Steve Lime, Havard Tveite |
| Contact: | steve.lime at dnr.state.mn.us, havard.tveite at umb.no |
| Last Edited: | $Date: 2008-12-23 13:34:31 -0800 (Tue, 23 Dec 2008) $ |
| Status: | Implemented |
| Version: | MapServer 5.0 |
| Id: | $Id: ms-rfc-26.txt 8278 2008-12-23 21:34:31Z hobu $ |
Mapserver terminology is mostly good and consistent, with a few exceptions. The two that generate the most confusion and TRANSPARENCY (layerObj) and various scale referencing parameters (e.g. MINSCALE).
Another change would be changing the symbolObj STYLE parameter to PATTERN instead. This would be simply to avoid confusion with the classObj STYLE.
The The purpose of this proposal is to make Mapserver even easier to use, removing confusion that can arise in cases of inconsistent terminology.
TRANSPARENCY is used in the Mapserver mapfile layer object for what is in fact opacity (as is also pointed out in the current documentation).
2) Technical details To achieve more consistent terminology, the following should be done:
Changing the keyword TRANSPARENCY to OPACITY
The old mapfile layer keyword “TRANSPARENCY” will be deprecated, but shall be supported in future versions of Mapserver as an alias for OPACITY.
The new mapfile layer keyword OPACITY should replace TRANSPARENCY. There will be no changes in type or semantics, only a change of keyword name.
The internal structure member name in the layerObj will change from transparency to opacity.
The parser will have to support both OPACITY and TRANSPARENCY (for backward compatibility). The type will not change.
At debug level 1 a warning will be issued that the TRANSPARENCY parameter is deprecated and OPACITY should be used instead.
Since the layerObj will no longer contain a transparency member this will break old scripts. The fix will be evident.
Documentation should be updated, introducing OPACITY as a new layer keyword with documentation similar to the current transparency. The layer keyword TRANSPARENCY should be documented as deprecated. All other documentation that references TRANSPARENCY will have to be updated (simple search-replace with a manual check of all occurences of the word transparency?)
SCALE and MAXSCALE/MINSCALE is a case where Mapserver terminology is not in line with mainstream map terminology.
In proper usage, scale is a representative fraction. The scale 1:50000 tells us that one meter on the map corresponds to 50000 meters in the “terrain”. 1:1000 (0.001) is a larger scale than 1:50000 (0.00002). The current use of MAXSCALE and MINSCALE is therefore not consistent with proper terminology.
To achieve more consistent terminology, the following could be done with limited consequences:
Change all occurrences of “SCALE” in keywords to “ScaleDenom”.
MinScale 10000 Maxscale 1000000
will become:
MinScaleDenom 10000 MaxScaleDenom 1000000
This will apply to the following occurences of SCALE in mapserver keywords:
The parser would have to accept the new keywords. The old keywords will be unique prefixes of the new keywords, and could be accepted by the parser (in a transition period or for eternity).
At debug level 1 a warning will be issued that the ...SCALE parameter is deprecated and ...SCALEDENOM should be used instead.
4) MapScript Implications For all scale variables, scale should be changed to scaledenom (for consistency reasons). The type (double) will not change. Like opacity above this could break old scripts.
The [scale] substitution should be deprecated (but still supported) and [scaledenom] added.
The scale CGI parameter would continue to be supported (e.g. users often define a map extent using a center point and a scale value). Scaledenom would also be supported.
All occurences of scale keywords in the documentation will have to be changed to reflect the new names. The old style keywords could be included, but should marked as deprecated.
Currently both the symbolObj and classObj contain STYLE parameters. The symbolObj style stores dash patterns used for line symbols. The name is derived from GD terminology. To avoid confusion with the classObj STYLE the symbolObj STYLE should be renamed to more concisely reflect it’s purpose.
In the symbolObj structure definition the member style will be renamed pattern. All references to the style in the code will also be updated.
The parser would have to accept the new keywords. The old keywords will be unique prefixes of the new keywords, and could be accepted by the parser (in a transition period or for eternity).
At debug level 1 a warning will be issued that the STYLE parameter is deprecated and PATTERN should be used instead.
As above the symbolObj structure would be altered and so MapScript scripts that set a symbol style programatically would break. They would need to reference the patter parameter instead.
None
None
The symbolObj reference guides would need to updated to reflect the name change.