Declare the documentation's structure in a source file

src/documentation.cpp is the documentation loading source: it carries no
code and names each document that the generated reference contains, in
order, by page label. The labels are declared on each markdown file's
first heading. The build configuration lists the files as Doxygen inputs
and nothing more, so the structure of the documentation and the
mechanics of generating it are separate.

The hand-maintained document index at the end of OVERVIEW.md is gone,
along with the last references to markdown files by filename in the
public header. The document list exists in one place.

The docs target clears its output and scratch directories on every run.
Doxygen keeps output files it judges unchanged, so a run over a
populated scratch directory carried pages forward from earlier ones, and
removed sections survived in the generated HTML and PDF after their
source was edited.

include/dpm/core.h

@@ -320,66 +320,17 @@ DPM_API const char* dpm_last_error(dpm_ctx* ctx);
 /* Module contract (implemented by modules, called by libdpm-core)    */
 /* ------------------------------------------------------------------ */
 
-/**
- * @mainpage libdpm-core.so — API Reference
+/*
+ * Every module exports, as extern "C":
  *
- * This is the generated reference for libdpm-core.so, extracted from
- * the source. It covers the public C API in <dpm/core.h>, the library's
- * internals, and the module contract.
- *
- * Start at core.h for the API a consumer or a module calls, and at
- * @ref module_contract for what a module implements.
- *
- * The project's prose documentation — overview, design, build, module
- * authoring, and consumer guide — lives in the docs/ directory of the
- * repository and is read there.
- */
-
-/**
- * @page module_contract The Module Contract
- *
- * A module is one .so in the module directory. It includes
- * <dpm/core.h>, links -ldpm-core, and exports three reserved symbols as
- * extern "C":
- *
- * @code
- * int         dpm_module_execute(dpm_ctx* ctx, const char* command,
- *                                int argc, char** argv);
- * const char* dpm_module_version(void);
- * const char* dpm_module_description(void);
- * @endcode
- *
- * @section module_contract_surface The Functional Surface
+ *   int         dpm_module_execute(dpm_ctx* ctx, const char* command,
+ *                                  int argc, char** argv);
+ *   const char* dpm_module_version(void);
+ *   const char* dpm_module_description(void);
  *
  * dpm_module_execute is the only entry through which a module performs
- * work; its capabilities are addressed by command string, so a module
- * publishes no headers, struct layouts, or symbols to anything that
- * calls it. NULL or an empty command behaves as the module's help
- * command.
- *
- * dpm_module_version and dpm_module_description are what a module
- * reports about itself. The library reads both at load and serves them
- * to consumers through dpm_module_info_of, where the version is what a
- * calling module judges before deciding to issue a command.
- *
- * @section module_contract_version Version Compatibility
- *
- * A module determines for itself whether it can work with the library
- * it is running against: dpm_core_version() reports the running
- * version, and the module proceeds or fails on its own judgement. A
- * module is built against the system-installed libdpm-core.so and is
- * responsible for being correct against it.
- *
- * The same holds toward a peer. A module requires the peer by name,
- * reads the version the library reports, and decides whether that
- * version suits the commands it intends to issue.
- *
- * @section module_contract_validation Validation
- *
- * The library refuses to load any module that does not validate
- * completely: every reserved symbol resolves, and the version and
- * description probes return well-formed values. A module that loads is
- * fully valid.
+ * work. The other two are what it reports about itself; the library
+ * reads both at load and serves them through dpm_module_info_of.
  */
 
 #ifdef __cplusplus