Separate guide and reference documentation tags

docs/build.dox

@@ -1,13 +1,13 @@
 /*!
 
-@page build Building applications
+@page build_guide Building applications
 
 @tableofcontents
 
 This is about compiling and linking applications that use GLFW.  For information on
-how to write such applications, start with the [introductory tutorial](@ref quick).
-For information on how to compile the GLFW library itself, see the @ref compile
-guide.
+how to write such applications, start with the
+[introductory tutorial](@ref quick_guide).  For information on how to compile
+the GLFW library itself, see @ref compile_guide.
 
 This is not a tutorial on compilation or linking.  It assumes basic
 understanding of how to compile and link a C program as well as how to use the

docs/compat.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page compat Standards conformance
+@page compat_guide Standards conformance
 
 @tableofcontents
 

docs/compile.dox

@@ -1,11 +1,11 @@
 /*!
 
-@page compile Compiling GLFW
+@page compile_guide Compiling GLFW
 
 @tableofcontents
 
 This is about compiling the GLFW library itself.  For information on how to
-build applications that use GLFW, see the @ref build guide.
+build applications that use GLFW, see @ref build_guide.
 
 
 @section compile_cmake Using CMake
@@ -156,7 +156,7 @@ necessary to compile GLFW.  Go ahead and compile the actual GLFW library with
 these files, as you would with any other project.
 
 Once the GLFW library is compiled, you are ready to build your applications,
-linking it to the GLFW library.  See the @ref build guide for more information.
+linking it to the GLFW library.  See @ref build_guide for more information.
 
 
 @subsection compile_options CMake options

docs/context.dox

@@ -1,16 +1,19 @@
 /*!
 
-@page context Context guide
+@page context_guide Context guide
 
 @tableofcontents
 
 This guide introduces the OpenGL and OpenGL ES context related functions of
-GLFW.  There are also guides for the other areas of the GLFW API.
+GLFW.  For details on a specific function, see the
+[reference documentation](@ref context).  There are also guides for the other
+areas of the GLFW API.
 
- - @ref intro
- - @ref window
- - @ref monitor
- - @ref input
+ - @ref intro_guide
+ - @ref window_guide
+ - @ref vulkan_guide
+ - @ref monitor_guide
+ - @ref input_guide
 
 
 @section context_object Context objects
@@ -29,7 +32,7 @@ the `glfwinfo` test program.
 @note Vulkan does not have a context and the Vulkan instance is created via the
 Vulkan API itself.  If you will be using Vulkan to render to a window, disable
 context creation by setting the [GLFW_CLIENT_API](@ref window_hints_ctx) hint to
-`GLFW_NO_API`.  For more information, see the @ref vulkan.
+`GLFW_NO_API`.  For more information, see the @ref vulkan_guide.
 
 
 @subsection context_hints Context creation hints

docs/input.dox

@@ -1,16 +1,17 @@
 /*!
 
-@page input Input guide
+@page input_guide Input guide
  
 @tableofcontents
 
-This guide introduces the input related functions of GLFW.  There are also
-guides for the other areas of GLFW.
+This guide introduces the input related functions of GLFW.  For details on
+a specific function, see the [reference documentation](@ref input).  There are
+also guides for the other areas of GLFW.
 
- - @ref intro
- - @ref window
- - @ref context
- - @ref monitor
+ - @ref intro_guide
+ - @ref window_guide
+ - @ref context_guide
+ - @ref monitor_guide
 
 GLFW provides many kinds of input.  While some can only be polled, like time, or
 only received via callbacks, like scrolling, there are those that provide both

docs/internal.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page internals Internal structure
+@page internals_guide Internal structure
 
 @tableofcontents
 

docs/intro.dox

@@ -1,18 +1,21 @@
 /*! 
 
-@page intro Introduction to the API
+@page intro_guide Introduction to the API
  
 @tableofcontents
 
-This guide introduces the basic concepts of GLFW and describes initialization,
+This guide introduces the basic concepts of GLFW and describes initialization reference
 error handling and API guarantees and limitations.  For a broad but shallow
-tutorial, see @ref quick instead.  There are also guides for the other areas of
-GLFW.
+tutorial, see @ref quick_guide instead.  For details on a specific function, see the
+[reference documentation](@ref init).
 
- - @ref window
- - @ref context
- - @ref monitor
- - @ref input
+There are also guides for the other areas of GLFW.
+
+ - @ref window_guide
+ - @ref context_guide
+ - @ref vulkan_guide
+ - @ref monitor_guide
+ - @ref input_guide
 
 
 @section intro_init Initialization and termination

docs/main.dox

@@ -11,20 +11,20 @@ for creating windows, contexts and surfaces, reading input, handling events, etc
 See @ref news_32 for release highlights or the
 [version history](http://www.glfw.org/changelog.html) for details.
 
-@ref quick is a guide for those new to GLFW.  It takes you through how to write
-a small but complete program.  For people coming from GLFW 2, the @ref moving
-guide explains what has changed and how to update existing code to use the new
-API.
+@ref quick_guide is a guide for those new to GLFW.  It takes you through how to
+write a small but complete program.  For people coming from GLFW 2, @ref
+moving_guide explains what has changed and how to update existing code to use
+the new API.
 
 There are guides for each of the various areas of the API.
 
- - @ref intro – initialization, error handling and high-level design
- - @ref window – creating and working with windows and framebuffers
- - @ref context – working with OpenGL and OpenGL ES contexts
- - @ref monitor – enumerating and working with monitors and video modes
- - @ref input – receiving events, polling and processing input
+ - @ref intro_guide – initialization, error handling and high-level design
+ - @ref window_guide – creating and working with windows and framebuffers
+ - @ref context_guide – working with OpenGL and OpenGL ES contexts
+ - @ref monitor_guide – enumerating and working with monitors and video modes
+ - @ref input_guide – receiving events, polling and processing input
 
-Once you have written a program, see the @ref compile and @ref build guides.        
+Once you have written a program, see @ref compile_guide and @ref build_guide.
 
 The [reference documentation](modules.html) provides more detailed information
 about specific functions.
@@ -32,15 +32,15 @@ about specific functions.
 There is a section on @ref guarantees_limitations for pointer lifetimes,
 reentrancy, thread safety, event order and backward and forward compatibility.
 
-The @ref vulkan guide fills in the gaps for how to use Vulkan with GLFW.
+The @ref vulkan_guide guide fills in the gaps for how to use Vulkan with GLFW.
 
-The @ref rift fills in the gaps for how to use LibOVR with GLFW.
+The @ref rift_guide fills in the gaps for how to use LibOVR with GLFW.
 
 The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
 design, implementation and use of GLFW.
 
-Finally, the @ref compat guide explains what APIs, standards and protocols GLFW
-uses and what happens when they are not present on a given machine.
+Finally, the @ref compat_guide guide explains what APIs, standards and protocols
+GLFW uses and what happens when they are not present on a given machine.
 
 This documentation was generated with Doxygen.  The sources for it are available
 in both the [source distribution](http://www.glfw.org/download.html) and

docs/monitor.dox

@@ -1,16 +1,17 @@
 /*!
 
-@page monitor Monitor guide
+@page monitor_guide Monitor guide
 
 @tableofcontents
 
-This guide introduces the monitor related functions of GLFW.  There are also
-guides for the other areas of GLFW.
+This guide introduces the monitor related functions of GLFW.  For details on
+a specific function, see the [reference documentation](@ref monitor).  There are
+also guides for the other areas of GLFW.
 
- - @ref intro
- - @ref window
- - @ref context
- - @ref input
+ - @ref intro_guide
+ - @ref window_guide
+ - @ref context_guide
+ - @ref input_guide
 
 
 @section monitor_object Monitor objects

docs/moving.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page moving Moving from GLFW 2 to 3
+@page moving_guide Moving from GLFW 2 to 3
 
 @tableofcontents
 
@@ -130,7 +130,7 @@ GLFW 3 provides support for multiple monitors.  To request a full screen mode wi
 instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
 window to use.  The @ref glfwGetPrimaryMonitor function returns the monitor that
 GLFW 2 would have selected, but there are many other
-[monitor functions](@ref monitor).  Monitor handles are pointers to the
+[monitor functions](@ref monitor_guide).  Monitor handles are pointers to the
 [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor.
 
 @par Old basic full screen

docs/news.dox

@@ -96,7 +96,7 @@ and the cursor position directly instead of returning cached data.
 @subsection news_31_libovr Better interoperability with Oculus Rift
 
 GLFW now provides native access functions for the OS level handles corresponding
-to monitor objects, as well as a [brief guide](@ref rift).  It is also regularly
+to monitor objects, as well as the @ref rift_guide.  It is also regularly
 tested for compatibility with the latest version of LibOVR (0.4.4 on release).
 
 

docs/quick.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page quick Getting started
+@page quick_guide Getting started
 
 @tableofcontents
 
@@ -10,7 +10,7 @@ and exit when the user closes the window or presses _Escape_.  This guide will
 introduce a few of the most commonly used functions, but there are many more.
 
 This guide assumes no experience with earlier versions of GLFW.  If you
-have used GLFW 2 in the past, read the @ref moving guide, as some functions
+have used GLFW 2 in the past, read @ref moving_guide, as some functions
 behave differently in GLFW 3.
 
 
@@ -346,11 +346,11 @@ This tutorial used only a few of the many functions GLFW provides.  There are
 guides for each of the areas covered by GLFW.  Each guide will introduce all the
 functions for that category.
 
- - @ref intro
- - @ref window
- - @ref context
- - @ref monitor
- - @ref input
+ - @ref intro_guide
+ - @ref window_guide
+ - @ref context_guide
+ - @ref monitor_guide
+ - @ref input_guide
 
 You can access reference documentation for any GLFW function by clicking it and
 the reference for each function links to related functions and guide sections.
@@ -359,6 +359,6 @@ The tutorial ends here.  Once you have written a program that uses GLFW, you
 will need to compile and link it.  How to do that depends on the development
 environment you are using and is best explained by the documentation for that
 environment.  To learn about the details that are specific to GLFW, see
-@ref build.
+@ref build_guide.
 
 */

