Manual.rst: Add 'General'. Explain in more detail why `[FE][lockIP] = 0` is...

Manual.rst: Add 'General'. Explain in more detail why `[FE][lockIP] = 0` is necessary. Add ESCAPE_TYPE_DEFAULT to config.qfq.ini explanation. Rewrite explanation for typeAheadLdapSearchPerToken.

extension/Documentation/Manual.rst

@@ -16,6 +16,14 @@
 
 .. include:: Includes.txt
 
+.. _general:
+
+General
+=======
+
+* Project homepage: https://git.math.uzh.ch/typo3/qfq
+* Latest relases: https://w3.math.uzh.ch/qfq/
+
 
 .. _installation:
 
@@ -68,7 +76,10 @@ In `config-qfq-ini`_ specify the:
 * installed `wkhtmltopdf` binary,
 * the site base URL.
 
-**Important**: To access FE_GROUP protected pages or content, it's necessary to set in the Typo3 Installtool: ::
+**Important**: To access FE_GROUP protected pages or content, it's necessary to disable the `[FE][lockIP]` check: `wkhtml`
+will access the Typo3 page locally and that IP address is different from the client (=user) IP.
+
+Configure via Typo3 Installtool `All configuration > $TYPO3_CONF_VARS['FE']`: ::
 
    [FE][lockIP] = 0
 
@@ -250,6 +261,8 @@ config.qfq.ini
 +-----------------------------+-------------------------------------------------+ crendentials is supported.                                                 |
 | LDAP_1_PASSWORD             | LDAP_1_PASSWORD=mySecurePassword                |                                                                            |
 +-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+
+| ESCAPE_TYPE_DEFAULT         | ESCAPE_TYPE_DEFAULT=s                           | All variables `{{...}}` get this escape class by default                   |
++-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+
 | SECURITY_VARS_HONEYPOT      | SECURITY_VARS_HONEYPOT = email,username,password| If empty: no check. All named variables will rendered as INPUT elements    |
 +-----------------------------+-------------------------------------------------+----------------------------------------------------------------------------+
 | SECURITY_ATTACK_DELAY       | SECURITY_ATTACK_DELAY = 5                       | If an attack is detected, sleep 'x' seconds and exit PHP process           |
@@ -291,6 +304,7 @@ Example: *typo3conf/config.qfq.ini*
 	;EDIT_FORM_PAGE = form
 	;LDAP_1_RDN='ou=Admin,dc=example,dc=com'
 	;LDAP_1_PASSWORD=mySecurePassword
+	;ESCAPE_TYPE_DEFAULT=s
 	;SECURITY_VARS_HONEYPOT=email,username,password
 	;SECURITY_ATTACK_DELAY=5
 	;SECURITY_SHOW_MESSAGE=true
@@ -491,7 +505,7 @@ Escape
 
 Variables used in SQL Statements might cause trouble by using: NUL (ASCII 0), \\n, \\r, \\, ', ", and Control-Z.
 
-Available `escape` types:
+To protect the web application the following `escape` types are available:
 
 	* 'm' - `real_escape_string() <http://php.net/manual/en/mysqli.real-escape-string.php>`_ (m = mysql)
 	* 'l' - LDAP search filter values will be escaped: `ldap-escape() <http://php.net/manual/en/function.ldap-escape.php>`_ (LDAP_ESCAPE_FILTER).
@@ -504,10 +518,11 @@ Available `escape` types:
 * It's possible to combine different `escape` types, they will be processed in the order given. E.g. `{{name:FE:alnumx:Ls}}` (L, s).
 * Escaping is typically necessary for SQL or LDAP queries.
 * Be careful when escaping nested variables. Best is to escape **only** the most outer variable.
