Made it more obvious that this file is a cmake tutorial. Also added a few...

Made it more obvious that this file is a cmake tutorial.  Also added a few more comments about how to use cmake.

examples/CMakeLists.txt

 #
-# This is a CMake makefile.  You can find the cmake utility and
-# information about it at http://www.cmake.org
+#  _______ _    _ _____  _____     _____  _____                 
+# |__   __| |  | |_   _|/ ____|   |_   _|/ ____|       /\       
+#    | |  | |__| | | | | (___       | | | (___        /  \      
+#    | |  |  __  | | |  \___ \      | |  \___ \      / /\ \     
+#    | |  | |  | |_| |_ ____) |    _| |_ ____) |    / ____ \    
+#    |_|__|_|_ |_|_____|_____/__  |_____|_____/    /_/  _ \_\   
+#   |__   __| |  | |__   __/ __ \|  __ \|_   _|   /\   | |      
+#      | |  | |  | |  | | | |  | | |__) | | |    /  \  | |      
+#      | |  | |  | |  | | | |  | |  _  /  | |   / /\ \ | |      
+#      | |  | |__| |  | | | |__| | | \ \ _| |_ / ____ \| |____  
+#      |_|   \____/   |_|  \____/|_|  \_\_____/_/    \_\______| 
+#
+#
+#    _____  ______          _____      _______ _    _ ______       
+#   |  __ \|  ____|   /\   |  __ \    |__   __| |  | |  ____|      
+#   | |__) | |__     /  \  | |  | |      | |  | |__| | |__         
+#   |  _  /|  __|   / /\ \ | |  | |      | |  |  __  |  __|        
+#   | | \ \| |____ / ____ \| |__| |      | |  | |  | | |____       
+#   |_|__\_\______/_/_ __\_\_____/__ _   |_|__|_|_ |_|______|_ _ _ 
+#  / ____/ __ \|  \/  |  \/  |  ____| \ | |__   __/ ____| | | | | |
+# | |   | |  | | \  / | \  / | |__  |  \| |  | | | (___   | | | | |
+# | |   | |  | | |\/| | |\/| |  __| | . ` |  | |  \___ \  | | | | |
+# | |___| |__| | |  | | |  | | |____| |\  |  | |  ____) | |_|_|_|_|
+#  \_____\____/|_|  |_|_|  |_|______|_| \_|  |_| |_____/  (_|_|_|_)
+#                                                                  
+#
+#
+# This is a CMake makefile.  CMake is a tool that helps you build C++ programs.
+# You can download CMake from http://www.cmake.org.  This CMakeLists.txt file
+# you are reading builds dlib's example programs. 
 #
 
 
 cmake_minimum_required(VERSION 2.8.12)
+# Every project needs a name.  We call this the "examples" project.
+project(examples)
 
-PROJECT(examples)
 
+# Tell cmake we will need dlib.  This command will pull in dlib and compile it
+# into your project.  Note that you don't need to compile or install dlib.  All
+# it needs is the dlib source code folder and it will take care of everything.
 include(../dlib/cmake)
 
