Update documentation

5 files changed, 69 insertions, 66 deletions

diff --git a/README.md b/README.md
index f089ed7..aae05eb 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,12 @@
 Pugl
 ====
 
-Pugl (PlUgin Graphics Library) is a minimal portable API for GUIs which is
-suitable for use in plugins.  It works on X11, MacOS, and Windows, and
-includes optional support for drawing with Vulkan, OpenGL, and Cairo.
+Pugl (PlUgin Graphics Library) is a minimal portability layer for GUIs which is
+suitable for use in plugins.  It works on X11, MacOS, and Windows, and includes
+optional support for drawing with Vulkan, OpenGL, and Cairo.
 
-Pugl is vaguely similar to libraries like GLUT and GLFW, but with some
-distinguishing features:
+Pugl is vaguely similar to libraries like GLUT and GLFW, but has different
+goals and priorities:
 
  * Minimal in scope, providing only a thin interface to isolate
    platform-specific details from applications.
@@ -16,18 +16,18 @@ distinguishing features:
  * Support for embedding in native windows, for example as a plugin or
    component within a larger application that is not based on Pugl.
 
- * Simple and consistent event-based API that makes dispatching in application
-   or toolkit code easy with minimal boilerplate.
+ * Explicit context and no static data, so that several instances can be used
+   within a single program at once.
 
- * Suitable not only for continuously rendering applications like games, but
-   also event-driven applications that only draw when necessary.
+ * Consistent event-based API that makes dispatching in application or toolkit
+   code easy with minimal boilerplate.
 
- * Explicit context and no static data whatsoever, so that several instances
-   can be used within a single program at once.
+ * Suitable for both continuously rendering applications like games, and
+   event-driven applications that only draw when necessary.
 
- * Small, liberally licensed Free Software implementation that is suitable for
-   vendoring and/or static linking.  Pugl can be installed as a library, or
-   used by simply copying the implementation into a project.
+ * Small, liberally licensed implementation that is suitable for vendoring
+   and/or static linking.  Pugl can be installed as a library, or used by
+   simply copying the implementation into a project.
 
 Stability
 ---------
@@ -66,37 +66,7 @@ all the tests at once via ninja:
     cd build
     ninja test
 
-The `examples` directory contains several programs that serve as both manual
-tests and demonstrations:
-
- * `pugl_embed_demo` shows a view embedded in another, and also tests
-   requesting attention (which happens after 5 seconds), keyboard focus
-   (switched by pressing tab), view moving (with the arrow keys), and view
-   resizing (with the arrow keys while shift is held).  This program uses only
-   very old OpenGL and should work on any system.
-
- * `pugl_window_demo` demonstrates multiple top-level windows.
-
- * `pugl_shader_demo` demonstrates using more modern OpenGL (version 3 or 4)
-   where dynamic loading and shaders are required.  It can also be used to test
-   performance by passing the number of rectangles to draw on the command line.
-
- * `pugl_cairo_demo` demonstrates using Cairo on top of the native windowing
-   system (without OpenGL), and partial redrawing.
-
- * `pugl_print_events` is a utility that prints all received events to the
-   console in a human readable format.
-
- * `pugl_cpp_demo` is a simple cube demo that uses the C++ API.
-
- * `pugl_vulkan_demo` is a simple example of using Vulkan in C that simply
-   clears the window.
-
- * `pugl_vulkan_cpp_demo` is a more advanced Vulkan demo in C++ that draws many
-   animated rectangles like `pugl_shader_demo`.
-
-All example programs support several command line options to control various
-behaviours, see the output of `--help` for details.  Please file an issue if
-any of these programs do not work as expected on your system.
+The [examples](examples) directory contains several demonstration programs that
+can be used for manual testing.
 
  -- David Robillard <d@drobilla.net>
diff --git a/doc/c/view.rst b/doc/c/view.rst
index 12f146d..016c4e3 100644
--- a/doc/c/view.rst
+++ b/doc/c/view.rst
@@ -28,13 +28,14 @@ For example:
 
 .. code-block:: c
 
-   const double defaultWidth  = 1920.0;
-   const double defaultHeight = 1080.0;
+   const PuglSpan defaultWidth  = 1920;
+   const PuglSpan defaultHeight = 1080;
 
    puglSetWindowTitle(view, "My Window");
