Lately I’ve been thinking about the HTML documentation and how it’s organized.
Comparing a page like cmake-generator-expressions(7) to the property or variable documentation pages, or comparing those to the output of
man cmake-variables or
man cmake-properties from a (Linux) command line, two things occur to me:
- The property and variable documentation is broken up at the wrong level
- It’s disappointing that only documentation broken up at that level is fully organized and indexed
What I mean by the first is that it’s far more comfortable to scroll through a page like the generator expression documentation or the
cmake-variables(7) man page, than it is to click around to individual, isolated pages each documenting a single property or variable. Back when CMake was first created the page-per-variable/property organization no doubt made sense, but these days a page that only documents a single variable or property feels like it’s presenting too little information, and with too little context. (In part because 90% of those pages are barely a paragraph of text, and don’t really need to be any longer.)
(I’m tempted to include policies as well, but honestly there’s far less value to seeing a given policy’s documentation in the context of other policies, since they’re identified only by number and each policy is a standalone item. There may be a couple of exceptions, but policies are generally not interrelated. The primary value in consolidating properties or variables is when an item is only one of a set of closely-related items, in which case it can be useful to view them all together.)
What I mean by the second point is that, because the generator expressions are all documented on a single page instead of broken up, there’s no
cmake --help-generator-expression-list, and no
cmake --help-generator-expression name to view the documentation for a specific expression. It’s the (IMHO uncomfortably-)fine granularity of the property and variable documentation that allows individual docs to be queried. (Interestingly, though, there are already differences there: the existing documentation has the property docs stored in subdirectories by type —
prop_cache, etc. — whereas the variables are all lumped into a single directory
Well, right up front: Does anyone disagree that the current page-per-item organization feels anemic? Do you prefer pages like
CMAKE_BUILD_TOOL to a page like cmake-generator-expressions(7)? This would hardly be the first time in my life that something has felt obvious to me, only to discover that I’m actually in a small minority of opinion. If the current organization is preferable to most users, I’ll shut up and deal with it.
Assuming I’m not alone in this, I’d like to propose a change. It will probably be tricky, with Sphinx, but I hope not impossible. The exact design can be fleshed out collaboratively in Gitlab, if this is undertaken, but my personal goals/requirements would broadly be:
Consolidate documentation on individual properties/variables into longer lists of multiple items. Probably not all on one page, but perhaps broken up along the lines of the current
cmake-properties(7)sections: “Properties of Global Scope”, “Properties on Targets”, “Variables that Provide Information”, “Variables that Control the Build”, etc. each become one page.
Ensure that a URL can still be given for each individual property/variable, though it may target an anchor on a larger page. So, instead of:
it might be:
but there would still be a way to link to “the
CMAKE_COMMANDdocumentation” specifically, in the online help.
The version-switcher in the online documentation would still function properly, and be able to navigate between separated and consolidated documentation for the same property/variable. I think this should be achievable with some modifications to
version_switch.js. (Though “some modifications” may be underselling it, as it would probably need at least a list of recognized property/variable categories. In the absence of the next item, it might need a list of every property and variable name so it could map them directly to/from the correct section pages.)
That would allow a request for
.../variable/CMAKE_INSTALL_PREFIX.htmlto be referred over to
.../var_behavior.html#CMAKE_INSTALL_PREFIX, instead of producing a 404 page. There are doubtless plenty of bookmarks and links to
https://cmake.org/cmake/help/latest/paths out in the wild, so those URLs should ideally remain valid.
cmake --helpfunctionality isn’t broken. Perhaps documentation files per property/variable are still written out to disk for use by the
cmDocumentationclass. Or, perhaps the documentation lists are converted to a parseable format like JSON that it can load to retrieve individual item docs.
cmake --help-foo namefunctionality is extended to the generator expressions, and to other smaller-than-a-page granularity items if any good candidates are identified.
The man pages shouldn’t change. This should be a no-brainer, since the manpage generator already combines all of the property/variable docs into a single file; it’d just be a matter of assembling it out of the longer consolidated pages, rather than the individual pages.
There’s probably more, but I figure that’s a start, and enough for people to react to and/or poke holes in. (Equally welcome!)