-# Tell CMake to compile a program.  We do this with the ADD_EXECUTABLE()
-# statement which takes the name of the output executable and then a list of
-# .cpp files to compile.  Here each example consists of only one .cpp file but
-# in general you will make programs that const of many .cpp files.
-ADD_EXECUTABLE(assignment_learning_ex assignment_learning_ex.cpp)
-# Then we tell it to link with dlib.
-TARGET_LINK_LIBRARIES(assignment_learning_ex dlib::dlib)
+
+# The next thing we need to do is tell CMake about the code you want to
+# compile.  We do this with the add_executable() statement which takes the name
+# of the output executable and then a list of .cpp files to compile.  Here we
+# are going to compile one of the dlib example programs which has only one .cpp
+# file, assignment_learning_ex.cpp.  If your program consisted of multiple .cpp
+# files you would simply list them here in the add_executable() statement.  
+add_executable(assignment_learning_ex assignment_learning_ex.cpp)
+# Finally, you need to tell CMake that this program, assignment_learning_ex,
+# depends on dlib.  You do that with this statement: 
+target_link_libraries(assignment_learning_ex dlib::dlib)
+
+
+
+# To compile this program all you need to do is ask cmake.  You would type
+# these commands from within the directory containing this CMakeLists.txt
+# file:
+#   mkdir build
+#   cmake ..
+#   cmake --build . --config Release
+#
+# The cmake .. command looks in the parent folder for a file named
+# CMakeLists.txt, reads it, sets up everything needed to build program.  Also,
+# note that CMake can also generate Visual Studio or XCode project files.  So
+# if instead you had written:
+#   mkdir build
+#   cmake .. -G "Visual Studio 14 2015 Win64" ..
+#
+# You would be able to open the resulting visual studio project and compile and
+# edit the example programs within the visual studio IDE.  CMake can generate a
+# lot of different types of IDE projects.  Run the cmake -h command to see a list
+# of arguments to -G to see what kinds of projects cmake can generate for you.
+# It probably includes your favorite IDE in the list.
+
+
 
 
+#################################################################################
+#################################################################################
+#  A CMakeLists.txt file can compile more than just one program.  So below we
+#  tell it to compile the other dlib example programs using pretty much the
+#  same CMake commands we used above.
+#################################################################################
+#################################################################################
 
 
 # Since there are a lot of examples I'm going to use a macro to simply this
 # CMakeLists.txt file.  However, usually you will create only one executable in
 # your cmake projects and use the syntax shown above.
-MACRO(add_example name)
-   ADD_EXECUTABLE(${name} ${name}.cpp)
-   TARGET_LINK_LIBRARIES(${name} dlib::dlib )
-ENDMACRO()
+macro(add_example name)
+   add_executable(${name} ${name}.cpp)
+   target_link_libraries(${name} dlib::dlib )
+endmacro()
 
 # if an example requires GUI, call this macro to check DLIB_NO_GUI_SUPPORT to include or exclude
-MACRO(add_gui_example name)
+macro(add_gui_example name)
    if (DLIB_NO_GUI_SUPPORT)
       message("No GUI support, so we won't build the ${name} example.")
    else()
       add_example(${name})
    endif()
-ENDMACRO()
+endmacro()
 
 # The deep learning toolkit requires a compiler with essentially complete C++11
 # support.  However, versions of Visual Studio prior to October 2016 didn't
@@ -62,6 +129,23 @@ if (NOT USING_OLD_VISUAL_STUDIO_COMPILER)
    endif()
 endif()
 
+
+if (DLIB_NO_GUI_SUPPORT)
+   message("No GUI support, so we won't build the webcam_face_pose_ex example.")
+else()
+   find_package(OpenCV QUIET)
+   if (OpenCV_FOUND)
+      include_directories(${OpenCV_INCLUDE_DIRS})
+
+      add_executable(webcam_face_pose_ex webcam_face_pose_ex.cpp)
+      target_link_libraries(webcam_face_pose_ex dlib::dlib ${OpenCV_LIBS} )
+   else()
+      message("OpenCV not found, so we won't build the webcam_face_pose_ex example.")
+   endif()
+endif()
+
+
+
 #here we apply our macros 
 add_gui_example(3d_point_cloud_ex)
 add_example(bayes_net_ex)
@@ -146,21 +230,6 @@ add_gui_example(video_tracking_ex)
 add_example(xml_parser_ex)
 
 
-if (DLIB_NO_GUI_SUPPORT)
-   message("No GUI support, so we won't build the webcam_face_pose_ex example.")
-else()
-   find_package(OpenCV QUIET)
-   if (OpenCV_FOUND)
-      include_directories(${OpenCV_INCLUDE_DIRS})
-
-      ADD_EXECUTABLE(webcam_face_pose_ex webcam_face_pose_ex.cpp)
-      TARGET_LINK_LIBRARIES(webcam_face_pose_ex dlib::dlib ${OpenCV_LIBS} )
-   else()
-      message("OpenCV not found, so we won't build the webcam_face_pose_ex example.")
-   endif()
-endif()
-
-
 if (DLIB_LINK_WITH_SQLITE3)
    add_example(sqlite_ex)
 endif()