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

[havatv]

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

[geographika]

This is addressed for the CLASS docs with https://github.com/mapserver/docs/commit/f9fd6dc499c69d245a67e2c806b7a0d717543f5f - more to follow.

See Notes at https://mapserver.org/mapfile/class.html