Revise docs for all "Scripting Commands", except four find_XXX
that use a macro suite of their own.
* Take full advantage of the improved syntax highlighting.
* Make consequential use of <..> placeholders.
* Clarify things here and there in the text.
Specific improvements to some command docs:
* "math": Correct description of novel hexadecimal capability.
* "if", "foreach", "while": Provide link to "endif" etc
* "foreach", "while": Mention "break" and "continue".
* "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures;
advise against negative arguments or reverse ranges (compare issue #18461)
* "endif", "endfunction" etc: Explain that the argument is optional and
maintained for compatibility only
Teach `cmake_minimum_required` and `cmake_policy(VERSION)` to support a
version range of the form `<min>[...<max>]`. Define this to mean that
version `<min>` is required, but known policies up to those introduced
by `<max>` will be set to `NEW`. This will allow projects to easily
specify a range of versions for which they have been updated.
The most likely documentation page a project author will read in
response to a policy warning is the page for the policy itself.
Add to every policy documentation page a note explicitly stating
that the OLD behavior is deprecated. Also mention this in the
cmake_policy() command documentation that explains how to set a
policy to OLD.
Suggested-by: Fraser Hutchison <fraser.hutchison@gmail.com>
This is the convention suggested in the Sphinx documentation and is
already used in several other places in the CMake documentation.
Update a few places where we were using other characters.
Note in a few places of the cmake_policy() command documentation
that the cmake_minimum_required() command can set policies too.
Inspired-by: Peter Kümmel <syntheticpp@gmx.net>
