MS RFC 133: Mapfile Syntax Cleanup

Date:

2021-01-26

Author:

Seth Girvin

Contact:

sethg@geographika.co.uk

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.

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

LAYER

MAP

SYMBOL

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

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

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