Skip to content

Help: Restructure and clarify cmake_path() docs

Craig Scott requested to merge craig.scott/cmake:cmake_path_docs into master

Restructured and reworked the docs. Main points to note:

  • I moved the synopsis close to the top, since this is where most people expect it and it makes for more convenient navigation.
  • I added a few sections to capture the details that are not specific to a single command. Putting section headings for these also meant they could be listed in the synopsis. The previous structure put all this information at the top, but the reader didn't necessarily know why they had to get all that information until they started looking at some of the commands. The headings and restructuring hopefully makes that less of an issue now. I also moved the definition of normalization to its own section as part of this work, which I think is more consistent overall.
  • Since the query subcommands are quite closely related to the decomposition subcommands, I moved the Query section to just after Decomposition.
  • I moved the COMPARE form into the Query section, since it is essentially still a form of query. If you want to still retain this as its own section, I won't object, but it felt a little strange that it got its own dedicated section.
  • For the GET subcommands, I grouped the syntax forms together and removed the previous descriptions that were not adding a lot of value by just more or less repeating the syntax in prose. This makes that section more concise and also allowed some of the examples to be combined. Having all the examples together also seems to make it easier to digest and compare the different forms.
  • Reformatting done to make things conform more closely with the dev documentation guidelines.

Further comments to follow shortly on specific items.

Related: #21385 (closed)

Edited by Craig Scott

Merge request reports