Adjust documentation to the actual behaviour of -Dwith-optimize

[steffengraber]

Fix issue #2340

[steffengraber]

@jarsi maybe you can have a look

[jarsi]

Hi @steffengraber, thanks for starting this!

If I understand the cmake line correctly then the default is still ON although it states that it is OFF. Also the default optimization level is still set to O2 (see here).

I think it's a matter of preference whether with-opimize defaults to O2 or O3. We ran some tests a while ago and did not see huge differences between these two.

If I remember correctly, this has not been finally resolved, maybe @heplesser and @diesmann could comment on this or we discuss this in one of our upcoming meetings.