README fixes and additions.v1.0.0

1 files changed, 94 insertions, 74 deletions

diff --git a/README.rst b/README.rst
index 6002c1c..0f7b852 100644
--- a/README.rst
+++ b/README.rst
@@ -2,129 +2,149 @@ setuptools_scm
 ===============
 
 About
-~~~~~~
+-----
 
-:code:`setuptools_scm` is a simple setup_requires utility for use
-in mercurial and git based projects.
+:code:`setuptools_scm` is a simple utility for the ``setup_requires``
+feature of setuptools for use in `Mercurial <http://mercurial.selenic.com/>`_
+and `Git <http://git-scm.com/>`_ based projects.
 
-It uses metadata from the scm to generate the **version** of a project
-and to list the files belonging to that project
-(makes MANIFEST.in unnecessary in many cases).
+It uses metadata from the SCM to generate the **version** of a project
+and is able to list the files belonging to that project
+(which makes the :code:`MANIFEST.in` file unnecessary in many cases).
 
-It falls back to PKG-INFO/.hg_archival.txt when necessary/
+It falls back to ``PKG-INFO``/``.hg_archival.txt`` when necessary.
 
-Standard Version Generation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Default behavior
+----------------
 
-In the standard configurations setuptools_scm takes a look at 3 things
+In the standard configuration setuptools_scm takes a look at 3 things:
 
-1. latest tag
-2. the distance to this tag
-3. workdir state
+1. latest tag (with a version number)
+2. the distance to this tag (e.g. number of revisions since latest tag)
+3. workdir state (e.g. uncommitted changes since latest tag)
 
-and uses roughly the following logic to render the version
+and uses roughly the following logic to render the version:
 
-not distance and clean
+no distance and clean:
     :code:`{tag}`
-distance and clean
+distance and clean:
     :code:`{next_version}.dev{distance}+n{revision hash}`
-not distance and not clean
+no distance and not clean:
     :code:`{tag}+dYYYMMMDD`
-distance and not clean
+distance and not clean:
     :code:`{next_version}.dev{distance}+n{revision hash}.dYYYMMMDD`
 
-
-The next version is calculated by adding 1 to the last numeric component
+The next version is calculated by adding ``1`` to the last numeric component
 of the tag.
 
-Using Semver
-~~~~~~~~~~~~
-
-Due to the default behaviour its necessary to always include a
-patch version, else the automatic guessing will increment the wrong part
-of the semver. (i.e. tag 2.0 results in 2.1.devX instead of 2.0.1.devX)
+Semantic Versioning (SemVer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Due to the default behavior it's necessary to always include a
+patch version (the ``3`` in ``1.2.3``), or else the automatic guessing
+will increment the wrong part of the semver (e.g. tag ``2.0`` results in
+``2.1.devX`` instead of ``2.0.1.devX``). So please make sure to tag
+accordingly.
 
-Future versions of setuptools_scm will switch to semver by default,
-hiding the the old behaviour as configurable option
+.. note::
 
+    Future versions of setuptools_scm will switch to
+    `SemVer <http://semver.org/>`_ by default hiding the the old behavior
+    as an configurable option.
 
-Setup.py
-~~~~~~~~
+Setup.py usage
+--------------
 
-.. code:: python
+To use setuptools_scm simple modify your project's setup.py file like this:
 
-    from setuptools import setup
-    setup(
-        ...,
-        use_scm_version=True,
-        setup_requires=['setuptools_scm'],
-        ...,
-    )
+1. Add the :code:`use_scm_version` parameter and set it to ``True``
 
-In order to configure the way use_scm_version works
-you an provide a mapping with options instead of simple truth value.
+2. Add :code:`'setuptools_scm'` to the :code:`setup_requires` parameter
 
+   E.g.:
+   
+   .. code:: python
+   
+       from setuptools import setup
+       setup(
+           ...,
+           use_scm_version=True,
+           setup_requires=['setuptools_scm'],
+           ...,
+       )
+   
+In order to configure the way ``use_scm_version`` works you can provide
+a mapping with options instead of simple boolean value.
 
-currently supported configuration keys are:
+The Currently supported configuration keys are:
 
 :version_scheme:
-    configures how the local version number is constructed
-    either a entrypoint name or a callable
+    configures how the local version number is constructed.
+    either an entrypoint name or a callable
+
 :local_scheme:
     configures how the local component of the version is constructed
-    either a entrypoint name or a callable
+    either an entrypoint name or a callable
 
-To use setuptools_scm in other python code
-you can use the get_version function.
+To use setuptools_scm in other Python code you can use the
+``get_version`` function:
 
 .. code:: python
 
     from setuptools_scm import get_version
     my_version = get_version()
 
-It suports the keys of the setup.py use_scm_version
-flag as keyword arguments.
-
+It optionally accepts the keys of the ``use_scm_version`` parameter as
+keyword arguments.
 
-extending setuptools_scm
+Extending setuptools_scm
 ------------------------
 
-adding new scm
-~~~~~~~~~~~~~~
+setuptools_scm ships with a few setuptools entrypoints based hooks to extend
+its default capabilities.
 
-setuptools_scm provides 2 entrypoints for adding new scms
+Adding a new SCM
+~~~~~~~~~~~~~~~~
 
-**setuptools_scm.parse_scm**
-    a function used to parse the metadata of the current workdir
-    use the name of the control directoy/file of your scm as name
+setuptools_scm provides 2 entrypoints for adding new SCMs
 
-    the return value MUST be a ScmVersion instance created by the
-    function :code:`setuptools_scm.version:meta`
+``setuptools_scm.parse_scm``
+    A function used to parse the metadata of the current workdir
+    using the name of the control directory/file of your SCM as the
+    entrypoint's name. E.g. for the built-in entrypoint for git the
+    entrypoint is named :code:`.git` and references
+    :code:`'setuptools_scm.git:parse'`.
 
-**setuptools_scm.files_command**
-    either a string containing a shell command
-    that prints all scm managed files in its current working directory
-    or a callable, that given a pathname will return
+    The return value MUST be a :code:`setuptools.version.ScmVersion` instance
+    created by the function :code:`setuptools_scm.version:meta`.
 
-    also use then name of your scm control directory as name of the entrypoint
+``setuptools_scm.files_command``
+    Either a string containing a shell command that prints all SCM managed
+    files in its current working directory or a callable, that given a
+    pathname will return that list.
 
+    Also use then name of your SCM control directory as name of the entrypoint.
 
-version number constructions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Version number construction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**setuptools_scm.version_scheme**
-    configures how the version number is constructed
+``setuptools_scm.version_scheme``
+    Configures how the version number is constructed given a
+    :code:`setuptools.version.ScmVersion` instance and should return a string
+    representing the version.
 
-    availiable implementations:
+    Available implementations:
 
-    :guess-next-dev: automatically guess the next development version
-    :post-release: generate post release versions
+    :guess-next-dev: automatically guesses the next development version (default)
+    :post-release: generates post release versions (adds :code:`postN`)
 
-**setuptools_scm.local_scheme**
-    configures how the local part of a version is rendered
+``setuptools_scm.local_scheme``
+    Configures how the local part of a version is rendered given a
+    :code:`setuptools.version.ScmVersion` instance and should return a string
+    representing the local version.
 
-    availiable implementations:
+    Available implementations:
 
-    :node-and-date: adds the node on dev versions and the date on dirty workdir
+    :node-and-date: adds the node on dev versions and the date on dirty
+                    workdir (default)
     :dirty-tag: adds :code:`+dirty` if the current workdir has changes