MS RFC 115: Upgrade and cleanup of Tutorial and Demo datasets

Date:2016/02
Author:Lars Lingner
Contact:lars at lingner.eu
Author:Seth Girvin
Contact:sgirvin at compass.ie
Author:Julien Enselme
Contact:julien.enselme at ioda.net
Author:Lars Schylberg
Contact:lars.schylberg at saabgroup.com
Status:Draft
Version:MapServer 7.0

1. Motivation

The MapServer Tutorial and Demo packages are very outdated and need some love. This result in a very bad first impression for new users testing the software.

In this RFC, we propose a plan to address this situation.

2. Proposed plan

  • review current docs
  • build example data package with new data
  • create new tutorial structure
  • create a HTML Template which can be used for demo server
  • create updated version for OSGeo-Live

Work and discussion is done in fork of docs repository [1]. We’ll update from upstream repository when upstream changes are committed. When we have a first stable version we will create a pull request to the upstream repository.

3. Backwards Compatibility

It is proposed that the tutorials work with both MapServer 6.4 and 7.0+ The existing tutorials, based around MapServer 5.0, could perhaps be moved to an archive section in the documentation.

4. Implementation Details

Content of the data package

  • vector data (OSM, NaturalEarth)
  • raster data (SRTM, satellite imagery, DEM)

Review current tutorial docs

  • remove or update outdated information and external links
  • reuse current text where appropriate

The current situation is that tutorials are duplicated in different places, with some links updated in one place and not another. For example the main tutorial section is on the documentation site at http://demo.mapserver.org/tutorial/sections.html However sections 3 and 4 of the tutorials are simply links to http://demo.mapserver.org/tutorial/section3.html The http://demo.mapserver.org site also duplicates sections 1 and 2.

In addition the OSGeo-Live has a tutorial section which is more recent, and could perhaps be used as the basis of the tutorials on the MapServer documentation site: http://live.osgeo.org/en/quickstart/mapserver_quickstart.html

A web page with OpenLayers included will be provided to view the maps created in this tutorial. This can also be used for the MapServer online demo.

Current tutorial titles, to review and decide if they are still relevant with modern MapServer usage.

Current structure

Section 1: Static Maps and the MapFile

  • 1.1 - Map with a single layer
  • 1.2 - Map with two layers from a single shapefile
  • 1.3 - Using classes to create a “useful” map
  • 1.4 - Labeling layers and Label layers
  • 1.5 - Raster layers
  • 1.6 - WMS layers
  • 1.7 - Projections, deconstructed
  • 1.8 - MapServer output formats
  • 1.9 - Intro to MapServer Modes: map and browse
  • Addendum (more examples):
    • PostGIS layers
    • WMS Server

Section 2: User Interface and HTML Templates

  • 2.1- Pan and zoom
  • 2.2 - Layer control
  • 2.3 - Scalebar
  • 2.4 - Legend
  • 2.5 - Reference map

Section 3: Query and More HTML Templates

  • 3.1 - Class-level Query Template
  • 3.2 - Layer-specific Header and Footer Templates
  • 3.3 - Map-wide Header and Footer Templates
  • 3.4 - The QueryMap

Section 4: Intro to Advanced Interfaces

  • 4.1 - More CGI Variables
  • 4.2 - Using JavaScript t0 Enhance the Application
  • 4.3 - Links to Other Examples

Proposed structure

Quickstart: Your first MapFile

  • 1.1 - Map with a single layer
  • 1.2 - Map with two layers
  • 1.3 - Viewing the map in a browser
  • 1.4 - Labeling Data
  • 1.5 - Symbolizing data (classes and expressions)
  • 1.6 - Adding a raster layer
  • 1.7 - Using different datasources (ShapeFile, PostGIS, SpatialLite, OGR)
  • 1.8 - Projections
  • 1.9 - Serving vector data

In depths tutorial

  • 2.1 - Adding external layers
  • 2.2 - Using different output formats
  • 2.3 - Making the map interactive with UTFGrid
  • 2.4 - Configure OGC Services (WMS, WFS, GetFeatureInfo)
  • 2.5 - Advanced symbology
  • 2.6 - Editors for creating map styles (ScribeUI, Magnacarto, Geany, Mapmanager, )
  • 2.7 - Styling OpenStreetMap Data with MapServer (basemaps)
  • 2.8 - Generate high resolution renderings for print

Feature Tutorials

  • Layer masking
  • Labels with leader lines
  • Contour lines rendering
  • …more features from RFCs

5. Documentation

n/a

6. Voting History