docs/rift.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page rift Oculus Rift guide
+@page rift_guide Oculus Rift guide
  
 @tableofcontents
 

docs/vulkan.dox

@@ -1,6 +1,6 @@
 /*!
 
-@page vulkan Vulkan guide
+@page vulkan_guide Vulkan guide
  
 @tableofcontents
 
@@ -18,6 +18,16 @@ The GLFW library does not need the Vulkan SDK to enable support for Vulkan.
 However, any Vulkan-specific test and example programs are built only if the
 CMake files find a Vulkan SDK.
 
+For details on a specific function, see the
+[reference documentation](@ref vulkan).  There are also guides for the other
+areas of the GLFW API.
+
+ - @ref intro_guide
+ - @ref window_guide
+ - @ref context_guide
+ - @ref monitor_guide
+ - @ref input_guide
+
 
 @section vulkan_include Including the Vulkan and GLFW header files
 

docs/window.dox

@@ -1,16 +1,17 @@
 /*!
 
-@page window Window guide
+@page window_guide Window guide
  
 @tableofcontents
 
-This guide introduces the window related functions of GLFW.  There are also
-guides for the other areas of GLFW.
+This guide introduces the window related functions of GLFW.  For details on
+a specific function, see the [reference documentation](@ref window).  There are
+also guides for the other areas of GLFW.
 
- - @ref intro
- - @ref context
- - @ref monitor
- - @ref input
+ - @ref intro_guide
+ - @ref context_guide
+ - @ref monitor_guide
+ - @ref input_guide
 
 
 @section window_object Window objects

include/GLFW/glfw3.h

@@ -46,37 +46,37 @@ extern "C" {
  *
  *  For more information about how to use this file, see @ref build_include.
  */
