* The Nitty Gritty
In general, =define-namespace= should work as you expect it to. But if you
need to understand why something is or isn't being namespaced, here's
the nitty gritty of how it happens.

** Quoted Lists
Quoted lists (be it with =quote= or =function=) are namespaced *only*
of the list is a =lambda= form (or a =macro= form). Arbitrary lists
are returned untouched (they are way too arbitrary to be handled
sanely). That is:
#+begin_src emacs-lisp
(define-namespace foo-
(defun infinite (y)
  (mapcar
   '(lambda (x) (infinite x))
   '(not a lambda (infinite x))))
)
#+end_src
expands to
#+begin_src emacs-lisp
(defun foo-infinite (y)
  (mapcar
   '(lambda (x) (foo-infinite x))
   '(not a lambda (infinite x))))
#+end_src

Note that = '(lambda ...)= is bad practice in Emacs, you should use
=(lambda ...)= instead (which is also namespaced just fine).

** Symbols Quoted with Quote
A symbol quoted with =quote= (or = ' =) is never namespaced.
#+begin_src emacs-lisp
(define-namespace foo-
(defvar var nil)
(defvaralias 'varalias 'var)
(defun fun nil)
(defalias 'alias 'fun)
(defalias 'otheralias 'var)
)
#+end_src
expands to
#+begin_src emacs-lisp
(defvar foo-var nil)
(defvaralias 'varalias 'var)
(defun foo-fun nil)
(defalias 'alias 'fun)
;;; foo-var is not a function, so:
(defalias 'otheralias 'var)
#+end_src

If you provide the =:assume-var-quote= keyword, quoted symbols will be
namespaced as variables instead.
** Symbols Quoted with Function
A symbol quoted with =function= (or =#' =) is assumed to be the name of a
function, and will be namespaced as such if possible. You may provide
the =:dont-assume-function-quote= keyword to disable this behaviour,
=function= will then be treated like =quote=.

#+begin_src emacs-lisp
(define-namespace foo-
(defun fun (x) x)
(mapcar 'fun somelist)
(mapcar #'fun somelist)
)
#+end_src
expands to
#+begin_src emacs-lisp
(defun foo-fun (x) x)
(mapcar 'fun somelist)
(mapcar #'foo-fun somelist)
#+end_src

** Backticks (quasi-quotes)
Backticks (or =`=) are handled as you would expect. Lists or simbles
quoted with a backtick are treated the same as those quoted with
regular quotes ([[#quoted-lists][see above]]), except anything prefixed by a comma (which
is effectively not quoted) is namespaced as usual.

** Local Variables Take Precedence
Local variables take precedence over namespace variables.
For instance
#+begin_src emacs-lisp
(define-namespace foo-
(defvar bar "2")

(defun funca (bar)
  (string-to-int bar))
)
#+end_src
expands to 
#+begin_src emacs-lisp
(defvar foo-bar "2")

(defun funca (bar)
  (string-to-int bar))
#+end_src

Note how the last =bar= isn't namespaced. That's because it is local
to the =funca= function, and takes precedence over the global
=foo-bar=. The argument list of functions, macros, and lambdas are
all local definitions.

By default, this does not happen with let bindings, they are
namespaced as usual (if the variable name in question has a global
definition). The reason is that let bindings are commonly used to
temporarily override global bindings. 

You can customize this behaviour with the =:no-let-vars= keyword.
Then:
#+begin_src emacs-lisp
(define-namespace foo- :no-let-vars
(defvar bar "2")

(let ((bar "1"))
  (string-to-int bar))
)
#+end_src
will expand to 
#+begin_src emacs-lisp
(defvar foo-bar "2")

(let ((bar "1"))
  (string-to-int bar))
#+end_src

** Macros
Macros are handled in a very intelligent manner. 

*Names* needs to know which parts of a macro's arguments are
evaluatable forms, and which are just arbitrary symbols. This presents
a challenge because macro arguments could be absolutely anything.
Fortunately, (good) macros already provide that information in their
=debug= declaration.

Thus, *Names* uses the macro's =edebug-spec-list= to find out which
arguments are evaluatable forms, and namespaces only those. Other
arguments are left untouched. Usually, this is not something you'll
need to worry about, it should just do what you expect from it. 

This is only relevant if you write your own macros. If you do,
remember to add a debug declaration in them.

*** The theading macros (~->~ and ~-->~)

The threading macros would require special treatment to namespace
correctly. However, you can use the ~:functionlike-macros~ keyword to
tell *Names* to treat them as regular functions.

For example, in the following snippet:
#+BEGIN_SRC emacs-lisp
(require 'dash)
(define-namespace foo-
:functionlike-macros (-> ->>)

(defvar var nil)
(defun fun (x &optional y)
  (concat x y))

(-> "some string"
    (fun var)
    fun)
)
#+END_SRC
the ~(fun var)~ part would be namespaced prefectly fine (~fun~ and
~var~ will be identified as a function and variable respectively),
because it looks like a regular function call. However, the second use
of ~fun~ will not be correctly namespaced, because that ~fun~ looks
like a variable.

In other words, you should use these macros like this instead:
#+BEGIN_SRC emacs-lisp
(-> "some string"
    (fun var)
    (fun))
#+END_SRC

** Accessing Global Symbols
If one of your definitions shadows a global definition, you can still
access it by prefixing it with =::=.

#+begin_src emacs-lisp
(define-namespace foo-
(defun message ()  
  (message)
  (::message "Hi"))
)
#+end_src
expands to 
#+begin_src emacs-lisp
(defun foo-message ()  
  (foo-message)
  (message "Hi"))
#+end_src

When in doubt feel free to use =::=, it will always get removed (as
long as it's not inside a =quote=). You may also change this prefix to
something else with the =:prefix= keyword.
