Commit Graph

60 Commits

Author SHA1 Message Date
Nikita Nemkin
718043b540 Help: Convert some literal blocks into tables and lists
Also, ensure that header-less tables have a top border in cmake.css.
2025-01-31 12:23:29 -05:00
scivision
7be01178a0 Help: JSON argument should be quoted
The error that results from a semicolon anywhere in a JSON string
is not obvious.

Issue: #26628
2025-01-24 12:00:56 -05:00
Alex Turbov
c3777c1536 ci: Extend spellcheck job with 'typos' tool
Unlike the `codespell`, `typos` is capable of finding typos
in combined identifiers (`CamelCase` or `snake_case`).
2025-01-22 08:51:45 -05:00
Martin Stadler
dc7a810a75 Help: Clarify documentation on regex character classes
In particular, give an example of matching `]`.
2024-04-11 08:46:37 -04:00
Marc Chevrier
9702a01dc9 Help: string(LENGTH): Fix synopsis link to command description
Make the link target explicit to avoid ambiguity with `JSON LENGTH`.

Fixes: #25546
2024-01-03 14:14:18 -05:00
Leonid Pospelov
c64f6d5a5a Help: Document append functionality of string(JSON) 2023-05-03 04:41:53 -04:00
Matthew Woehlke
68fb1572a8 Help: Convert signatures of file command
Convert `file` command to use new `signature` directive. Use '<HASH>'
rather than 'HASH' for relevant signature targets, as this is arguably
more correct, results in less need to specify explicit targets, but
still produces '#hash' as the HTML anchor.

Although actual textual changes to `file` are fairly minimal, large
portions of the content have been re-indented and in many cases,
re-flowed. Some tabular content in literal text blocks has also been
converted to actual tables.
2023-03-15 10:53:25 -04:00
Matthew Woehlke
533ebb072b Help: Use signature directive for string command 2023-03-06 09:52:52 -05:00
Marc Chevrier
d36754e163 Merge topic 'doc-updates'
22d36aa0f8 Help: string(JSON): avoid duplicate labels

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !8028
2022-12-18 08:06:27 -05:00
Marc Chevrier
22d36aa0f8 Help: string(JSON): avoid duplicate labels 2022-12-17 12:42:36 +01:00
Vasiliy Koyrev
9da542d5c1 string(TIMESTAMP): Add %z and %Z for adding time zone string
Fixes: #24056
2022-10-27 11:13:46 -04:00
Brad King
7d25ae7350 Help: Add versionadded for string(TIMESTAMP) %f specifier
This was accidentally left out of commit c050d6a01e (string(TIMESTAMP):
add %f specifier for microseconds, 2022-01-27, v3.23.0-rc1~59^2).
2022-10-14 11:28:38 -04:00
Tobias Nießen
2f0a3d43e1 Help: Fix string(JSON ... LENGTH ...) signature
The list of indices and/or member names is optional, i.e., can be
empty. For example, string(JSON foo LENGTH "[0,0,0]") sets foo to 3.
2022-03-30 09:14:13 -04:00
Peter Würth
c050d6a01e string(TIMESTAMP): add %f specifier for microseconds
The %f specified extends the string(TIMESTAMP) and file(TIMESTAMP)
commands to output the timestamp with a microsecond resolution.
This convention is offered by python's datetime module.
Before, the precision was limited to seconds.

The implementation is done by extending existing cmTimestamp methods
with a `microseconds` parameter. This parameter is optional in order to
be backwards compatible. The timestamps are now received in a
cross-platform manner using libuv, since the standard C functions like
time() don't allow for sub-second precision.

This requires libuv 1.28 or higher.  We already require higher than
that on Windows, so update the required version for other platforms.

