Improve introduction and deployment documentation

3 files changed, 64 insertions, 23 deletions

diff --git a/doc/c/meson.build b/doc/c/meson.build
index fc63421..761557d 100644
--- a/doc/c/meson.build
+++ b/doc/c/meson.build
@@ -10,8 +10,19 @@ conf_py = configure_file(
   output: 'conf.py',
 )
 
-configure_file(copy: true, input: '../deployment.rst', output: 'deployment.rst')
-configure_file(copy: true, input: '../summary.rst', output: 'summary.rst')
+deployment_rst = configure_file(
+  copy: true,
+  input: '../deployment.rst',
+  output: 'deployment.rst',
+)
+
+summary_rst = configure_file(
+  copy: true,
+  input: '../summary.rst',
+  output: 'summary.rst',
+)
+
+copied_rst_files = [deployment_rst, summary_rst]
 
 c_rst_files = files(
   'index.rst',
@@ -36,7 +47,7 @@ docs = custom_target(
   build_by_default: true,
   command: [sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@',
             '-E', '-q', '-t', 'singlehtml'],
-  input: [c_rst_files, c_pugl_rst, c_index_xml],
+  input: [c_rst_files, copied_rst_files, c_pugl_rst, c_index_xml],
   install: true,
   install_dir: docdir / 'pugl-0',
   output: 'singlehtml',
@@ -47,7 +58,7 @@ docs = custom_target(
   build_by_default: true,
   command: [sphinx_build, '-M', 'html', '@OUTDIR@', '@OUTDIR@',
             '-E', '-q', '-t', 'html'],
-  input: [c_rst_files, c_pugl_rst, c_index_xml],
+  input: [c_rst_files, copied_rst_files, c_pugl_rst, c_index_xml],
   install: true,
   install_dir: docdir / 'pugl-0',
   output: 'html',
diff --git a/doc/deployment.rst b/doc/deployment.rst
index 1e98e62..caa95a0 100644
--- a/doc/deployment.rst
+++ b/doc/deployment.rst
@@ -2,11 +2,12 @@
 Usage
 #####
 
-*********************
-Building Against Pugl
-*********************
+**************************
+Using an Installed Version
+**************************
 
 When Pugl is installed,
+particularly on POSIX systems,
 pkg-config_ packages are provided that link with the core platform library and desired backend:
 
 .. code-block:: sh
@@ -16,11 +17,41 @@ pkg-config_ packages are provided that link with the core platform library and d
    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.
+Depending on one of these packages should be all that is necessary to use Pugl.
+If pkg-config is not available,
+details on the individual libraries that are installed are available in the README.
 
-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.
+************************
+Using a Meson Subproject
+************************
 
+Pugl uses the meson_ build system,
+which allows it to be included as a subproject within other meson projects.
+
+To use Pugl as a subproject,
+copy the source tree (or use a git submodule or subtree) to your ``subprojects`` directory,
+for example to ``subprojects/pugl``,
+and use the ``subproject`` function in meson to include it:
+
+.. code-block:: meson
+
+   pugl_proj = subproject('pugl')
+
+See the `Meson subproject documentation <https://mesonbuild.com/Subprojects.html>`_ for details.
+
+******************
+Vendoring Manually
+******************
+
+To "vendor" Pugl with projects that use a different build system,
+the headers in the ``include`` subdirectory and sources in ``src`` are needed.
+The ``include`` directory needs to be added to the search path for the compiler,
+and the required source files need to be compiled.
+It is only necessary to build the needed platform and backend implementations.
+Due to the modular design,
+no centralized configuration is needed to enable or disable platform/backend support.
+However, a few preprocessor symbols can be used to control which X11 features are used,
+see the top of ``src/x11.c`` for details.
+
+.. _meson: https://mesonbuild.com/
 .. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
diff --git a/doc/summary.rst b/doc/summary.rst
index e9cdc62..4f08c46 100644
--- a/doc/summary.rst
+++ b/doc/summary.rst
@@ -1,17 +1,16 @@
-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.
+Pugl is a minimal portability layer for embeddable GUIs.
+It provides a drawing context and event-based main loop API,
+which can be used to create graphical applications or embedded views.
 
-Pugl is particularly suitable for use in plugins or other loadable modules.
-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 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.
+Pugl is particularly suitable for plugins,
+since it has no implicit context or mutable static data,
+and can be statically linked.
+The "core" library implements platform support,
+and depends only on standard system libraries.
+MacOS, Windows, and X11 are currently supported.
 
 Graphics backends are built as separate libraries,
-so applications can depend only on the APIs that they use.
+so applications depend only on the APIs that they use.
 Pugl includes graphics backends for Cairo_, OpenGL_, and Vulkan_.
 Other graphics APIs can be used by implementing a custom backend.