--- /dev/null
+#+OPTIONS: toc:nil num:nil
+
+* Names [[https://secure.travis-ci.org/Bruce-Connor/names.png?branch=master]]
+
+*Names* is designed as a practical, complete, robust, and debuggable
+tool which writes your namespaces for you.
+
+[[file:package-example.png]]\\
+/Example usage of Names to namespace an emacs-lisp function./
+*** A Namespace implementation for Emacs-Lisp
+
+The *Names* package aims to provide an implementation of
+namespaces in Emacs with four guiding principles:
+
+- Practical :: Actually useful and easy to grasp.
+- Completeness :: Support any macro/function/special-form available in
+ emacs-lisp, even the ones defined by you or a third
+ party.
+- Robustness :: No-surprises, well-tested, and with clearly stated
+ limitations. Yes, as complete as we aim to be,
+ there will be limitations.
+- Debuggable :: Support *edebug* and =eval-defun=, as well as any
+ other essential tools for package developers.
+
+See [[https://github.com/Bruce-Connor/spaces#why-a-namespace-package][Why a namespace package?]] for a description on why this is
+necessary, and see [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/Other-Packages.org][Other-Packages.org]] for a description and comparison
+of previous packages attempting similar things.
+
+**** Version Compatibility
+Currently, *Names* is being supported on the entire Emacs 24 family
+(24.1--24.4). Any new changes or pull requests are tested on a
+[[https://travis-ci.org/Bruce-Connor/names][Travis-CI machine]]. See the /“tests”/ subdirectory for our test suite,
+and see .
+
+** Usage
+The [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/UsageExample.org][UsageExample]] file clearly displays and explains how to use *Names*
+in your package. There are few simple measures to take. Go have a look
+if you’re interested, I promise it’s worth it!
+
+If you want deeper descriptions of use-cases, see [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/TheNittyGritty.org][TheNittyGritty.org]].
+
+** Developer Tools
+*Names* offers a series of tools to make package writing more
+convenient inside a namespace. These developer facilities are on this
+separate file, so the file isn't loaded on the user's computer when
+your package calls =(require 'names)=.
+
+To access them add the following line to your init file.
+#+begin_src emacs-lisp
+(require 'names-dev)
+#+end_src
+
+*** Edebug and eval-defun support
+
+First and foremost, the =edebug-eval-defun= command (bound to =C-u
+C-M-x=) is an essential tool for any package developer. *Names*
+wouldn't be a very useful utility if it prevented you from using this
+asset.
+
+Therefore, it provides the =names-eval-defun= command, which is
+identical to =edebug-eval-defun= except it also works inside
+namespaces. It will automatically be added to your
+=emacs-lisp-mode-map=.
+
+*** Font-locking
+Font-lock for =define-namespace= and =:autoload=.
+
+*** Expansion and comparison functions
+=names-compare-forms= and =names-print= offer information when
+something just doesn't seem to make sense.
+
+** Nomenclature
+
+The name of this package is *Names*, always with a capital “N”.
+Despite the word being plural, refer to it in the singular (e.g.,
+“Names is an amazing achievement”). If possible consider giving it a
+slight emphasis, such as: /Names/.
+When there's a risk of confusion or ambiguity, be it due to context or
+lack of knowledge by the reader, =names.el= is also acceptable.
+
+** Why a namespace package?
+Plain and simple: Emacs doesn't have namespaces, and it needs them.
+
+Nic Ferrier has a [[http://nic.ferrier.me.uk/blog/2013_06/adding-namespaces-to-elisp][great essay on the subject]]. Note that
+*Names* is very different from the solution he proposes, but it does
+solve the problem he had with other alternatives which left the
+debugger unusable.
+
+Emacs takes the approach of prefixing every symbol name with the name
+of the package. This successfully avoids name clashes between
+packages, but it quickly leads to code that's repetitive and annoying
+to write. Below is an example from =package.el=, the word "/package/"
+is repeated 7 times in a 10-line function.
+
+*Names* doesn't change this overall approach. It adheres to Emacs
+standards and is completely invisible to the end-user. *Names* simply
+gives /you/ (the developer) a convenient way of writing code that
+adheres to this standard.
+
+[[file:package-example.png]]
+/Example usage of Names to namespace an emacs-lisp function./
+
+- At runtime, the right-hand-side will create the same definitions as the left-hand-side.
+- At compilation, it will create the exact same compiled file (with no left-over reference to =names.el= functions).
+
+*** Tested On:
+Below are the packages on which I've tested *Names*. If you're
+interested, try using it on one of your packages and [[https://github.com/Bruce-Connor/names/issues][let me know how
+it goes]].
+**** elnode
+- *Number of ert tests passed:* Same as before namespacing (62).
+- *Reduction in code size:* Approx. 2000 characters.
+**** s.el
+- *Number of ert tests passed:* All.
+- *Reduction in code size:* Approx. 1000 characters (8%).
+1000 characters is a lot when you consider /s.el/ has the second
+shortest namespace possible, =s-=.
+**** dash.el
+- *Number of ert tests passed:* Same as before namespacing (104).
+**** latex-extra
+- *Number of ert tests passed:* ALL.
+**** aggressive-indent
+No actual tests defined, but this package actually uses /Names/ for
+real! And it's alive and well.