Document package ident and name requirements

docs/err/invalid-pkg-ident.rst

@@ -0,0 +1,9 @@
+Error: Invalid package name *or* Invalid package identifier
+###########################################################
+
+Package identifiers in ``dds`` must follow a well-defined pattern of
+``<name>@<version>``, where ``<version>`` is a valid Semantic Version and
+``<name>`` follows a few simple rules.
+
+.. seealso::
+    :ref:`pkgs.pkgs` and :ref:`Package Naming Requirements <pkgs.naming-reqs>`

docs/guide/packages.rst

@@ -1,5 +1,5 @@
-Package Layout
-##############
+Packages and Layout
+###################
 
 The units of distribution in ``dds`` are *packages*. A single package consists
 of one or more *libraries*. In the simplest case, a package will contain a
@@ -268,6 +268,8 @@ the ``libs/`` directory that is also a library root is added as a child of the
 owning package.
 
 
+.. _pkgs.pkgs:
+
 Packages
 ********
 
@@ -300,4 +302,27 @@ present in the ``package.dds`` file: ``Name``, ``Version``, and ``Namespace``:
 
 .. seealso::
   The purpose of ``Namespace``, as well as additional options in this file,
-  are described in the :ref:`deps.pkg-deps` page
+  are described in the :ref:`deps.pkg-deps` page
+
+
+.. _pkgs.naming-reqs:
+
+Naming Requirements
+===================
+
+Package names aren't a complete free-for-all. Package names must follow a set
+of specific rules:
+
+- Package names may consist of ASCII, lowercase characters, digits,
+  underscores (``_``), hyphens (``-``), and periods (``.``).
+
+  .. note::
+    Different filesystems differ in their handling of filenames. Some platforms
+    perform unicode and case normalization, which can significantly confuse tools
+    that don't use the same normalization rules. Different platforms have
+    different filename limitations and allowable characters. This set of
+    characters is valid on most currently popular filesystems.
+
+- Package names must begin with an alphabetic character
+- Package names must end with an alphanumeric character (letter or digit).
+- Package names may not contain adjacent punctuation characters.