Bump version, and add several docs fixes and clarifications

docs/conf.py

 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '0.1.0-alpha.3'
+release = '0.1.0-alpha.4'
 
 # -- General configuration ---------------------------------------------------
 extensions = []
 pygments_style = None
 
 # -- Options for HTML output -------------------------------------------------
-html_theme = 'pyramid'
+html_theme = 'nature'
 html_theme_options = {}
 html_static_path = []
 html_sidebars = {}

docs/dev/building.rst

 The ``ci.py`` script performs the following actions, in order:
 
 #. Prepare the build output directory
-#. Bootstrap the prior version of ``dds`` that will build the current version.
+#. Prepare the prior version of ``dds`` that will build the current version.
 #. Import the embedded ``catalog.json`` into a catalog database stored within
-   ``_build/``. This will be used to resolve the third-party packages that
+   ``_prebuilt/``. This will be used to resolve the third-party packages that
    ``dds`` itself uses.
 #. Invoke the build of ``dds`` using the prebuilt ``dds`` from the prior
    bootstrap phase. If ``--build-only`` was specified, the CI script stops
 .. code-block:: bash
 
     $ _prebuilt/dds build -t [toolchain] \
-        --catalog _build/catalog.db \
-        --repo-dir _build/ci-repo
+        --catalog _prebuilt/catalog.db \
+        --repo-dir _prebuilt/ci-repo
 
 The ``--catalog`` and ``--repo-dir`` arguments are not strictly necessary, but
 help to isolate the ``dds`` dev environment from the user-local ``dds``

docs/err/invalid-config-key.rst

-Error: Invalid configuration key
-################################
-
-``dds`` uses a very simple key-value-pair plaintext configuration file format.
-Receiving this error indicates that one of the keys in a configuration file is
-invalid.
-
-..  .
-  TODO: Create reference documentation for packages and libs, and include
-  those links in the seealso below.
-
-.. seealso::
-
-    - For defining a toolchain file, see :doc:`/guide/toolchains` and
-      :ref:`toolchains.opt-ref`
-    - For package and library configuration, see the :doc:`/guide/packages`
-      page.

docs/guide/catalog.rst

 Adding Packages to the Catalog
 ******************************
 
