Add badpath keyword

1 files changed, 113 insertions, 0 deletions

diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst
index b175299..e2debd7 100644
--- a/docs/source/spec_file_format.rst
+++ b/docs/source/spec_file_format.rst
@@ -13,12 +13,122 @@ Keywords
 * **group** - Name of group the package belongs to
 * **upstream_url** - URL to package in repository
 * **source_url** - URL to original source package
+* **badpath** - Name of extracted top-level directory
 * **description** - Full description of package
 * **summary** - Brief description of package
 * **classification** - opensolaris package classification format [1]_
 * **arch** - Destined architecture of the package
 * **license** - License of the package
 
+Keywords, in-depth
+==================
+
+.. _FMRI: http://docs.oracle.com/cd/E26502_01/html/E21383/pkgterms.html#glubk
+
+Keywords in an ipsutils SPEC file refer to the data inserted into the FMRI_ section of a package manifest.
+
+name
+----
+
+The ``name`` of the package should match the first part of the source package.
+If source package is named ``ccache-x.y.z.tar.gz`` the ``name`` field should be set to ``ccache``.
+In the case of Python, for example, they use a capital 'p' in the source package filename: ``Python-3.2.1.tar.gz``.
+
+repackas
+--------
+
+To create an IPS package under a different name use the ``repackas`` keyword.  In this case, ``Python``
+can be repackaged as ``python3`` and all subsequent modules (numpy, scipy, etc) can be repackaged as
+``python3-[module]`` to make administration easier.
+
+version
+-------
+
+The version of the package is generally provided in the name of the source archive.
+
+release
+-------
+
+The ``release`` keyword allow you to apply patches to the IPS package without the need to change the version number.
+For example, if a maintainer releases a bugfix, but it does not increment the version number, you may apply the
+patch, increment the release number, and push the package to your repository.  Clients will then receive the latest 
+bugfix without incrementing the package version.
+
+group
+-----
+
+``group`` defines a subclass of the IPS package classification system.
+
+summary
+-------
+
+``summary`` is a very brief description of the package's functional purpose.
+
+license
+-------
+
+The ``license`` describes the package's current license (e.g. ``GPL``, ``BSD``, ``MIT``, etc)
+
+maintainer
+----------
+
+The package maintainer's full name and email.  Use the format: ``John Doe <john@example.com>``
+
+upstream_url
+------------
+
+URL to the original source archive on the internet (or intranet).  Example, ``http://www.example.com/package-1.0.0.tar.gz``
+
+source_url
+----------
+
+Although ``upstream_url`` can be in URL format, it is not a requirement.  Example, ``package-1.0.0.tar.gz`` or ``http://www.example.com/package-1.0.0.tar.gz``
+
+badpath
+-------
+  
+Some developers may package their source code with a top-level directory name that differs
+from what is written to disk.
+
+Example: ``gtar tfvz tkdiff-4.2.tar.gz`` ::
+
+   -rw-r--r-- dorothyr/users 5910 2011-11-26 21:08 tkdiff-unix/CHANGELOG.txt
+   -rw-r--r-- dorothyr/users 18092 2011-11-26 21:08 tkdiff-unix/LICENSE.txt
+   -rwxr-xr-x dorothyr/users  1084 2011-11-26 21:08 tkdiff-unix/README.txt
+   -rwxr-xr-x dorothyr/users 341372 2011-11-26 21:08 tkdiff-unix/tkdiff
+   
+The *name* of the package is **tkdiff-4.2** and the directory structure is **tkdiff-unix**.
+This scenario will cause ipsbuild to fail unless the ``badpath`` keyword is used to circumvent the issue.
+
+Example: ::
+
+   badpath: tkdiff-unix
+
+arch
+----
+
+There are only two architectures available:
+
+- i386
+- sparc
+
+.. note:
+
+   There is no automatic architecture detection in IPS.
+   
+classification
+--------------
+
+.. _classification: http://docs.oracle.com/cd/E26502_01/html/E21383/gentextid-3283.html#scrolltoc
+
+For a list of package classifications please refer to the IPS package classification_ documentation.
+
+description
+-----------
+
+A long detailed description of your package.
+
+
 Directives
 ==========
 
@@ -95,6 +205,9 @@ Available shell expansion variables
 * **SPKGS** - ipsutils/SPKGS/[package]
 
 .. note::
+   All available *keywords* are expandable, too. 
+
+.. note::
    Macro expansion for ipsutils is in its infancy.  If you are familiar with macro expansion
    in RPM's SPEC implementation; there is nothing even remotely close to it here.  This will be
    addressed in the future.