Document ZPublisher request parameter controls

[d-maurer]

ZPublisher (more precisely ZPublisher.HTTPRequest,processInputs) supports a large set of controls which guide the interpretation of request parameters. A request parameter (as supported by Zope) has the general form name=value. Controls are specified as suffixes of the form :<control> to the name part of the request parameter. They can specify for example a type for the value or how the parameter should be aggregated with other request parameters to form a complex form variable. Examples are x:int=1 (gives a form variable x with integer value 1) and r.x:record=1 (gives a form variable r with attribute x with value '1').

The discussions in #618 and #634 have shown that we need a specification/documentation of these features.

Where should such a documentation/specification be located?

• my personal preference would be a file request_parameter_controls.rst alongside HTTPRequest with a reference in the docstring of its processInputs to this file

with alternatives:

• directly put it in the docstring of processInputs
• put it in the "Zope Developer Guide"
• put it in the "Zope Book"

Such a document would have wide ranging effects:

• it is a prerequisite for Enhance ZPublisher "type suffixes" and "ZTUtils" ... #619
• it would provide answers for "HTTPRequest.processInputs": broken "character_encoding" handling #634
• it would contribute to the resolution of Several possible problems within the ZPublisher Converters module #558

[icemac]

I like the idea to have the documentation near the code although it should be in the documentation, too to be easily findable.

[d-maurer]

Michael Howitz wrote at 2019-5-20 23:15 -0700:

I like the idea to have the documentation near the code although it should be in the documentation, too to be easily findable.

We could first put is near the code (I have seen that this is already used in `Products.Transience`) and put it in a more prominent place later - once it is finished and "polished". Or we put a reference at a prominent place to the location in the code tree.

[d-maurer]

Closed via #640