-There are two primary ways to add entries to the package catalog.
-
-
-Adding Individual Packages
-==========================
-
-A single package can be added to the catalog with the ``dds catalog add``
-command:
-
-.. code-block:: text
-
-    dds catalog add <package-id>
-        [--depends <requirement> [--depends <requirement> [...]]]
-        [--git-url <url> --git-ref <ref>]
-        [--auto-lib <namespace>/<name>]
-
-The ``<package-id>`` positional arguments is the ``name@version`` package ID
-that will be added to the catalog. The following options are supported:
-
-``--depends <requirement>``
-    This argument, which can be specified multiple times to represent multiple
-    dependencies, sets the dependencies of the package within the catalog. If
-    the obtained package root contains a ``package.json5``, then the
-    dependencies listed here must be identical to those listed in
-    ``package.json5``, or dependency resolution may yield unexpected results.
-
-``--git-url <url>``
-    Specify a Git URL to clone from to obtain the package. The root of the
-    cloned repository must be a package root, but does not necessarily need to
-    have the ``package.json5`` and ``library.json5`` files if relying on the
-    ``--auto-lib`` parameter.
-
-    ``--git-ref`` **must** be passed with ``--git-url``.
-
-``--git-ref <ref>``
-    Specify a Git ref to clone. The remote must support cloning by the ref that
-    is specified here. Most usually this should be a Git tag.
-
-    ``dds`` will perform a shallow clone of the package at the specified
-    Git reference.
-
-``--auto-lib``
-    This option must be provided if the upstream does not already contain the
-    ``dds`` files that are necessary to export the library information. This
-    can only be specified for packages that contain a single library root at
-    the package root.
-
-    The form of the argument is that of ``<namespace>/<name>``, where
-    ``namespace`` and ``name`` are the usage requirement keys that should be
-    generated for the library.
-
-
-.. _catalog.adding.json:
-
-Bulk Imports via JSON
-=====================
-
-The ``dds catalog import`` supports a ``--json`` flag that specifies a JSON
+The ``dds catalog import`` supports a ``--json`` flag that specifies a JSON5
 file from which catalog entries will be generated.
 
 .. note::
 
   {
     // Import version spec.
-    "version": 1,
+    version: 1,
     // Packages section
-    "packages": {
+    packages: {
       // Subkeys are package names
       "acme-gadgets": {
         // Keys within the package names are the versions that are
         // available for each package.
         "0.4.2": {
-          // `depends` is an object of dependencies for this
+          // `depends` is an array of dependency statements for this
           // particular version of the package. (Optional)
-          "depends": {
-            // A mapping of package names to version ranges
-            "acme-widgets": "^1.4.1"
-          },
+          depends: [
+            "acme-widgets^1.4.1"
+          ],
           // `description` is an attribute to give a string to describe
           // the package. (Optional)
-          "description": "A collection of useful gadgets.",
+          description: "A collection of useful gadgets.",
           // Specify the Git remote information
-          "git": {
+          git: {
             // `url` and `ref` are required.
-            "url": "http://example.com/git/repo/acme-gadgets.git",
-            "ref": "v0.4.2-stable",
+            url: "http://example.com/git/repo/acme-gadgets.git",
+            ref: "v0.4.2-stable",
             // The `auto-lib` is optional, to specify an automatic
             // library name/namespace pair to generate for the
             // root library
             "auto-lib": "Acme/Gadgets",
             // List of filesystem transformations to apply to the repository
             // (optional)
-            "transform": [
+            transform: [
               // ... (see below) ...
             ]
           }
 Filesystem Transformations
 **************************
 
-A catalog entry can have a set of filesystem transformations attached to its remote information (e.g. the ``git`` property). When ``dds`` is obtaining a copy of the code for the package, it will apply the associated transformations to the filesystem based in the directory of the downloaded/cloned directory. In this was, ``dds`` can effectively "patch" the filesystem structure of a project arbitrarily. This allows many software projects to be imported into ``dds`` without needing to patch/fork the original project to support the required filesystem structure.
+.. note::
+  Filesystem transformations is a transitional feature that is likely to be
+  removed in a future release, and replaced with a more robust system when
+  ``dds`` has a better way to download packages. Its aim is to allow ``dds``
+  projects to use existing libraries that might not meet the layout
+  requirements that ``dds`` imposes, but can otherwise be consumed by ``dds``
+  with a few tweaks.
+
+A catalog entry can have a set of filesystem transformations attached to its
+remote information (e.g. the ``git`` property). When ``dds`` is obtaining a
+copy of the code for the package, it will apply the associated transformations
+to the filesystem based in the directory of the downloaded/cloned directory. In
+this way, ``dds`` can effectively "patch" the filesystem structure of a project
+arbitrarily. This allows many software projects to be imported into ``dds``
+without needing to patch/fork the original project to support the required
+filesystem structure.
 
 .. important::
   While ``dds`` allows you to patch directories downloaded via the catalog, a
 
   The intention of filesystem transformations is to act as a "bridge" that will allow ``dds`` projects to more easily utilize existing libraries.
 
-.. note::
-  Filesystem transformations can only be added to catalog entries using the
-  :ref:`JSON import method <catalog.adding.json>`. It is not available in the
-  command-line import method.
-
 
 Available Transformations
 =========================
 
-At time of writing, there are four main transformations available to catalog entries:
+At time of writing, there are five transformations available to catalog entries:
 
 ``copy`` and ``move``
   Copies or moves a set of files/directories from one location to another. Allows the following options:
   - ``path`` - The path of the file to write. **Required**
   - ``content`` - A string that will be written to the file. **Required**
 
-  If the file exists and is not a directory, the file will be replaced. If the path names an existing directory, an error will be generated.
+  If the file exists and is not a directory, the file will be replaced. If the
+  path names an existing directory, an error will be generated.
+
+``edit``
+  Modifies the contents of the files in the package.
+
+  - ``path`` - Path to the file to edit. **Required**
+  - ``edits`` - An array of edit objects, applied in order, with the following
+    keys:
+
+    - ``kind`` - One of ``insert`` or ``delete`` to insert/delete lines,
+      respectively. **Required**
+    - ``line`` - The line at which to perform the insert/delete. The first line
+      of the file is line one, *not* line zero. **Required**
+    - ``content`` - For ``insert``, the string content to insert into the file.
+      A newline will be appended after the content has been inserted.
 
-Transformations are added as a JSON array to the JSON object that specifies the remote information for the package. Each element of the array is an object, with one or more of the four keys listed above. If an object features more than one of the above keys, they are applied in the same order as they have been listed.
+Transformations are added as a JSON array to the JSON object that specifies
+the remote information for the package. Each element of the array is an
+object, with one or more of the keys listed above. If an object features more
+than one of the above keys, they are applied in the same order as they have
+been listed.
 
 
 Example: Crypto++
 =================
 
-The following catalog entry will build and import `Crypto++`_ for use by a ``dds`` project. This uses the unmodified Crypto++ repository, which ``dds`` doesn't know how to build immediately. With some simple moving of files, we end up with something ``dds`` can build directly:
+The following catalog entry will build and import `Crypto++`_ for use by a
+``dds`` project. This uses the unmodified Crypto++ repository, which ``dds``
+doesn't know how to build immediately. With some simple moving of files, we
+end up with something ``dds`` can build directly:
 
 .. code-block:: javascript
 
 Example: libsodium
 ==================
 
-For example, this catalog entry will build and import `libsodium`_ for use in a ``dds`` project. This uses the upstream libsodium repository, which does not meet the layout requirements needed by ``dds``. With a few simple transformations, we can allow ``dds`` to build and consume libsodium successfully:
+For example, this catalog entry will build and import `libsodium`_ for use in
+a ``dds`` project. This uses the upstream libsodium repository, which does not
+meet the layout requirements needed by ``dds``. With a few simple
+transformations, we can allow ``dds`` to build and consume libsodium
+successfully:
 
 .. code-block:: javascript
 

docs/guide/cmake.rst

 .. note::
     ``dds`` doesn't (yet) have a ready-made central repository of packages that
     can be downloaded. You'll need to populate the local package catalog
-    appropriately.
+    appropriately. The default catalog file contains a limited set of useful
+    packages, but you may wish to add more for yourself.
 
     .. seealso:: Refer to :doc:`catalog` for information about remote packages.
 
 Declaring Dependencies
 ======================
 
-``dds build-deps`` accepts a list of dependencies as commnad line arguments,
-but it may be useful to specify those requirements in a file.
+``dds build-deps`` accepts a list of dependency statements as commnad line
+arguments, but it may be useful to specify those requirements in a file.
 
 ``dds build-deps`` accepts a JSON5 file describing the dependencies of a
 project as well. This file is similar to a very stripped-down version of a
     :caption: ``dependencies.json5``
 
     {
-        depends: {
-            'neo-sqlite3': '^0.2.0',
-        }
+        depends: [
+            'neo-sqlite3^0.2.0',
+        ]
     }
 
 
 any of the transitive dependencies required.
 
 
-Using Out Dependencies' Libraries
+Using Our Dependencies' Libraries
 =================================
 
 Like with ``dds``, CMake wants us to explicitly declare how our build targets
 
     pmm(DDS)
 
-..note::
+.. note::
     The ``_deps`` directory and ``INDEX.lmi`` file will be placed in the CMake
     build directory, out of the way of the rest of the project.
 

docs/guide/interdeps.rst

 .. code-block:: js
 
     {
-        name: 'acme-widgets',
+        name: 'acme-gadgets',
         version: '4.3.6',
         namespace: 'acme',
     }
 
 Suppose that our package's libraries build upon the libraries in the
 ``acme-widgets`` package, and that we require version ``1.4.3`` or newer, but
-not as new as ``2.0.0``. Such a dependency can be declared with the ``Depends``
-key:
+not as new as ``2.0.0``. Such a dependency can be declared with the ``depends``
+array:
 
 .. code-block:: js
     :emphasize-lines: 5-7
         name: 'acme-gadgets',
         version: '4.3.6',
         namespace: 'acme',
-        depends: {
-            'acme-widgets': '^1.4.3',
-        },
+        depends: [
+            'acme-widgets^1.4.3',
+        ],
     }
 
 .. seealso:: :ref:`deps.ranges`.
 
 If we wish to declare additional dependencies, we simply declare them with
-additional ``Depends`` keys
+additional ``depends`` items:
 
 .. code-block::
     :emphasize-lines: 7-8
         name: 'acme-gadgets',
         version: '4.3.6',
         namespace: 'acme',
-        depends: {
-            'acme-widgets': '^1.4.3',
-            'acme-gizmos': '~5.6.5',
-            'acme-utils': '^3.3.0',
-        },
+        depends: [
+            'acme-widgets^1.4.3',
+            'acme-gizmos~5.6.5',
+            'acme-utils^3.3.0',
+        ],
     }
 
 When ``dds`` attempts to build a project, it will first build the dependency
 supported by ``npm`` and ``npm``-like tools. There are five (and a half)
 version range formats available, listed in order of most-to-least restrictive:
 
-Exact: ``1.2.3`` and ``=1.2.3``
+Exact: ``@1.2.3``
     Specifies an *exact* requirement. The dependency must match the named
     version *exactly* or it is considered incompatible.
 
     Specifies an *at least* requirement. The version must be *at least* the
     given version, but any newer version is acceptable.
 
-Anything: ``*``
-    An asterisk ``*`` represents than *any* version is acceptable. This is not
-    recommended for most dependencies.
+A dependency string is simply the name of the package with the range suffix appended.
 
 
 .. _deps.ranges.why-lowest:
 
 Suppose we are developing a library ``Gadgets``, and we wish to make use of
 ``Widgets``. The latest version is ``1.5.2``, and they promise Semantic
-Versioning compatibility, so we select a version range of ``^1.5.2``.
+Versioning compatibility, so we select a dependency statement of
+``Widgets^1.5.2``.
 
 Suppose a month passes, and ``Widgets@1.6.0`` is published. A few things
 happen:
    *everyone* is developing against ``1.6.0`` without realizing that they
    actually only require ``1.5.2`` in their dependency declarations.
 #. Code in our project is written that presupposes features or bugfixes added
-   in ``1.6.0``, and thus makes the dependency declaration on ``Widgets ^1.5.2``
+   in ``1.6.0``, and thus makes the dependency declaration on ``Widgets^1.5.2``
    a *lie*.
 
 Pulling the lowest-matching-version has two *huge* benefits:
 In short: *Your* compatibility ranges are not for *you*. They are for *your
 users*.
 
-Suppose package ``A`` requires ``B ^1.0.0``, and ``B`` requires ``C ^1.2.0``.
+Suppose package ``A`` requires ``B^1.0.0``, and ``B`` requires ``C^1.2.0``.
 Now let us suppose that ``A`` wishes to use a newer feature of ``C``, and thus
-declares a dependency on ``C ^1.3.0``. ``B`` and ``A`` have different
+declares a dependency on ``C^1.3.0``. ``B`` and ``A`` have different
 compatibility ranges on ``C``, but this will work perfectly fine **as long as
 the compatible version ranges of A and B have some overlap**.
 

docs/guide/packages.rst

       * ``.cpp``, ``.c++``, ``.cc``, and ``.cxx``
 
     - * Not compiled
-      * ``.H``, ``.H++``, ``.h``, ``.h++``, ``.hh``, ``.hpp``, ``.hxx``, and ``.inl``
+      * ``.H``, ``.H++``, ``.h``, ``.h++``, ``.hh``, ``.hpp``, ``.hxx``,
+        ``.ipp``, ``.inc``, and ``.inl``
 
 If a file's extension is not listed in the table above, ``dds`` will ignore it.
 

docs/guide/toolchains.rst

 Providing a Default Toolchain File
 **********************************
 
-If you do not which to provide a new toolchain for every individual project,
+If you do not wish to provide a new toolchain for every individual project,
 and the built-in toolchains do not suit your needs, you can write a toolchain
 file to one of a few predefined paths, and ``dds`` will find and use it for the
 build. The following directories are searched, in order:
 
 Despite splitting strings as-if they were shell commands, ``dds`` does nothing
 else shell-like. It does not expand environment variables, nor does it expand
-globs.
+globs and wildcards.
 
 
 ``compiler_id``
 ``warning_flags``
 -----------------
 
-Override the compiler flags that should be used to enable warnings. This option
-is stored separately from ``flags``, as these options may be enabled/disabled
-separately depending on how ``dds`` is invoked.
+Provide *additional* compiler flags that should be used to enable warnings. This option is stored separately from ``flags``, as these options may be enabled/disabled separately depending on how ``dds`` is invoked.
 
 .. note::
-    If ``compiler_id`` is provided, a default value will be used that enables
-    common warning levels.
+    If ``compiler_id`` is provided, a default set of warning flags will be provided when warnings are enabled.
 
-    If you need to tweak warnings further, use this option.
+    Adding flags to this toolchain option will *append* flags to the basis warning flag list rather than overwrite them.
 
-On GNU-like compilers, the default flags are ``-Wall -Wextra -Wpedantic
--Wconversion``. On MSVC the default flag is ``/W4``.
+.. seealso::
+
+    Refer to :ref:`toolchains.opts.base_warning_flags` for more information.
 
 
 ``flags``, ``c_flags``, and ``cxx_flags``
 On GNU and Clang this will be ``-fdiagnostics-color`` by default.
 
 
-``obj_prefix``, ``obj_suffix``, ``archive_prefix``, ``archive_suffix``,
-``exe_prefix``, and ``exe_suffix``
-----------------------------------
+``obj_prefix``, ``obj_suffix``, ``archive_prefix``, ``archive_suffix``, ``exe_prefix``, and ``exe_suffix``
+----------------------------------------------------------------------------------------------------------
 
 Set the filename prefixes and suffixes for object files, library archive files,
 and executable files, respectively.
+
+
+.. _toolchains.opts.base_warning_flags:
+
+``base_warning_flags``
+----------------------
+
+When you compile your project and request warning flags, ``dds`` will
+concatenate the warning flags from this option with the flags provided by
+``warning_flags``. This option is "advanced," because it provides a set of
+defaults based on the ``compiler_id``.
+
+On GNU-like compilers, the base warning flags are ``-Wall -Wextra -Wpedantic
+-Wconversion``. On MSVC the default flag is ``/W4``.
+
+For example, if you set ``warning_flags`` to ``"-Werror"`` on a GNU-like
+compiler, the resulting command line will contain ``-Wall -Wextra -Wpedantic
+-Wconversion -Werror``.

docs/index.rst

     dev/index
     err/index
 
-.. Hide the link to the error reference since we don't want it cluttering our
-    main toc, but we want Sphinx to not consider it "unreferenced." We'll generate
-    our own link
-
-.. seealso::
-    For in-depth error and troubleshooting information see: :doc:`err/index`.
-
-
 Indices and tables
 ==================
 

docs/tut/hello-world.rst

    The term *package root* is further described in the :doc:`/guide/packages` page.
 
 From here on, this created directory will simply be noted as ``<root>``. In
-the examples, this will refer to the directory package root directory we have
-created.
+the examples, this will refer to the package root directory we have created.
 
 
 Creating the First *Source Root*
 
 > dds build -t :gcc
 
-If all successful, ``dds`` will emit information about the compile and link
+If all is successful, ``dds`` will emit information about the compile and link
 process, and then exit without error.
 
 By default, build results will be placed in a subdirectory of the package root

package.jsonc

 {
     "$schema": "./res/package-schema.json",
     "name": "dds",
-    "version": "0.1.0-alpha.3",
+    "version": "0.1.0-alpha.4",
     "namespace": "dds",
     "depends": {
         "spdlog": "1.4.2",

src/dds/error/errors.cpp

         return "invalid-version-string.html#range";
     case errc::invalid_version_string:
         return "invalid-version-string.html";
-    case errc::invalid_config_key:
-        return "invalid-config-key.html";
     case errc::invalid_lib_filesystem:
     case errc::invalid_pkg_filesystem:
         return "invalid-pkg-filesystem.html";
 specification. Refer to the documentation and https://semver.org/ for more
 information.
 )";
-    case errc::invalid_config_key:
-        return R"(The `key' in a `key: value' pair was not recognized.)";
     case errc::invalid_lib_filesystem:
     case errc::invalid_pkg_filesystem:
         return R"(
         return "Attempted to parse an invalid version range string." BUG_STRING_SUFFIX;
     case errc::invalid_version_string:
         return "Attempted to parse an invalid version string." BUG_STRING_SUFFIX;
-    case errc::invalid_config_key:
-        return "Found an invalid configuration key." BUG_STRING_SUFFIX;
     case errc::invalid_lib_filesystem:
     case errc::invalid_pkg_filesystem:
         return "The filesystem structure of the package/library is invalid." BUG_STRING_SUFFIX;

src/dds/error/errors.hpp

     invalid_version_string,
     invalid_pkg_id,
     invalid_pkg_name,
-    invalid_config_key,
     unknown_test_driver,
     dependency_resolve_failure,
     dup_lib_name,