-* In `config.qfq.ini`_ a global `default escape type` can be defined. Such type applies to all substituted variables without
-  a *specific* escape type.
-* Additionally a `default escape type` can be defined per `Form`. This overwrites the global definition of `config.qfq.ini`.
-* To suppress a default escape type, the `escape type` = '-' will switch of escaping. E.g.: `{{name:FE:alnumx:-}}`.
+* In `config.qfq.ini`_ a global `ESCAPE_TYPE_DEFAULT` can be defined. The configured escape type applies to all substituted
+  variables, who do not contain a *specific* escape type.
+* Additionally a `defaultEscapeType` can be defined per `Form` (separate field in the Form Editor). This overwrites the
+  global definition of `config.qfq.ini`.
+* To suppress a default escape type, define the `escape type` = '-' on the specific variable. E.g.: `{{name:FE:alnumx:-}}`.
 
 Sanitize class
 ^^^^^^^^^^^^^^
@@ -997,7 +1012,8 @@ To decide which Parameter should be placed on *Form.parameter* and which on *For
 +-----------------------------+----------------------------------+---------------------------------------------------------------+------+-------------+----------+
 | typeAheadLdapSearchPrefetch | `(mail=?)`                       | Regular LDAP search expresssion, typically return one record  | x    | x           | TA       |
 +-----------------------------+----------------------------------+---------------------------------------------------------------+------+-------------+----------+
-| typeAheadLdapSearchPerToken | -                                | Split search value in token and permutate search combination  | x    | x           | TA       |
+| typeAheadLdapSearchPerToken | -                                | Split search value in token and OR-combine every search with  | x    | x           | TA       |
+|                             |                                  |  the individual tokens                                        |      |             |          |
 +-----------------------------+----------------------------------+---------------------------------------------------------------+------+-------------+----------+
 | typeAheadLdapValuePrintf    | `'%s / %s', cn, mail`            | Custom format to display attributes, as `value`               | x    | x           | TA       |
 +-----------------------------+----------------------------------+---------------------------------------------------------------+------+-------------+----------+
@@ -1079,9 +1095,9 @@ This situation also applies in *pedantic* mode to verify the user input after ea
 PerToken
 ^^^^^^^^
 
-Sometimes a LDAP server only provides attributes like 'sn' and 'givenName', but not 'displayName' or a practial combination of
-multiple attributes - than it is difficult to search for 'firstname' and (=boolean AND) 'lastname'. E.g. 'John Doe', results to search like
-`(|(sn=*John Doe*)(givenName=*John Doe*))` which will be probably always be empty.
+Sometimes a LDAP server only provides attributes like 'sn' and 'givenName', but not 'displayName' or another practial
+combination of multiple attributes - than it is difficult to search for 'firstname' *and* (=human AND) 'lastname'.
+E.g. 'John Doe', results to search like `(|(sn=*John Doe*)(givenName=*John Doe*))` which will be probably always be empty.
 Instead, the user input has to be splitted in token and the search string has to repeated for every token.
 
 * *Form.parameter* or *FormElement.parameter*:
@@ -1097,7 +1113,8 @@ E.g.::
 
    Result: (& (|(a=*X*)(b=*X*)) (|(a=*Y*)(b=*Y*))
 
-Attention: this option is only usefull in specific environments.
+Attention: this option is only usefull in specific environments. Only use it, if it is really needed. The query becomes
+much more cpu / IO intensive.
 
 
 .. _Fill_LDAP_STORE:
@@ -1352,7 +1369,7 @@ parameter
 +-----------------------------+--------+----------------------------------------------------------------------------------------------------------+
 | typeAheadLdapIdPrintf       | string | Key formatting of LDAP result, per entry. E.g.: `'%s', mail`                                             |
 +-----------------------------+--------+----------------------------------------------------------------------------------------------------------+
-| typeAheadLdapSearchPerToken | -      | Split search value in token and permutate search combination                                             |
+| typeAheadLdapSearchPerToken | -      | Split search value in token and OR-combine every search with the individual tokens                       |
 +-----------------------------+--------+----------------------------------------------------------------------------------------------------------+
 | typeAheadLimit              | int    | Maximum number of entries. The limit is applied to the server (LDAP or SQL) and the Client               |
 +-----------------------------+--------+----------------------------------------------------------------------------------------------------------+