CMake documentation work

docs/build.dox

@@ -148,6 +148,10 @@ uses OpenGL and `glu32` if it uses GLU.
 
 @subsection build_link_cmake_source With CMake and GLFW source
 
+This section is about using CMake to compile and link GLFW along with your
+application.  If you want to use an installed binary instead, see @ref
+build_link_cmake_module.
+
 With just a few changes to your `CMakeLists.txt` you can have the GLFW source
 tree built along with your application.
 
@@ -174,56 +178,54 @@ needs GLU, you can find it by requiring the OpenGL package.
 find_package(OpenGL REQUIRED)
 @endcode
 
-Once found, the GLU library path is stored in the `OPENGL_glu_LIBRARY` cache
-variable.
+If GLU is found, the `OPENGL_GLU_FOUND` variable is true and the
+`OPENGL_INCLUDE_DIR` and `OPENGL_glu_LIBRARY` cache variables can be used.
 
 @code{.cmake}
-target_link_libraries(myapp glfw ${OPENGL_glu_LIBRARY})
+target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
+target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
 @endcode
 
 
-@subsection build_link_cmake_pkgconfig With CMake on Unix and installed GLFW binaries
-
-CMake can import settings from pkg-config, which GLFW supports.  When you
-installed GLFW, the pkg-config file `glfw3.pc` was installed along with it.
-
-First you need to find the PkgConfig package.  If this fails, you may need to
-install the pkg-config package for your distribution.
+@subsection build_link_cmake_module With CMake and installed GLFW binaries
 
-@code{.cmake}
-find_package(PkgConfig REQUIRED)
-@endcode
+This section is about using CMake to link GLFW after it has been built and
+installed.  If you want to build it along with your application instead, see
+@ref build_link_cmake_source.
 
-This creates the CMake commands to find pkg-config packages.  Then you need to
-find the GLFW package.
+With just a few changes to your `CMakeLists.txt`, you can locate the module and
+target files generated when GLFW is installed.
 
 @code{.cmake}
-pkg_search_module(GLFW REQUIRED glfw3)
+find_package(glfw3 3.2 REQUIRED)
 @endcode
 
-This creates the CMake variables you need to use GLFW.  To be able to include
-the GLFW header, you need to tell your compiler where it is.
+Once GLFW has been located, link against it with the `glfw` target.  This adds
+all link-time dependencies of GLFW as it is currently configured, the include
+directory for the GLFW header and, when applicable, the
+[GLFW_DLL](@ref build_macros) macro.
 
 @code{.cmake}
-include_directories(${GLFW_INCLUDE_DIRS})
+target_link_libraries(myapp glfw)
 @endcode
 
-You also need to link against the correct libraries.  If you are using the
-shared library version of GLFW, use the `GLFW_LIBRARIES` variable.
+Note that it does not include GLU, as GLFW does not use it.  If your application
+needs GLU, you can find it by requiring the OpenGL package.
 
 @code{.cmake}
-target_link_libraries(simple ${GLFW_LIBRARIES})
+find_package(OpenGL REQUIRED)
 @endcode
 
-If you are using the static library version of GLFW, use the
-`GLFW_STATIC_LIBRARIES` variable instead.
+If GLU is found, the `OPENGL_GLU_FOUND` variable is true and the
+`OPENGL_INCLUDE_DIR` and `OPENGL_glu_LIBRARY` cache variables can be used.
 
 @code{.cmake}
-target_link_libraries(simple ${GLFW_STATIC_LIBRARIES})
+target_include_directories(myapp ${OPENGL_INCLUDE_DIR})
+target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
 @endcode
 
 
-@subsection build_link_pkgconfig With pkg-config on OS X or other Unix
+@subsection build_link_pkgconfig With makefiles and pkg-config on Unix
 
 GLFW supports [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/),
 and the `glfw3.pc` pkf-config file is generated when the GLFW library is built