-/*! @defgroup context Context handling
+/*! @defgroup context Context reference
  *
- *  This is the reference documentation for context related functions.  For more
- *  information, see the @ref context.
+ *  This is the reference documentation for OpenGL and OpenGL ES context related
+ *  functions.  For more task-oriented information, see the @ref context_guide.
  */
-/*! @defgroup vulkan Vulkan support
+/*! @defgroup vulkan Vulkan reference
  *
- *  This is the reference documentation for Vulkan related functions.  For more
- *  information, see the @ref vulkan.
+ *  This is the reference documentation for Vulkan related functions and types.
+ *  For more task-oriented information, see the @ref vulkan_guide.
  */
-/*! @defgroup init Initialization, version and errors
+/*! @defgroup init Initialization, version and error reference
  *
  *  This is the reference documentation for initialization and termination of
- *  the library, version management and error handling.  For more information,
- *  see the @ref intro.
+ *  the library, version management and error handling.  For more task-oriented
+ *  information, see the @ref intro_guide.
  */
-/*! @defgroup input Input handling
+/*! @defgroup input Input reference
  *
  *  This is the reference documentation for input related functions and types.
- *  For more information, see the @ref input.
+ *  For more task-oriented information, see the @ref input_guide.
  */
-/*! @defgroup monitor Monitor handling
+/*! @defgroup monitor Monitor reference
  *
  *  This is the reference documentation for monitor related functions and types.
- *  For more information, see the @ref monitor.
+ *  For more task-oriented information, see the @ref monitor_guide.
  */
-/*! @defgroup window Window handling
+/*! @defgroup window Window reference
  *
  *  This is the reference documentation for window related functions and types,
- *  including creation, deletion and event polling.  For more information, see
- *  the @ref window.
+ *  including creation, deletion and event polling.  For more task-oriented
+ *  information, see the @ref window_guide.
  */