Update docs on source dists to reflect new tarball format, and some

doc cleanup

docs/guide/source-dists.rst

@@ -3,13 +3,13 @@ Source Distributions
 
 A *source distribution* is ``dds``'s primary format for consuming and
 distributing packages. A source distribution, in essence, is a
-:ref:`package root <pkgs.pkg-root>` directory that contains only the files
+:ref:`package root <pkgs.pkg-root>` archive that contains only the files
 necessary for ``dds`` to reproduce the full build of all libraries in the
 package. The source distribution retains the directory structure of every
 :ref:`source root <pkgs.source-root>` of the original package, and thus retains
-the header structure thereof. In this way, the ``#include`` directives to use
-a library in a source distribution are identical to if the libraries therein
-were directly part of the consuming project.
+the header structure thereof. In this way, the ``#include`` directives to use a
+library in a source distribution are identical to if the libraries therein were
+directly part of the consuming project.
 
 
 Generating a Source Distribution
@@ -20,24 +20,27 @@ Generating a source distribution from a project directory is done with the
 
 > dds sdist create
 
-The above command can be executed within any package root, and the result will
-be a new directory that reproduces the package's filesystem structure, but
-only maintaining the files that are necessary for ``dds`` to reproduce the
-build of that package.
+The above command can be executed within a package root, and the result will be
+a gzip'd tar archive that reproduces the package's filesystem structure, but
+only maintaining the files that are necessary for ``dds`` to reproduce a build
+of that package.
 
 The ``--project=<dir>`` flag can be provided to override the directory that
 ``dds`` will use as the package root. The default is the working directory of
 the project.
 
 The ``--out=<path>`` flag can be provided to override the destination path of
-the resulting source distribution. The path should not name an existing file or
-directory. By default, ``dds`` will generate a source distribution in the
-working directory with the name ``project.dsd/`` (The output is itself a
-directory, not an archive). If the ``--replace`` flag is provided, then ``dds``
-will overwrite the destination if it names an existing file or directory.
+the archive. The path should not name an existing file or directory. By default,
+``dds`` will generate a source distribution in the working directory with the
+pattern ``<name>@<version>.tar.gz``. If the ``--replace`` flag is provided,
+then ``dds`` will overwrite the destination if it names an existing file or
+directory.
 
 
-Exporting a Package to the Local Repository
-*******************************************
+Importing a Source Ditsribution
+*******************************
 
-.. seealso:: :ref:`repo.export-local`
+Given a source distribution archive, one can import the package into the local
+repository with a single command::
+
+> dds repo import some-package@1.2.3.tar.gz

docs/guide/toolchains.rst

@@ -271,12 +271,17 @@ Valid ``cxx_version`` values are:
 ``warning_flags``
 -----------------
 
-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.
+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 set of warning flags will be provided when warnings are enabled.
 
-    Adding flags to this toolchain option will *append* flags to the basis warning flag list rather than overwrite them.
+    If ``compiler_id`` is provided, a default set of warning flags will be
+    provided when warnings are enabled.
+
+    Adding flags to this toolchain option will *append* flags to the basis
+    warning flag list rather than overwrite them.
 
 .. seealso::
 
@@ -320,22 +325,37 @@ debug information in a separate file from the binaries.
 Select the language runtime/standard library options. Must be an object, and supports two keys:
 
 ``static``
-    A boolean. If ``true``, the runtime and standard libraries will be static-linked into the generated binaries. If ``false``, they will be dynamically linked. Default is ``true`` with MSVC, and ``false`` with GCC and Clang.
+    A boolean. If ``true``, the runtime and standard libraries will be
+    static-linked into the generated binaries. If ``false``, they will be
+    dynamically linked. Default is ``true`` with MSVC, and ``false`` with GCC
+    and Clang.
 
 ``debug``
-    A boolean. If ``true``, the debug versions of the runtime and standard library will be compiled and linked into the generated binaries. If ``false``, the default libraries will be used.
+    A boolean. If ``true``, the debug versions of the runtime and standard
+    library will be compiled and linked into the generated binaries. If
+    ``false``, the default libraries will be used.
 
-    **On MSVC** the default value depends on the top-level ``/debug`` option: If ``/debug`` is not ``false``, then ``/runtime/debug`` defaults to ``true``.
+    **On MSVC** the default value depends on the top-level ``/debug`` option: If
+    ``/debug`` is not ``false``, then ``/runtime/debug`` defaults to ``true``.
 
     **On GCC and Clang** the default value is ``false``.
 
 .. note::
-    On GNU-like compilers, ``static`` does not generate a static executable, it only statically links the runtime and standard library. To generate a static executable, the ``-static`` option should be added to ``link_flags``.
+
+    On GNU-like compilers, ``static`` does not generate a static executable, it
+    only statically links the runtime and standard library. To generate a static
+    executable, the ``-static`` option should be added to ``link_flags``.
 
 .. note::
-    On GNU and Clang, setting ``/runtime/debug`` to ``true`` will compile all files with the ``_GLIBCXX_DEBUG`` and ``_LIBCPP_DEBUG=1`` preprocessor definitions set. **Translation units compiled with these macros are definitively ABI-incompatible with TUs that have been compiled without these options!!**
 
-    If you link to a static or dynamic library that has not been compiled with the same runtime settings, generated programs will likely crash.
+    On GNU and Clang, setting ``/runtime/debug`` to ``true`` will compile all
+    files with the ``_GLIBCXX_DEBUG`` and ``_LIBCPP_DEBUG=1`` preprocessor
+    definitions set. **Translation units compiled with these macros are
+    definitively ABI-incompatible with TUs that have been compiled without these
+    options!!**
+
+    If you link to a static or dynamic library that has not been compiled with
+    the same runtime settings, generated programs will likely crash.
 
 
 ``compiler_launcher``
@@ -402,14 +422,10 @@ Defaults::
         // On GNU-like compilers (GCC, Clang):
         c_compile_file:   "<compiler> -fPIC -pthread [flags] -c [in] -o[out]",
         cxx_compile_file: "<compiler> -fPIC -pthread [flags] -c [in] -o[out]",
-        // When `optimize` is enabled, `-O2` is added as a flag
-        // When `debug` is enabled, `-g` is added as a flag
 
         // On MSVC:
-        c_compile_file:   "cl.exe /MT /nologo /permissive- [flags] /c [in] /Fo[out]",
-        cxx_compile_file: "cl.exe /MT /EHsc /nologo /permissive- [flags] /c [in] /Fo[out]",
-        // When `optimize` is enabled, `/O2` is added as a flag
-        // When `debug` is enabled, `/Z7` and `/DEBUG` are added, and `/MT` becomes `/MTd`
+        c_compile_file:   "cl.exe /nologo /permissive- [flags] /c [in] /Fo[out]",
+        cxx_compile_file: "cl.exe /EHsc /nologo /permissive- [flags] /c [in] /Fo[out]",
     }
 
 
@@ -419,7 +435,7 @@ Defaults::
 Override the *command template* that is used to generate static library archive
 files.
 
-This template expects three placeholders:
+This template expects two placeholders:
 
 - ``[in]`` is the a placeholder for the list of inputs. It must not be attached
   to any other arguments. The list of input paths will be inserted in place of