Documentation work.

docs/Doxyfile.in

@@ -666,7 +666,6 @@ INPUT                  = @GLFW_INTERNAL_DOCS@                         \
                          @GLFW_SOURCE_DIR@/docs/monitor.dox           \
                          @GLFW_SOURCE_DIR@/docs/window.dox            \
                          @GLFW_SOURCE_DIR@/docs/input.dox             \
-                         @GLFW_SOURCE_DIR@/docs/common.dox            \
                          @GLFW_SOURCE_DIR@/docs/rift.dox              \
                          @GLFW_SOURCE_DIR@/docs/compat.dox
 

docs/common.dox

@@ -1,18 +0,0 @@
-/*!
-
-@page common Common tasks
-
-@tableofcontents
-
-This guide explains how to 
-
-
-@section common_full_screen Windowed full screen mode
-
-@section common_window_pos Initial window position
-
-GLFW comes with the `windows` test program, which illustrates this method.
-
-@section common_fps_camera First-person camera controls
-
-*/

docs/input.dox

@@ -146,16 +146,30 @@ The `GLFW_KEY_LAST` constant holds the highest value of any
 [named key](@ref keys).
 
 
-@subsection input_char Unicode character input
+@subsection input_char Text input
 
-If you wish to receive Unicode code point input, set a character callback.
+GLFW supports text input in the form of a stream of
+[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
+operating system text input system.  Unlike key input, text input obeys keyboard
+layouts and modifier keys and supports composing characters using
+[dead keys](https://en.wikipedia.org/wiki/Dead_key).  Once received, you can
+encode the code points into
+[UTF-8](https://en.wikipedia.org/wiki/UTF-8) or any other encoding you prefer.
+
+Because an `unsigned int` is 32 bits long on all platforms supported by GLFW,
+you can treat the code point argument as native endian
+[UTF-32](https://en.wikipedia.org/wiki/UTF-32).
+
+There are two callbacks for receiving Unicode code points.  If you wish to
+offer regular text input, set a character callback.
 
 @code
 glfwSetCharCallback(window, character_callback);
 @endcode
 
 The callback function receives Unicode code points for key events that would
-have led to regular text input on that platform.
+have led to regular text input and generally behaves as a standard text field on
+that platform.
 
 @code
 void character_callback(GLFWwindow* window, unsigned int codepoint)
@@ -163,9 +177,9 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
 }
 @endcode
 
-If you wish to receive all Unicode code point events generated by the system, or
-just want to know exactly what modifier keys were used, set a character with
-modifiers callback.
+If you wish to receive even those Unicode code points generated with modifier
+key combinations that a plain text field would ignore, or just want to know
+exactly what modifier keys were used, set a character with modifiers callback.
 
 @code
 glfwSetCharCallback(window, charmods_callback);

docs/intro.dox

@@ -114,19 +114,24 @@ keep the description string.
 @section coordinate_systems Coordinate systems
 
 GLFW has two primary coordinate systems: the _virtual screen_ and the window
-_client area_.  Both use the same unit: _virtual screen coordinates_, or just
-_screen coordinates_, which don't necessarily correspond to pixels.
+_client area_ or _content area_.  Both use the same unit: _virtual screen
+coordinates_, or just _screen coordinates_, which don't necessarily correspond
+to pixels.
 
 <img src="spaces.svg" width="90%" />
 
-Window and monitor positions are specified relative to the upper-left corners of
-their content areas, while cursor positions are specified relative to the window
-client area.
+Both the virtual screen and the client area coordinate systems have the X-axis
+pointing to the right and the Y-axis pointing down.
 
-The origin of the window client area coordinate system is also the position of
-the window, meaning you can translate client area coordinates to the virtual
-screen by adding the window position.  The window frame, when present, extend
-out from the client area but does not affect the window position.
+Window and monitor positions are specified as the position of the upper-left
+corners of their content areas relative to the virtual screen, while cursor
+positions are specified relative to a window's client area.
+
+Because the origin of the window's client area coordinate system is also the
+point from which the window position is specified, you can translate client area
+coordinates to the virtual screen by adding the window position.  The window
+frame, when present, extends out from the client area but does not affect the
+window position.
 
 Almost all positions and sizes in GLFW are measured in screen coordinates
 relative to one of the two origins above.  This includes cursor positions,
@@ -140,7 +145,7 @@ measured in pixels.
 Pixels and screen coordinates may map 1:1 on your machine, but they won't on
 every other machine, for example on a Mac with a Retina display.  The ratio
 between screen coordinates and pixels may also change at run-time depending on
-which monitor the window is currently on.
+which monitor the window is currently considered to be on.
 
 
 @section guarantees_limitations Guarantees and limitations

docs/monitor.dox

@@ -28,9 +28,10 @@ Each monitor has a current video mode, a list of supported video modes,
 a virtual position, a human-readable name, an estimated physical size and
 a gamma ramp.  One of the monitors is the primary monitor.
 
-The virtual position of a monitor is in screen coordinates and, together with
-the current video mode, describes the viewports that the connected monitors
-provide into the virtual desktop that spans them.
+The virtual position of a monitor is in
+[screen coordinates](@ref coordinate_systems) and, together with the current
+video mode, describes the viewports that the connected monitors provide into the
+virtual desktop that spans them.
 
 
 @subsection monitor_monitors Retrieving monitors
@@ -86,15 +87,13 @@ a gamma ramp.
 
 @subsection monitor_modes Video modes
 
-Although GLFW generally does a good job at selecting a suitable video
-mode for you when you open a full screen window, it is sometimes useful to
-know exactly which modes are available on a certain system. For example,
-you may want to present the user with a list of video modes to select
-from.
+GLFW generally does a good job selecting a suitable video mode when you create
+a full screen window, but it is sometimes useful to know exactly which video
+modes are supported.
 
-To get a list of supported video modes, you can use the function @ref
-glfwGetVideoModes.  See the reference documentation for the lifetime of the
-returned array.
+Video modes are represented as @ref GLFWvidmode structures.  You can get an
+array of the video modes supported by a monitor with @ref glfwGetVideoModes.
+See the reference documentation for the lifetime of the returned array.
 
 @code
 int count;
@@ -102,16 +101,19 @@ GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
 @endcode
 
 To get the current video mode of a monitor call @ref glfwGetVideoMode.  See the
-reference documentation for the lifetime of the returned structure.
+reference documentation for the lifetime of the returned pointer.
 
 @code
 const GLFWvidmode* mode = glfwGetVideoMode(monitor);
 @endcode
 
+The resolution of a video mode is specified in
+[screen coordinates](@ref coordinate_systems), not pixels.
+
 
 @subsection monitor_size Physical size
 
-The physical size in millimetres of a monitor, or an estimation of it, can be
+The physical size of a monitor in millimetres, or an estimation of it, can be
 retrieved with @ref glfwGetMonitorPhysicalSize.  This has no relation to its
 current _resolution_, i.e. the width and height of its current
 [video mode](@ref monitor_modes).
@@ -131,8 +133,9 @@ const double dpi = mode->width / (widthMM / 25.4);
 
 @subsection monitor_pos Virtual position
 
-The position of the monitor on the virtual desktop, in screen coordinates, can
-be retrieved with @ref glfwGetMonitorPos.
+The position of the monitor on the virtual desktop, in
+[screen coordinates](@ref coordinate_systems), can be retrieved with @ref
+glfwGetMonitorPos.
 
 @code
 int xpos, ypos;

docs/window.dox

@@ -187,14 +187,16 @@ application has no preference.
 of the accumulation buffer.  `GLFW_DONT_CARE` means the application has no
 preference.
 
-@note Accumulation buffers are a legacy OpenGL feature and should not be used in
-new code.
+@par
+Accumulation buffers are a legacy OpenGL feature and should not be used in new
+code.
 
 `GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
 `GLFW_DONT_CARE` means the application has no preference.
 
-@note Auxiliary buffers are a legacy OpenGL feature and should not be used in
-new code.
+@par
+Auxiliary buffers are a legacy OpenGL feature and should not be used in new
+code.
 
 `GLFW_STEREO` specifies whether to use stereoscopic rendering.  This is a hard
 constraint.
@@ -251,6 +253,7 @@ forward-compatible, i.e. one where all functionality deprecated in the requested
 version of OpenGL is removed.  This may only be used if the requested OpenGL
 version is 3.0 or above.  If OpenGL S is requested, this hint is ignored.
 
+@par
 Forward-compatibility is described in detail in the
 [OpenGL Reference Manual](https://www.opengl.org/registry/).
 
@@ -265,6 +268,7 @@ a specific profile.  If requesting an OpenGL version below 3.2,
 `GLFW_OPENGL_ANY_PROFILE` must be used.  If another OpenGL ES is requested,
 this hint is ignored.
 
+@par
 OpenGL profiles are described in detail in the
 [OpenGL Reference Manual](https://www.opengl.org/registry/).
 
@@ -282,6 +286,7 @@ the pipeline will be flushed whenever the context is released from being the
 current one.  If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
 not be flushed on release.
 
+@par
 Context release behaviors are described in detail by the
 [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
 extension.
@@ -384,8 +389,9 @@ void window_close_callback(GLFWwindow* window)
 @subsection window_size Size
 
 The size of a window can be changed with @ref glfwSetWindowSize.  For windowed
-mode windows, this sets the size of the _client area_ or _content area_ of the
-window.  The window system may impose limits on window size.
+mode windows, this sets the size, in
+[screen coordinates](@ref coordinate_systems) of the _client area_ or _content
+area_ of the window.  The window system may impose limits on window size.
 
 @code
 glfwSetWindowSize(window, 640, 480);
@@ -403,8 +409,8 @@ the system, set a size callback.
 glfwSetWindowSizeCallback(window, window_size_callback);
 @endcode
 
-The callback function receives the new size of the client area of the window
-when it is resized.
+The callback function receives the new size, in screen coordinates, of the
+client area of the window when it is resized.
 
 @code
 void window_size_callback(GLFWwindow* window, int width, int height)
@@ -442,11 +448,10 @@ distances and not coordinates, they are always zero or positive.
 @subsection window_fbsize Framebuffer size
 
 While the size of a window is measured in screen coordinates, OpenGL works with
-pixels.  The size you pass into `glViewport`, for example, should be in pixels
-and not screen coordinates.  On some platforms screen coordinates and pixels are
-the same, but this is not the case on all platforms supported by GLFW.  There is
-a second set of functions to retrieve the size in pixels of the framebuffer of
-a window.
+pixels.  The size you pass into `glViewport`, for example, should be in pixels.
+On some machines screen coordinates and pixels are the same, but on others they
+will not be.  There is a second set of functions to retrieve the size, in
+pixels, of the framebuffer of a window.
 
 If you wish to be notified when the framebuffer of a window is resized, whether
 by the user or the system, set a size callback.
@@ -483,8 +488,8 @@ a high-DPI one.
 
 The position of a windowed-mode window can be changed with @ref
 glfwSetWindowPos.  This moves the window so that the upper-left corner of its
-client area has the specified screen coordinates.  The window system may put
-limitats on window placement.
+client area has the specified [screen coordinates](@ref coordinate_systems).
+The window system may put limitats on window placement.
 
 @code
 glfwSetWindowPos(window, 100, 100);