branch: master
commit 4ee3bb48cffd2a198be02676641c9b30a3452ed3
Author: Artur Malabarba <bruce.connor...@gmail.com>
Commit: Artur Malabarba <bruce.connor...@gmail.com>
packages/names.el: Better Readme
---
Readme.org | 23 +++++++++++------------
UsageExample.org | 32 ++++++++++----------------------
2 files changed, 21 insertions(+), 34 deletions(-)
diff --git a/Readme.org b/Readme.org
index c4d481c..ef55b04 100644
--- a/Readme.org
+++ b/Readme.org
@@ -16,14 +16,13 @@ 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.
+- Complete :: Support any macro, function, or special-form available in
+ emacs-lisp, /even/ the ones defined by you or a third
+ party.
+- Robust :: No-surprises, well-tested, and with clearly stated
+ limitations.
+- Debuggable :: Support *edebug* and =eval-defun=, and any other
+ package developing tools.
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
@@ -84,10 +83,10 @@ 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.
+Nic Ferrier has a
[[http://nic.ferrier.me.uk/blog/2013_06/adding-namespaces-to-elisp][great essay
on the subject]], and you might want to
+read
[[https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00772.html][an
opposing opinion]] as well. 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
diff --git a/UsageExample.org b/UsageExample.org
index 9c0ceb4..db49887 100644
--- a/UsageExample.org
+++ b/UsageExample.org
@@ -7,22 +7,14 @@ The important items are already listed in the Readme:
#+BEGIN_SRC emacs-lisp
-;;; example-package.el --- Just an example
+;;; example.el --- Just an example
;;; You have to add this requirement!!
;; Package-Requires: ((names "0.5"))
-;;; Commentary:
-
-;; Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla
-;; Bla Bla Bla Bla
-
;;; Code:
-;;; Require us. After compilation there will be NO leftover reference
-;;; to the names package.
-
-(eval-when-compile (require 'names))
+;; `define-namespace' is autoloaded, so there's no need to require `names'.
;;;###autoload
(define-namespace example-
@@ -33,8 +25,8 @@ The important items are already listed in the Readme:
"Evaluate BODY, don't evaluate NAME."
(declare (debug (sexp body-form))
(indent defun))
- ;; `example-has-courage' here is inside a quoted
- ;; form, so it needs to be written explicitly.
+ ;; `example-has-courage' is inside a quoted form, so it needs to be
+ ;; written explicitly.
`(let ((example-has-courage ',name))
,@body))
@@ -48,15 +40,13 @@ The important items are already listed in the Readme:
(defun -fight-internal ()
"Called by `example-fight'"
(when has-courage
- ;; `has-courage' here is will be expanded to
- ;; `example-has-courage'.
+ ;; `has-courage' here is will be expanded to `example-has-courage'.
(let ((has-courage nil))
- ;; Victory!
- )))
+ (message "Victory!"))))
)
-(provide 'example-package)
-;;; example-package.el ends here
+(provide 'example)
+;;; example.el ends here
#+END_SRC
@@ -86,14 +76,12 @@ To see this expansion yourself.
"Called by `example-fight'"
(when example-has-courage
(let ((has-courage nil))
- ;; Victory!
- )))
+ (message "Victory!"))))
#+END_SRC
* Usage Instructions
-The
-follow these steps:
+Follow these steps:
1. Remember to list =names= as a dependency, and =require= it.
2. Wrap all code that's to be namespaced inside a =(define-namespace NAME
...)= macro.