Implements: #19335
2022-01-28 06:23:57 -05:00
Antons Jeļkins
aafa392c12 string(TIMESTAMP): Add %V specifier for ISO 8601 week number
In ISO 8601 weeks begin with Monday. The first week of
the year is the week which contains the first Thursday
of the year.
2021-08-02 16:31:53 +02:00
Brad King
a915f691ad Help: Format string(TIMESTAMP) format specifiers as a definition list
Also fix the version that added `%A` and `%B`.
2021-07-23 12:03:25 -04:00
Nikita Nemkin
5000f93a91 Help: Fix grammar in .. versionadded directives
Issue: #19715
2020-12-02 21:00:31 +05:00
Nikita Nemkin
a19058d7d8 Help: Replace some versionadded directives with versionchanged
`.. 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
2020-11-12 09:44:01 +05:00
Nikita Nemkin
c705279bae Help: Add .. versionadded directives to commands documentation
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
2020-11-09 20:51:57 +05:00
Peter Steneteg
49fce3373b Help: Clarify string(JSON) error handling
Closes: #21355
2020-10-28 23:09:24 +11:00
Craig Scott
95c14579f2 Help: Cleanup typos and grammar for the 3.19 release 2020-10-24 22:58:42 +11:00
Peter Steneteg
8eab76eb84 string(JSON): Adds JSON parsing support to the string command
Adds a set of sub commands to the string command for parsing JSON, the
JSON commands are: GET, TYPE, MEMBER, LENGTH, REMOVE, SET, and EQUAL.

Closes: #19501
2020-09-16 13:55:24 -04:00
Kyle Edwards
5395bf05eb string: Add new HEX sub-command 2020-02-19 09:11:05 -05:00
Joachim Wuttke (o)
466b138ea2 Help: string: regex match and replace is a subcase of Search&Replace 2020-02-17 17:42:50 +01:00
Craig Scott
b97673f54b Help: Add note to each string() subcommand that assumes ASCII input
Fixes: #19465
2019-07-19 20:47:21 +10:00
Craig Scott
26cd64d977 Help: Fix language and formatting inconsistencies for string() command 2019-07-19 20:47:21 +10:00
Alex Turbov
536cca60ea string: introduce REPEAT sub-command 2019-04-15 11:06:06 -04:00
Joachim Wuttke (l)
c2efb3efcd Help: Revise docs on Scripting Commands
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
2018-10-23 15:12:10 +02:00
Brad King
fab2c2339b Help: Fix documentation of escape sequences in a regex
Documentation added by commit 4b35dab891 (Help: Document how escape
sequences work in a regex, 2018-07-18) is only correct for backslashes
inside `[]` groups.  The regex engine does interpret `\` escapes
elsewhere.  Fix the docs.

Inspired-by: R2RT <artur.ryt@gmail.com>
Fixes: #18428
2018-10-09 06:31:37 -04:00
Brad King
4b35dab891 Help: Document how escape sequences work in a regex
Our regex engine doesn't interpret `\`-escapes but CMake language escape
sequences may be used to pass literal whitespace characters to it.
2018-07-18 10:36:00 -04:00
Brad King
51c0e1407c Help: Add Synopsis section to install, list, and string docs
Summarize the command signatures in one block at the top of the
documentation as is typical in Unix command-line tool manuals.
Make the mode keywords links to the corresponding full signature
and documentation.

Issue: #17948
2018-05-07 10:10:37 -04:00
Yee Fan
20d90a9482 Help: Some spelling corrections for commands. 2018-04-21 00:37:09 +08:00
Marc Chevrier
a58158727b list(): add JOIN sub-command 2018-03-20 14:28:17 +01:00
Brad King
846a4dd118 Merge topic 'string-join'
689eeb67 string: Add JOIN subcommand

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Pavel Solodovnikov <hellyeahdominate@gmail.com>
Merge-request: !1762
2018-02-20 11:47:51 -05:00
Alex Turbov
689eeb67cb string: Add JOIN subcommand
This is just like CONCAT but accepts a glue string to put between
each value.  `JOIN ""` is equivalent to `CONCAT`.
2018-02-16 10:04:47 -05:00
Craig Scott
a71ab3be0e Help: Expand string(MAKE_C_IDENTIFIER) docs
The MAKE_C_IDENTIFIER subcommand was also buried in the docs for the
TIMESTAMP subcommand, so it has been pulled out to its own subheading.
2018-02-11 21:04:26 +11:00
Bernhard M. Wiedemann
014ad2989c Timestamp: support %A and %B
These are defined both by [1] and [2] to give full names of a weekday
and month.

[1] http://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html
[2] https://msdn.microsoft.com/de-de/library/fe06s4ak.aspx
2017-09-07 13:36:11 -04:00
Sylvain Joubert
d8ecc25457 Add PREPEND sub-command to string command 2017-08-11 13:26:33 +02:00
Brad King
eb08e1febb Help: Document CMAKE_MATCH_<n> variables 2017-04-18 14:45:49 -04:00
Brad King
8dd9975263 Help: Link from if(MATCHES) to regex specification docs 2017-04-18 14:45:04 -04:00
Brad King
a0091a697e Help: Format string() command regex specification docs 2017-04-18 14:44:50 -04:00
Bernhard M. Wiedemann
6c54f7b365 string: Teach TIMESTAMP to treat %% as %
This encoding is documented by `strptime`.
2017-01-27 09:25:37 -05:00
Bernhard M. Wiedemann
243aed525a cmTimestamp: Support SOURCE_DATE_EPOCH to override current time
See https://reproducible-builds.org/ for why this is good and
https://reproducible-builds.org/specs/source-date-epoch/ for the
definition of this variable.
2017-01-26 10:21:41 -05:00
Brad King
92f95aede9 string: Add support for SHA-3 algorithms 2016-11-10 16:40:43 -05:00
Brad King
979e8ba6c6 Help: De-duplicate and spell out supported hash algorithms
Spell out the supported algorithms in a definition list in the
`string(<HASH>)` command documentation.  Revise the `file(<HASH>)`
command and CPack module documentation to reference it instead of
duplicating the list.
2016-11-10 16:07:46 -05:00
Ruslan Baratov
751f7b5255 string(TIMESTAMP ...): add '%a' and '%b' format specifiers
%b: Abbreviated month name (e.g. Oct).
%a: Abbreviated weekday name (e.g. Fri).
2016-09-12 19:07:38 +03:00
Chuck Atkins
02d177c9cc Add additional <= and >= comparison operators
This adds the LESS_EQUAL, GREATER_EQUAL, and associated STR and VERSION
equivalents to use the combined <= and >= functionality.
2016-08-09 09:30:34 -04:00
Jose-Luis Blanco-Claraco
6727270b75 CMake: Extend TIMESTAMP sub-commands with new unix time format specifier
The new `%s` format specifier is substituted by file()/string()
`TIMESTAMP` sub-commands with the number of seconds since unix-epoch
(1970-01-01 00:00:00 UTC).

Co-Author: Nils Gladitz <nilsgladitz@gmail.com>
2016-02-18 10:30:13 -05:00
Brad King
3809150a38 Help: Document string(REGEX) input concatentation (#15742)
These commands concatenate all their input before matching.  Document
this behavior.
2015-09-14 10:37:59 -04:00
Brad King
5f2c47c44c Help: Organize string command docs into sections
Add section headers and titles for each command signature.  Group
related commands into sections.
2015-09-14 10:37:40 -04:00