Deprecation using macros and metadata

Hi all,

I've written a first-draft of section about deprecating library functions.  The intro goes:

When maintaining a library that other programmers rely on to get their work done it behooves you to be thoughtful when making changes. In the process of fixing bugs and making improvements to your library you will eventually wish to change its public interface. Making changes to a public-facing protion of your library is no small matter, but assuming that you’ve determined its necessity then you’ll want to deprecate the functions that are obsolete. The term deprecate basically means that a given function should be avoided in favor of some other, newer function. This section details an approach to deprecating API functions and reporting existing deprecations using Clojure macros.