Documentation inconsistency for use of hypens on identifiers

Regarding the use of hypens on identifiers, the documentation doesn't look consistent. Which one is recommended? 

Here states the following:

parser.allow_hyphen_in_identifiers = false

This is a backward compatibility option, false by default, which allows the '-' character inside variable identifiers (available since 2.1). If enabled, be warned that you will have to surround the mathematical minus sign with spaces for it to be correctly interpreted.

But here, the configuration is different: 

If the parser.allows.dash.identifiers configuration value is set to true, then the - dash is also allowed in identifiers (and must be surrounded by spaces to be interpreted as an arithmetic minus operator).}}