Skip to content

Help: Restructure and improve generator expressions manual

I have been increasingly finding the generator expressions manual hard to use. With the significant amount of new expressions added for 3.24, this has now reached a critical point for me where the existing structure seemed to pretty much break down. There was enough inconsistency in where to find things that I couldn't keep any sort of meaningful mental model of how things were located. I decided to try a different approach and restructured it around a more task-based format to see what others think of this alternative. This keeps related things closer together, and I believe more closely maps to how users will work with the manual.

With the new structure, the manual moves more descriptive and foundational content to the beginning. The detailed reference then follows after that. I also added a new section about whitespace and quoting, since problems related to that area come up in the forums reasonably often. The previous example that used -I$<JOIN:...> was also found to be problematic in this area. I chose to expand that example, improve it, and add another example to hopefully steer users away from the common problems that previous example led to.

The $<CUDA_COMPILER_VERSION> and $<CUDA_COMPILER_ID> expressions were missing versionadded directives, so I added them. Previously, only their associated $<CUDA_COMPILER_VERSION:version> and $<CUDA_COMPILER_ID:ids> expressions had those directives. The omission only became obvious after the two closely related expressions were moved next to each other in the restructuring.

A few minor typo fixes, grammatical improvements and cross-references pointing to the wrong things were addressed along the way.

Backport: release

Edited by Brad King

Merge request reports