mapserver / mapserver-documentation

Source repository for the MapServer documentation, for the live website. Please submit pull requests to the 'main' branch.

This repository is meant to write and manage the official documentation for MapServer. Please submit all pull requests to the main branch.

Documentation Guide

Please see the Documentation Development Guide, for getting started with your contributions: https://mapserver.org/development/documentation.html

Contributions

We warmly encourage documentation contributions, even if it is a small error or enhancement. Please create a new pull request with your change. Thank-you!

Communication

If you are looking for general advice on how to proceed, send your note or questions to the MapServer-dev list: subscribe

License

See LICENSE.md

mapserver-documentation's Issues

Document layer compositing framework (7.0, RFC 113)

The Layer Compositing Framework (MapServer/MapServer#5071) is implemented in version 7 (RFC 113 - http://mapserver.org/development/rfc/ms-rfc-113.html).
It needs to be documented.

EXTENT_PRIORITY (raster) not documented

I could not find EXTENT_PRIORITY documented. It was added in MapServer/MapServer@fbf4fb25d4

Document that PROJ_LIB configuration must come before any projection blocks.

Since projection objects are initialized as processed it is necessary that any proj.4 related configurations must be done before any projection blocks are encountered.

This config doesn't work:

MAP
  PROJECTION
    "init=epsg:3857"
  END
  CONFIG "PROJ_LIB" "C:/somedir/proj"
  ...

But this works fine:

MAP
  CONFIG "PROJ_LIB" "C:/somedir/proj"
  PROJECTION
    "init=epsg:3857"
  END
  ...

Steve

Layer type ANNOTATION is deprecated in 6.2 - documentation needs to be updated

According to the migration guide, layer type annotation is now deprecated. The documentation will have to be updated accordingly. I guess there are several affected files - layer is one of them, and there is probably things to update in the mapscript documentation.

Document that COLOR can take also hexadecimal value

Page http://www.mapserver.org/mapfile/style.html#style
COLOR [r] [g] [b] | [attribute]
Color to use for drawing features.

Should mention with an example that also hexadecimal format can be used
COLOR "#66FF4A"

Document 'Enable/disable OWS layers by IP list' (RFC-90)

Lack of Python mapscript documentation

MapScritp docs doesn't contains any information about fromstring and msLoadMapFromString functions:

>>> import mapscript
>>> mapscript.fromstring
<function fromstring at 0x7f2ffdd47320>
>>> mapscript.msLoadMapFromString
<built-in function msLoadMapFromString>

Raster documentation still refers to native mapserver formats

Since 6.2, mapserver relies on GDAL for all raster accesses, and does not have native support for png, jpeg, gif, tif or eppl as stated by the doc. The doc should be updated to reflect that.

Document that since Mapserver 7, mapfiles are expected to be UTF-8 encoded

The implementation of RFC103 for Mapserver 7 means that UTF-8 is expected as the character encoding for mapfiles. This should be documented.

Document 'Saving MapServer Objects to Strings' (RFC-88)

Document the FILTER changes made in Mapserver 7

In Mapserver 7, LAYER FILTER will only support native Mapserver filters (MapServer/MapServer#5001, http://mapserver.org/MIGRATION_GUIDE.html#migration). This needs to be documented.

Improve GEOMTRANFORM documentation

Supported expressions for GEOMTRANSFORM are listed on the mapfile-layer page http://mapserver.org/en/mapfile/layer.html and on the mapfile-style page http://www.mapserver.org/mapfile/style.html
However, there are no further links to show in detail how the expressions are used and what they yield as a result. Best help for users would be to write a new document that gathers examples from all GEOMTRANSFORM expressions into one page and "Cartographical Symbol Construction" page could be used as an example. As a first aid a light yellow "See also" box could be added to both STYLE and LAYER pages.

I found these existing documents but there can be more.
buffer: http://mapserver.org/de/development/rfc/ms-rfc-48.html
simplify, simplifypt, generalize: http://mapserver.org/development/rfc/ms-rfc-89.html
end, start etc.: http://www.mapserver.org/mapfile/symbology/construction.html
smoothing: http://www.mapserver.org/en/output/shape_smoothing.html
This one seems to be a sub-page of the "output" page, but that one does not have a corresponding link
http://www.mapserver.org/en/output/

Incorrect information about mapObj

From here

convertToString() : string
Saves the object to a string. Provides the inverse option for updateFromString. .. versionadded:: 6.4

But mapObj has no updateFromString method.

Update the Mapserver installation documentation to reflect the move to cmake

Mapserver has migrated from autotools to cmake ( MapServer/MapServer#4617 ).
This change only seems to be reflected in the installation documentation as a warning in unix.txt that the documentation is not up to date.
At least unix.txt needs to be updated.
Please add other files that need to be updated.

Mapscript docs - incorrect shapeObj method name: topologySimplifyPreservingSimplify

Both the SWIG mapscript docs as well as the PHP mapscript docs for the function topologyPreservingSimplify (SWIG mapscript/PHP mapscript) list it as topologySimplifyPreservingSimplify instead of topologyPreservingSimplify.

labelObj text/expression missing from mapscript docs

c.f. MapServer/MapServer#4310

Need to update download page...

http://mapserver.org/download.html still references 6.2 as the most recent release in several sections. Need to get that to 6.4.

Steve

Win32 compilation page outdated

http://mapserver.org/installation/win32.html still refers to the nmake era. Should be upgraded to cmake instructions

Swig/MapScript Query Docs Out-of-date

(moved from MapServer/MapServer#4414)

The page http://mapserver.org/mapscript/querying.html needs to be updated to reflect changes made between 5.6 and 6.0. Specifically, the code for query results processing has changed significantly. See http://mapserver.org/development/rfc/ms-rfc-65.html for more information. The PHP/MapScript docs don't seem to have a similar set of docs.

The migration guide needs to be better integrated with the documentation

(migrated from MapServer/MapServer#4472)

The migration guide is living in mapserver / mapserver.
We need to have the migration guide better integrated with the documentation.
Currently, on mapserver.org/trunk, the migration guide is the one for 6.0 (it should be the one for 6.2).

In track there used to be a mechanism to "copy" the migration guide over to the documentation.
Such a copy should be done every time the documentation is compiled.

It could perhaps also be useful to include the migration guide in the PDF documentation.

KVP request example for WCS 2.0 GetCapabilities is incorrect

The documentation on this page http://mapserver.org/ogc/wcs_server.html#wcs-2-0 is incorrect with respect the KVP request example for WCS 2.0 GetCapabilities.

Specifically the example says that the syntax should be:

GetCapabilities

http://www.yourserver.com/wcs?SERVICE=wcs&VERSION=2.0.1
&REQUEST=GetCapabilities

However, the version parameter is incorrect here. Following OWS common, the negotiation for version in the GetCapabilities request is performed using the acceptversions parameter; only once a version has been negotiated do subsequent requests (GetCoverage, DescribeCoverage) use the version parameter.

Also use of a lower case "wcs" is also incorrect. Similarly to WMS and WFS (parameter values are case sensitive) the correct service parameter value is actually "WCS".

So the example should be:
http://www.yourserver.com/wcs?SERVICE=WCS&ACCEPTVERSIONS=2.0.1& REQUEST=GetCapabilities&

Other examples should also be updated to use the uppercase "WCS" over lowercase "wcs"

Remove /mapfile/variable_sub.html

This page is duplicative of the runtime substitution documentation. It's also pretty old and I'm sure we want to advocate this type of use regardless.

Steve

UTFGrid support

http://mapserver.org/development/rfc/ms-rfc-93.html (code contribution in MapServer/MapServer#4765)

Document that label angle is counterclockwise

The angle for label is specified counterclockwise. This is not mentioned in the documentation (mapfile/label).

Document which parameters can be changed using run-time substitution, and those that require validation

There is confusion as to which parameters that can be changed using run-time substitution, the ways in which they can be changed and to what extent validation is necessary. I am among those that are confused, and could need some help here...

Related issues are #26 and MapServer/MapServer#3599.

Parameters can be changed using the URL (cgi/controls#variables), for example :

map.layer[layername].class[classname]=STYLE+COLOR+R+G+B+END

Variables can be used (cgi/runsub):

...mapserv?map=....&myvariable=myvalue"

Should we list the parameters that can be changed?
Should we list the parameters that can not be changed?

Should we list the parameters that require validation?
Should we list the parameters that do not require
validation?

@tbonfort suggests adding information on run-time substitution to the documentation of each parameter. That is a good idea, but requires some work:

Given the confusion around the subject, improving the documentation
might not be superfluous 
I'm not sure how to present this succinctly. In order to stay in sync
with the actual mapfile syntax, maybe the most visible and maintainable
solution is to document those directly in the mapfile document?

e.g, in STYLE:

COLOR r g b
  - blabla sets the color of the fill
  - can be overriden by url using
map.layer[layername].class[classname]=STYLE+COLOR+R+G+B+END

or CLASS:
TITLE "title"
   - used as a label for legends
   - can be overriden by URL using map.layer[l].class[c]=TITLE+foobar ,
but requires a "title" VALIDATION entry

If there was a way to add custom styling for those in the sphinx syntax
that would be great (e.g. so that they appear in a table with example
syntax and required validations)

This would probably be a very time consuming task...

How can we determine if a parameter can be changed using run-time substitution / URL?
@tbonfort (asking @sdlime):

(Steve, please correct me if I'm wrong)
* parameters that are allowed to be changed by URL have the tag
"URL_VARIABLE" in maplexer.l
* the validation checks are sprinkled out throughout the loadXXX methods
of mapfile.c, look for msyysource==MS_URL_TOKENS along with calls to
msValidateParameter

Links to older docs 404 on mapserver.org

The links to the .pdf documentation on http://mapserver.org/previousversions.html result in a 404 error for all three older versions. Only the current version returns a .pdf file.

Not Found

The requested URL /MapServer-60.pdf was not found on this server.

Document WFS 2.0 support

Give the `VALIDATION` block its own documentation page

VALIDATION blocks provide quite a bit of functionality that is currently poorly documented if at all: a quick scan through mapfile.c shows specifying expression, group, keyimage, template, text, title and immutable validation strings affects mapserver behaviour. Centralising documentation for these parameters would be useful, with links to the more specialised Runtime Substitution documentation where appropriate.

Integrate the PHP mapscript and SWIG mapscript documentation

In MapServer/MapServer#4347, @sdlime wrote:

Man, I wish we could have just one for the MapScript API document and then language specific implementation notes

and

One thing about merging MapScript docs is that would help surface differences in the API. Hard as we might try things are not identical. I am ok with a phased approach, that is, complete the work mentioned in this ticket and then move separately to unify all MapScript docs. Jeff, thoughts?

@jmckenna commented:

Right now I am happy that the PHP mapscript devs are maintaining the PHP docs directly themselves, very easily. @havatv I am not so sure how we could have one document home for mapscript, when the PHP and SWIG APIs are different.

And @sdlime commented:

I looked through docs a bit and it looks like both are relatively current. Formats are just very different. There is loads of overlap though that is pretty language agnostic. For example, the list of class members/attributes...

The discussion can continue here.
How should a unified mapscript API documentation be structured?

Information on where to place MAP files should be easy to find in the documentation

There was a recent post on mapserver-users about security issues when having map files readable by the web server. I tried to find a good place to refer to in the documentation when answering, but it was not easy to find. I suggest that information about how to set up map files and data sources for Mapserver is included in the introduction.

displaying attributs with a GetFeatureInfo is not documented

Add wms_include_items and wms_exclude_items (and add some information in gml_include_items and gml_exclude_items about this other not so new parameter)

See http://lists.osgeo.org/pipermail/mapserver-users/2006-September/019507.html for more reference.

Link to the documentation index missing

There used to be an index available from the documentation page. Now I can't find it. Don't know when it disappeared.

An index is useful, and we have done a lot of work to add index entries, so it would be nice to get the index back.

Document the use of WFS data sources through OGR

On the mapserver-users list, there was a request (2014-12-24) to add documentation of the possible use of OGR get to WFS data sources. This issue was created to follow up that request.
I guess it could be mentioned in the OGR and the WFS client document. Perhaps also under data input-> WFS.

Web metadata key "labelcache_map_edge_buffer" is not documented.

The web metadata key "labelcache_map_edge_buffer" does not seem to be documented anywhere. The parameter controls the amount of gutter around an image where no labels are to be placed. It's a commonly used parameter when doing tiling... There are references to it on the mailing list and in the mapcache docs. Value is given in pixels and must be a negative integer for 6.0 and earlier versions. In 6.2 the value can be positive or negative (we take an absolute value in the code).

Steve

Mapcache documentation - seeder: many options are missing

Some options seem to be missing on the seeder page in the documentation.

Here is what mapcache_seed reports (20. june trunk):

usage: mapcache_seed options
-c|--config [value]: configuration file (/path/to/mapcache.xml)
-t|--tileset [value]: tileset to seed
-g|--grid [value]: grid to seed
-z|--zoom [value]: min and max zoomlevels to seed, separated by a comma. eg 0,6
-M|--metasize [value]: override metatile size while seeding, eg 8,8
-e|--extent [value]: extent to seed, format: minx,miny,maxx,maxy
-n|--nthreads [value]: number of parallel threads to use
-m|--mode [value]: mode: seed (default), delete or transfer
-o|--older [value]: reseed tiles older than supplied date (format: year/month/day hour:minute, eg: 2011/01/31 20:45
-D|--dimension [value]: set the value of a dimension (format DIMENSIONNAME=VALUE). Can be used multiple times for multiple dimensions
-x|--transfer [value]: tileset to transfer
-d|--ogr-datasource [value]: ogr datasource to get features from
-l|--ogr-layer [value]: layer inside datasource
-s|--ogr-sql [value]: sql to filter inside layer
-w|--ogr-where [value]: filter to apply on layer features
-h|--help: show help
-q|--quiet: don't show progress info
-f|--force: force tile recreation even if it already exists
-v|--verbose: show debug log messages

I can't find -m, -M, -x, -h, -f documented.

Restructure website to arrange by our "products" (MapServer, MapCache, TinyOWS,..)

Comments from @sdlime :

I was thinking about a couple of changes to the home page.

1) Remove the "documentation" bread crumb, at least from the home page. To me it's confusing. If it stays it should start with "Home" and then add from there so you'd have:

  Home
  Home >> MapServer >> Documentation
  Home >> MapServer >> Documentation >> Mapfile
  Home >> MapCache >> Documentation >> mapcache.xml
  Home >> Download  
  Home >> Community

Which brings me to...

2) Right now what I'd consider documentation is mixed in with other project resources. I was thinking about a homepage table of contents like:

About (links to a page about the project itself, history, organization (mapcache/TinyOWS), etc...)
Products
  - MapServer (these would go to detail pages for each product)
  - MapCache
  - TinyOWS
Download
Documentation
  - MapServer
    - Guides (e.g. Mapfile/MapScript syntax)
    - Tutorials
    - How To's
  - MapCache (might not need sub-sections depending on what documentation they have)
    - ...
  - TinyOWS
    - ...
Community
Development  
  - github
  - RFCs

Something like this anyway. Once you get into a particular product section navigation (ideally) would be limited things relative to that product. No idea how practical this is though.

Tutorial is down

The tutorial http://www.mapserver.org/tutorial/index.html is down. Could you up the tutorial? Thank you in advance.

ENCODING is missing in the LAYER documentation

I can't find any documentation about ENCODING keyword i the LAYER documentation.

I found an example in the msautotest how it works and that solved my problem today.

MapServer/msautotest_DEPRECATED@b029514

msautotest documentation still references SVN - should be changed to GIT

The msautotest documentation refers to SVN, but I believe that the most current version of msautotest is on github.
http://www.mapserver.org/development/tests/autotest.html

PIE layer EXPRESSION not documented

see MapServer/MapServer#4287

WFS: correct data types for describefeaturetype

In the WFS (and WMS) server documentation, gml_[item name]_type is used to specify the type of the non-spatial properties of a feature. Currently the documentation is:

gml_[item name]_type (Optional) Specifies the type of the attribute.
Valid values are Integer|Real|Character|Date|Boolean.

The value specified in gml_[item name]_type is used as it is in the describefeaturetype response, so I guess that the values need to be valid GML types.

An overview of the XML schema type library can be found in: http://books.xmlschemata.org/relaxng/relax-CHP-8-SECT-1.html

"Real" and "Character" are not mentioned there, and "Integer", "Date" and "Boolean" are all specified with a lower case first letter.
I assume that "double" could be used instead of "Real", and "string" instead of "Character".

What should we write in the gml_[item name]_type documentation?
I think we need to say that the values need to be valid GML or XML data types. But should we give directions when it comes to which of the valid GML or XML data types that should be used? Should only primitive types be allowed?
Should a prefix (for example "xsd:") be mandatory?

Relevant open issue: MapServer/MapServer#462

Expressions involving geometry / shapes - clarifications needed?

The expression documentation says:

area ( shape1 ) returns the area of shape1

In a thread on the mailing list, @sdlime tells Andrea to use area([shape]) > 10000000.
Andrea had used EXPRESSION ( (area([GEOMETRY]) > 10000000) ), which did not work. EXPRESSION ( (area([shape]) > 10000000) ) worked.

I guess that the documentation should be made more clear - perhaps some introductory text. shape1 and shape2 are used in the documentation.

I am not very familiar with this, so I would appreciate suggestions!

Reorganise PHP Mapscript documentation to get important information included in the TOC and PDF

This issue has been copied from MapServer/MapServer#4347.

I suggest that PHP Mapscript documentation is reorganised as follows:

• A new file is introduced: mapscript/php/phpmapscript.txt - This file will contain the API (currently in index.txt).
• mapscript/php/index.txt is changed to an index, referencing: phpmapscript.txt, by_example.txt, migration_guide.txt.
• mapscript/php/class_intro.txt is removed and its contents included in index.txt.

Currently, the migration guide and the by example file are not included in the documentation tree / table of contents, and they are not included in the PDF document. I think they should be!

I am willing to do this, but it would be nice to get input (and hopefully approval) from @jmckenna and @sdlime first.

Runtime substitution page needs some update...

Page is: http://mapserver.org/cgi/runsub.html. The supported parameter section needs some changes... 1) Remove reference to DATAPATTERN. 2) All parameters must be validated, so that should be added and the specific reference for OUTPUTFORMAT should be removed. 3) I think we can safely remove version references in this block since the set of parameters supported has been stable for some time now.

Steve

Documentation of template driven output should be updated

The documentation of template driven output is lacking, and should be updated. Please report issues.
One thing I found is that .json is not a valid extension for templates, and the GeoJSON example uses .json as an extension.

Regular expression operator mixup in the Expressions chapter?

In 5.5 Expressions (PDF document), it is written:

MapServer supports two regex operators:
• ~ case insensitive regular expression
• ~* case sensitive regular expression

This seems to be wrong. It should be the other way around (as in the example below).

Links to previous versions of Docs are broken

FYI, the PDF doc links on the following page are all down (Current is working actually):
http://mapserver.org/previousversions.html#previousversions

Update documentation to reflect the removal of GD support

GD support was removed in Mapserver 7. Documentation needs to be updated to reflect this change. Please report affected files.

Link to track from the outputformat page

From the mapserver-users list:

There is a link on this page http://mapserver.org/mapfile/outputformat.htm to this page http://trac.osgeo.org/mapserver/ticket/2436 but I get a permission denied even when I am logged into Trac.

Thanks

Richard W. Greenwood, PLS
www.greenwoodmap.com http://www.greenwoodmap.com

On 29.04.2015 11:41, thomas bonfort wrote

we moved to github a little while ago....
MapServer/MapServer#2436

Document the usage of kernel density layers

The usage of kernel density layers is quite well documented in RFC 108. However, RFC was a plan about what and how to do and in the final implementations some details do not match with the RFC.

Because it does not make sense to edit a plan to suit with the final solution or at least with the future development, I suggest to document the usage of kernel density layers in the Output generation section http://mapserver.org/output/index.html as a new item "Dynamic Heatmap (Kernel Density Estimation)". There is already a chapter about dynamic charting and dynamic heatmap feels to belong to same gategory.

To start with, chapters 2.1, 2.2, 2.3, and 2.8 from the RFC could be copied to new place. From example mapfiles the line "processing "KERNELDENSITY_ATTRIBUTE=VAL"" should be removed because the functionality was implemented in a different way.