[CMake] Current documentation and module standards

[Hendrik Sattler]

Hi,

Reading through the updated  
http://www.cmake.org/HTML/Documentation.html, there are several  
problems:
1.
UsePkgConfig is not marked deprecated. One may get the idea that both  
FindPkgConfig and UsePkgConfig are needed.

2.
There are several FindSDL_* modules vs. one FindQt4 and one  
FindwxWindows (that should be renamed to FindwxWidgets, btw) that both  
use *_USE_* variable for additional stuff.

3.
What is the FindJava about? Looking at the PROJECT call, there seems  
to be native Java support, so FindJava is for what?

4.
Variables are _INCLUDE_DIR for one module (e.g. FindJPEG) and  
_INCLUDE_PATH for another (e.g. FindJNI). That should be standardized  
to one or the other. Maybe define both where compatibility is needed  
but only document the fixed one.

5.
What is the difference between OPTION (VARX "some text") and the  
setting a boolean cache variable that can be changed by the user?

6.
For FIND_PACKAGE, major.minor is undocumented.


CMake is definitely missing some interface standards enforcement. At  
least the standards that are shipped with CMake should have such a  
standard.
I also noted some strange things on other pages.

http://www.cmake.org/HTML/WritingCMakeLists.html:
- It states inclusion with "INCLUDE  
(${CMAKE_ROOT}/Modules/FindTCL.cmake)" instead of using "FIND_PACKAGE  
( TCL )".
- The second last line on that page suggests usage of SUBDIRS although  
the documentation says to use ADD_SUBDIRECTORY instead.


http://www.cmake.org/HTML/RunningCMake.html:
- That first screenshot is really old. It should be updated. The text  
above that should be updated, too, as there are currently much more  
generators available.


http://www.cmake.org/HTML/Install.html:
- Somehow, the combination of MSYS+mingw32 is always forgotten as a  
valid alternative to cygwin. With this combination, you can also build  
cmake from CVS (although running bootstrap did not build the  
CMakeSetup.exe or maybe I did something wrong).

HS