d4d1f85297 Help: Move a note about arguments and genexes into include file
968224484f Help: Drop unused `PROPERTY_GENEX` replace from `prop_tgt/INTERFACE_*` files
65457e4fae Help: Add _See Also_ sections to related CMake commands
c86ec79d07 Help: Use direct refs to genexes instead of ``$<GENEX-NAME>``
8c6274326d Help: Use CMake highlighting for command synopsis
c356a94512 Help: Use monospaced font for a genex name in a section title
f98c8707f4 Help: Use `code-block:: cmake` instead of `::` for sub-commands descriptions
2ba351ca4f Help: ``CMake`` → CMake
...
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7873
Clarify in `cmake-language(7)` that a variable lookup may use a cache
entry if the variable is not set. Fix misleading text in added by
commit 8ba2a8d4a4 (Help: short/long variable reference in if command,
2018-11-01, v3.14.0-rc1~408^2~2).
Fixes: #23863
Section "Variables References" said that environment and cache
variables are "evaluated in the same contexts as a normal variable
reference". The reader has to guess what "contexts" means in
this context. Probably "inside a Quoted Argument or an Unquoted
Argument", exactly as for ordinary variable references.
But this is exactly what the reader would tacitly assume anyway.
Therefore I think the removed clause was unnecessary, and possibly
more confusing than helpful.
* The code snippets in the docs consist of CMake code mixed
with syntax definition punctuation like < > [ ] ... Therefore
a pure CMake lexer is inadequate. Here it is replaced by a
CMake syntax definition parser.
* Fixed syntax definition snippets in FindPkgConfig.cmake to
make best use of syntax highlighting. This source file is the
hardest to support because it contains comparison operators
<= = >=, which need special attention to avoid confusion
with the placeholder indicators <...>.
* Fixed syntax in execute_process.rst (there were unbalanced
brackets).
* Disabled syntax highlighting for long string examples in
cmake-language.7.rst.
* No highlighting of removed syntax in CMP0049
* To inspect the outcome of this patch, see e.g. the pages
* manual/cmake-buildsystem.7.html
* module/ExternalProject.html
* module/FindPkgConfig.html
which are particularly rich in complex code snippets.
This was overlooked in the initial implementation of CMP0053. However,
an additional policy to reject it again is not worth it. Instead, add
tests and document the behavior.
Fixes: #17883
Clarify definitions of `bracket_open` and `bracket_close` productions.
In note about unquoted arguments containing unescaped double quotes,
provide examples of how they can be written as quoted arguments.
Also clarify location of nested calls supported by variable function
scope.
Suggested-by: Дилян Палаузов <dilyan.palauzov@aegee.org>
Some of our "cmake" code blocks do not use fully valid CMake syntax
because they have placeholders for human reference. Sphinx has
never been able to properly lex and highlight these, but now warns.
Fix each block's syntax or change to a non-cmake block as appropriate.
This fixes several reported bugs about CMake not handling
non-ascii paths on Windows.
Practically, the use of some unicode characters may still
be limited by the build or compiler tools.
For example, a user may be limited by the build tools to
using characters within the Windows ANSI code page (which can
include non-ascii characters in the current system language).
