Add keyword explanation and beginning of howto section

1 files changed, 90 insertions, 2 deletions

diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
index 73148c1..5a54b1f 100644
--- a/docs/source/tutorial.rst
+++ b/docs/source/tutorial.rst
@@ -58,9 +58,10 @@ Download ``ccache`` directly with ``wget``::
 Creating a SPEC file
 --------------------
 
-Writing an ipsutils SPEC file from scratch feels like a daunting task, 
+Writing an ipsutils SPEC file from scratch is a daunting task, 
 much like when working with RPM SPEC files.  There is a utility, ``ipsutils-newspec`` 
-available to help help 
+available to help.  This creates all available keywords and directives so that you
+may pick and choose which ones to fill out.
 
 ::
 
@@ -101,5 +102,92 @@ Contents of generated file::
    %end
 
 
+What are these keywords you speak of?
+-------------------------------------
 
+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``
+
+arch
+~~~~
+
+There are only two architectures available:
+
+- i386
+- sparc
+
+.. note:
+
+   This keyword is mandatory.  There is no automatic architecture detection in IPS.
+   
+classification
+~~~~~~~~~~~~~~
+
+For a list of package classifications please refer to `this site <http://docs.oracle.com/cd/E26502_01/html/E21383/gentextid-3283.html#scrolltoc>`_.
+
+description
+~~~~~~~~~~~
+
+A long detailed description of your package.
+
+
+Filling in the blanks
+=====================
+
+yadda yadda
\ No newline at end of file