| Description | People who do not know CMake often have the impression that it will be difficult to learn. In particular, they make comparisons to learning Python, Ruby, Lua, Perl, or some other popular scripting language. The difference is, programmers are motivated to learn popular scripting languages, because they know their learning curve will be leveraged into other projects. CMake has to be learned for its own sake, it has no value apart from CMake, so people resist learning it.
If CMake had a chapter documenting its core syntax, then the world could see that CMake is a simple, indeed a trivial programming language. This would lower objections to learning and using CMake syntax, as compared to other languages.
The chapter should also endeavor to separate the concern of *syntax* from that of *build capabilities*. Any build tool has a pile of capabilities that needs to be learned. This doesn't change no matter what scripting language is used. The chapter could have a preamble emphasizing the difference, and how little syntax there really is to learn.
That there is little syntax to learn, may seem obvious to some people from scanning the documentation. But realize that 1st time CMake users are floundering and know nothing about what's going on. They look at a big long webpage of commands, and "what's the syntax" doesn't jump out at them. As they try to "learn by doing," it is entirely possible that they'll burn themselves on list-semicolon issues, or on escape issues. CMake syntax is simple, but there are indeed some pitfalls worth knowing about. If they burn themselves, then it creates frustration. Often enough frustration for them to drop CMake entirely and try something else, such as the Lua-based Premake, or the Python-based SCons.
"What's the syntax" is typically a trivial, boring part of the documentation. Nevertheless it should be present. Programmers need the psychological assurance that a new technology is indeed simple, that they can indeed skip over that section of the docs, that it's pretty much like every other language they've ever looked at. With the possible exception of some list, quote, and escape conventions that they'll refer to when they need to.
The wiki can be used to prototype the chapter. The wiki currently has some entries on syntax, but they are incomplete, haphazard, and unprofessional. The prototype wiki page also needs to be displayed prominently on the wiki site, not buried as just another page among many. Once the prototype is of sufficient quality, it needs to be integrated with the core documentation shipped with CMake. Links to the chapter should be provided in appropriate places, such as are currently provided for the FAQ and so forth.
It might be advisable to crib a chapter or part of a chapter from the "Mastering CMake" book, if the book discusses syntax. In addition to reducing development time and cost, the cribbed chapter could include a sales pitch for the "Mastering CMake" book.
|