-   puglSetDefaultSize(view, defaultWidth, defaultHeight);
-   puglSetMinSize(view, defaultWidth / 4.0, defaultHeight / 4.0);
-   puglSetAspectRatio(view, 1, 1, 16, 9);
+   puglSetSizeHint(view, PUGL_DEFAULT_SIZE, 1920, 1080);
+   puglSetSizeHint(view, PUGL_MIN_SIZE, 640, 480);
+   puglSetSizeHint(view, PUGL_MIN_ASPECT, 1, 1);
+   puglSetSizeHint(view, PUGL_MAX_ASPECT, 16, 9);
 
 There are also several :enum:`hints <PuglViewHint>` for basic attributes that can be set:
 
diff --git a/doc/deployment.rst b/doc/deployment.rst
index 4afc51a..1e98e62 100644
--- a/doc/deployment.rst
+++ b/doc/deployment.rst
@@ -9,15 +9,18 @@ Building Against Pugl
 When Pugl is installed,
 pkg-config_ packages are provided that link with the core platform library and desired backend:
 
-- ``pugl-cairo-0``
-- ``pugl-gl-0``
-- ``pugl-vulkan-0``
+.. code-block:: sh
+
+   pkg-config --cflags --libs pugl-0
+   pkg-config --cflags --libs pugl-cairo-0
+   pkg-config --cflags --libs pugl-gl-0
+   pkg-config --cflags --libs pugl-vulkan-0
 
 Depending on one of these packages should be all that is necessary to use Pugl,
 but details on the individual libraries that are installed are available in the README.
 
-If you are instead including the source directly in your project,
-the structure is quite simple and hopefully obvious.
-It is only necessary to copy the platform and backend implementations that you need.
+If you are instead building directly from source,
+all of the implementation files are in the ``src`` directory.
+It is only necessary to build the platform and backend implementations that you need.
 
 .. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
diff --git a/doc/summary.rst b/doc/summary.rst
index f05515f..e9cdc62 100644
--- a/doc/summary.rst
+++ b/doc/summary.rst
@@ -1,21 +1,19 @@
-Pugl is an API for writing portable and embeddable GUIs.
+Pugl is a library for writing portable and embeddable GUIs.
 Pugl is not a toolkit or framework,
 but a minimal portability layer that sets up a drawing context and delivers events.
 
-Compared to other libraries,
 Pugl is particularly suitable for use in plugins or other loadable modules.
-There is no implicit context or static data in the library,
+It has no implicit context or mutable static data,
 so it may be statically linked and used multiple times in the same process.
 
-Pugl has a modular design that separates the core library from graphics backends.
-The core library is graphics agnostic,
-it implements platform support and depends only on standard system libraries.
+Pugl has a modular design with a core library and separate graphics backends.
+The core library implements platform support and depends only on standard system libraries.
 MacOS, Windows, and X11 are currently supported as platforms.
 
-Graphics backends are separate so that applications only depend on the API that they use.
+Graphics backends are built as separate libraries,
+so applications can depend only on the APIs that they use.
 Pugl includes graphics backends for Cairo_, OpenGL_, and Vulkan_.
-It is also possible to use some other graphics API by implementing a custom backend,
-or simply accessing the native platform handle for a window.
+Other graphics APIs can be used by implementing a custom backend.
 
 .. _Cairo: https://www.cairographics.org/
 .. _OpenGL: https://www.opengl.org/
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..20538c3
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,31 @@
+These programs serve as demonstrations, and as utilities for manual testing.
+
+ * `pugl_embed_demo` shows a view embedded in another, and also tests
+   requesting attention (which happens after 5 seconds), keyboard focus
+   (switched by pressing tab), view moving (with the arrow keys), and view
+   resizing (with the arrow keys while shift is held).  This program uses only
+   very old OpenGL and should work on any system.
+
+ * `pugl_window_demo` demonstrates multiple top-level windows.
+
+ * `pugl_shader_demo` demonstrates using more modern OpenGL (version 3 or 4)
+   where dynamic loading and shaders are required.  It can also be used to test
+   performance by passing the number of rectangles to draw on the command line.
+
+ * `pugl_cairo_demo` demonstrates using Cairo on top of the native windowing
+   system (without OpenGL), and partial redrawing.
+
+ * `pugl_print_events` is a utility that prints all received events to the
+   console in a human readable format.
+
+ * `pugl_cpp_demo` is a simple cube demo that uses the C++ API.
+
+ * `pugl_vulkan_demo` is a simple example of using Vulkan in C that simply
+   clears the window.
+
+ * `pugl_vulkan_cpp_demo` is a more advanced Vulkan demo in C++ that draws many
+   animated rectangles like `pugl_shader_demo`.
+
+All example programs support several command line options to control various
+behaviours, see the output of `--help` for details.  Please file an issue if
+any of these programs do not work as expected on your system.