MS RFC 133: Mapfile Syntax Cleanup¶
- Date:
2021-01-26
- Author:
Seth Girvin
- Contact:
- Status:
Adopted
- Last update:
2022-03-29
- Version:
MapServer 8.0
Overview¶
This RFC proposes removing deprecated Mapfile keywords and syntax as part of the 8.0 release. Keywords have been deprecated in previous MapServer releases for various reasons, and continuing to support them could cause confusion for new MapServer users.
See MS RFC 26: Version 5 Terminology Cleanup for an RFC with similar aims. Note forming the basis for the RFC can be found in the MapServer Wiki.
Deprecation Options¶
There are a number of options for each keyword listed as deprecated.
Full removal
Remove from parser
Remove all code paths and references
Remove from docs
Remove from all msautotests and examples
Reinstate the keyword
Remove deprecated reference from the docs
Leave as deprecated
Add DEBUG warnings if used, aiming to remove in a future MapServer 9.0
Note this RFC is a first draft and aims to set out options to discuss on the MapServer dev mailing list.
Upgrading Mapfiles¶
In order to help users upgrade Mapfiles, version validation has been added to the Python mappyfile project. The online validator is currently hosted at http://mappyfile.geographika.net/ but could be hosted on the mapserver.org domain if desired.
The mappyfile project can also be run locally on the command-line to validate Mapfiles against specific versions of MapServer using the following command:
mappyfile validate C:\Code\mapserver\mapserver\msautotest\**\*.map --version=8.0
This will log any Mapfile syntax errors for the specified version in the following format:
class16.map (Line: 26 Column: 3) ERROR: Invalid value in CLASS - 'color' does not match any of the regexes: '^__[a-z]+__$'
Proposed Keyword Changes¶
The following Mapfile syntax changes are proposed.
CLASS¶
Remove the following deprecated keywords. These were used to apply direct styling in CLASS
blocks, rather than in STYLE
blocks.
BACKGROUNDCOLOR deprecated since 6.0
COLOR deprecated since 6.0
MAXSIZE deprecated since 6.0
MINSIZE deprecated since 6.0
OUTLINECOLOR deprecated since 6.0
SIZE deprecated since 6.0
SYMBOL deprecated since 6.0
MAXSCALE - not in docs
Also the following OVERLAY
shortcuts used for style 1 (undocumented):
OVERLAYBACKGROUNDCOLOR
OVERLAYCOLOR
OVERLAYMAXSIZE
OVERLAYMINSIZE
OVERLAYOUTLINECOLOR
OVERLAYSIZE
OVERLAYSYMBOL
Deprecated approach of styles directly in a CLASS:
LAYER
NAME 'bdry_counpy2'
TYPE LINE
DATA '../query/data/bdry_counpy2.shp'
STATUS DEFAULT
CLASS
COLOR 231 231 231
END
END
New (since 2002) approach:
LAYER
NAME 'bdry_counpy2'
TYPE LINE
DATA '../query/data/bdry_counpy2.shp'
STATUS DEFAULT
CLASS
STYLE
COLOR 231 231 231
END
END
END
LABEL¶
ANTIALIAS GD support removed in 7.0
BACKGROUNDCOLOR removed in 6.0
BACKGROUNDSHADOWCOLOR removed in 6.0
BACKGROUNDSHADOWSIZE removed in 6.0
ENCODING deprecated since 7.0
MINLENGTH - unused and undocumented
LAYER¶
DUMP deprecated since 6.0
LAYERANGLEITEM already removed?
LABELSIZEITEM already removed?
OPACITY deprecated since 7.0
TRANSPARENCY deprecated since 5.0
MAP¶
DATAPATTERN deprecated since 5.4
IMAGEQUALITY deprecated since 4.6
INTERLACE deprecated since 4.6
TEMPLATEPATTERN deprecated since 5.4
TRANSPARENT deprecated since 4.6
SYMBOL¶
ANTIALIAS GD support removed in 7.0
TRANSPARENT GD support removed in 7.0
STYLE¶
ANGLEITEM deprecated since 5.0
ANTIALIAS GD support removed in 7.0
BACKGROUNDCOLOR deprecated since 6.2
MINSIZE - not in docs, unused?
MAXSIZE - not in docs, unused?
SCALEBAR¶
INTERLACE deprecated since 4.6
TRANSPARENT deprecated since 4.6
WEB¶
Backward compatibility issues¶
Users will need to remove deprecated keywords from Mapfiles to use MapServer 8.0
Documentation needs¶
Mapfile documentation will be updated to reflect any changes in the Mapfile syntax.
Files¶
mapfile.c
mapfile.h
maplexer.l
maplexer.c
mapserver.h
mapserver/msautotest Mapfiles
mapcopy.c
maplegend.c
Ticket ID and reference¶
Remove LOG, EXTENT, MAXSCALE, and MINSCALE keywords from WEB object: https://github.com/MapServer/MapServer/pull/6333
Remove MAP TRANSPARENT keyword: https://github.com/MapServer/MapServer/pull/6329
Remove INTERLACE, IMAGEQUALITY, OPACITY keywords from SCALEBAR, LEGEND and MAP classes: https://github.com/MapServer/MapServer/pull/6342
Removal of styling keywords from a Mapfile CLASS: https://github.com/MapServer/MapServer/pull/6317
Remove DUMP keyword from LAYER - RFC133: https://github.com/MapServer/MapServer/pull/6264
Remove BACKGROUNDCOLOR from STYLE object: https://github.com/MapServer/MapServer/pull/6343
Remove unused LABEL>MINLENGTH property: https://github.com/MapServer/MapServer/pull/6462
Remove URL update functionality (DATAPATTERN and TEMPLATEPATTERN): https://github.com/MapServer/MapServer/pull/6469
Voting history¶
+1 from ThomasB, TomK, JeromeB, JukkaR, MikeS, EvenR, JeffM, SethG, SteveL
See https://lists.osgeo.org/pipermail/mapserver-dev/2021-May/016476.html