With some of the content expanded, reorder a few paragraphs
and tweak some of the wording to improve the flow.
Co-Authored-By: Craig Scott <craig.scott@crascit.com>
`.. versionchanged` directive might be more appropriate when
documentation refers to previous CMake version, old behavior
or a policy, and there's no new parameter or a variable involved.
Issue: #19715
This change ony concerns directives that appear in the document body.
The guidelines for inserting version directives:
* Baseline version is CMake 3.0, i.e. directives start at 3.1.
* Always use `.. versionadded::` directive, avoid ad-hoc version
references. Exception: policy pages.
* For new command signatures, put `versionadded` on a separate line
after the signature.
* For a group of new signatures in a new document section,
a single version note at the beginning of the section is sufficient.
* For new options, put `versionadded` on a separate line before
option description.
* If all the option descriptions in the list are short one-liners,
it's fine to put `versionadded` on the same line as the description.
* If multiple option descriptions in close proximity would have
the same ..versionadded directive, consider adding a single
directive after the list, mentioning all added options.
* For compact value lists and sub-option lists, put a single
`versionadded` directive after the list mentioning all additions.
* When a change is described in a single paragraph, put
`versionadded` into that paragraph.
* When only part of the paragraph has changed, separate the changed
part if it doesn't break the flow. Otherwise, write a follow-up
clarification paragraph and apply version directive to that.
* When multiple version directives are close by, order earlier
additions before later additions.
* Indent related lists and code blocks to include them in the scope
of `versionadded` directive.
Issue: #19715
Previously the command considered non-absolute source file paths relative to
the associated target on the LHS. This causes problems in incremental builds
where files are added from subdirectories and forces users to workaround by
manually converting to absolute paths. Change this to enable more intuitive
usage by projects.
Fixes#17981
Now, several `INTERFACE_*` properties can be set on `IMPORTED` targets,
not only via `set_property` and `set_target_properties` but also via
`target_compile_definitions`, `target_compile_features`,
`target_compile_options`, `target_include_directories`, `target_sources`
and `target_link_libraries`.
Fixes: #15689
Issue: #17197
