View Issue Details [ Jump to Notes ] [ Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006295CMakeDocumentationpublic2008-02-02 21:152008-03-13 09:09
ReporterBrandon Van Every 
Assigned ToBill Hoffman 
PriorityhighSeveritytextReproducibilityalways
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0006295: document core syntax in a chapter format
DescriptionPeople 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.
TagsNo tags attached.
Attached Files

 Relationships

  Notes
(0010498)
Alex Neundorf (developer)
2008-02-14 15:28

 Maybe one or two chapters from the cmake book could be put online, e.g. "KEY CONCEPTS" and "WRITING CMAKELISTS FILES" ?

Alex
(0010499)
Brandon Van Every (reporter)
2008-02-14 15:37

 And be sure to advertize that you can buy the book while you're at it to get the rest of the chapters. Include a weblink to where to buy the book straight from Kitware. Don't be shy. You can kill 2 birds with 1 stone: solve this doc problem *and* sell more copies of your book.
(0010781)
Bill Hoffman (manager)
2008-03-13 09:09

 This is now done here:
http://www.cmake.org/HTML/syntax.html [^]
and referenced here:
http://www.cmake.org/HTML/Documentation.html [^]

 Issue History
Date Modified Username Field Change
2008-02-02 21:15 Brandon Van Every New Issue
2008-02-14 15:28 Alex Neundorf Note Added: 0010498
2008-02-14 15:29 Alex Neundorf Category CMake => Documentation
2008-02-14 15:37 Brandon Van Every Note Added: 0010499
2008-02-15 10:30 Bill Hoffman Status new => assigned
2008-02-15 10:30 Bill Hoffman Assigned To => Bill Hoffman
2008-03-13 09:09 Bill Hoffman Status assigned => closed
2008-03-13 09:09 Bill Hoffman Note Added: 0010781
2008-03-13 09:09 Bill Hoffman Resolution open => fixed

Copyright © 2000 - 2018 MantisBT Team