Merge pull request #59 from jean/master

Editing while reading

8 files changed, 222 insertions, 221 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index b4840ba..1e8489b 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -4,6 +4,7 @@ Changes
 4.3.3 (unreleased)
 ------------------
 
+- Correct typos and ReST formatting errors in documentation.
 - Fix C optimizations broken on Py3k.  See the Python bug at:
   http://bugs.python.org/issue15657
   (https://github.com/zopefoundation/zope.interface/issues/60)
diff --git a/docs/README.rst b/docs/README.rst
index bb5f9cd..0c55c10 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -36,7 +36,7 @@ Interfaces are defined using Python ``class`` statements:
 
 In the example above, we've created an interface, :class:`IFoo`.  We
 subclassed :class:`zope.interface.Interface`, which is an ancestor interface for
-all interfaces, much as `object` is an ancestor of all new-style
+all interfaces, much as ``object`` is an ancestor of all new-style
 classes [#create]_.   The interface is not a class, it's an Interface,
 an instance of :class:`zope.interface.interface.InterfaceClass`:
 
@@ -68,19 +68,19 @@ and even its module:
 
 The interface defined two attributes:
 
-`x`
+``x``
   This is the simplest form of attribute definition.  It has a name
   and a doc string.  It doesn't formally specify anything else.
 
-`bar`
+``bar``
   This is a method.  A method is defined via a function definition.  A
   method is simply an attribute constrained to be a callable with a
   particular signature, as provided by the function definition.
 
-  Note that `bar` doesn't take a `self` argument.  Interfaces document
+  Note that ``bar`` doesn't take a ``self`` argument.  Interfaces document
   how an object is *used*.  When calling instance methods, you don't
-  pass a `self` argument, so a `self` argument isn't included in the
-  interface signature.  The `self` argument in instance methods is
+  pass a ``self`` argument, so a ``self`` argument isn't included in the
+  interface signature.  The ``self`` argument in instance methods is
   really an implementation detail of Python instances. Other objects,
   besides instances can provide interfaces and their methods might not
   be instance methods. For example, modules can provide interfaces and
@@ -105,7 +105,7 @@ syntax:
 
   >>> IFoo.get('y')
 
-You can use `in` to determine if an interface defines a name:
+You can use ``in`` to determine if an interface defines a name:
 
 .. doctest::
 
@@ -193,8 +193,8 @@ function in a class statement:
   ...         return "Foo(%s)" % self.x
 
 
-In this example, we declared that `Foo` implements `IFoo`. This means
-that instances of `Foo` provide `IFoo`.  Having made this declaration,
+In this example, we declared that ``Foo`` implements ``IFoo``. This means
+that instances of ``Foo`` provide ``IFoo``.  Having made this declaration,
 there are several ways we can introspect the declarations.  First, we
 can ask an interface whether it is implemented by a class:
 
@@ -211,7 +211,7 @@ And we can ask whether an interface is provided by an object:
   >>> IFoo.providedBy(foo)
   True
 
-Of course, `Foo` doesn't provide `IFoo`, it implements it:
+Of course, ``Foo`` doesn't *provide* ``IFoo``, it *implements* it:
 
 .. doctest::
 
@@ -264,11 +264,11 @@ classes).  We do this using a Python-2.4-style decorator named
   >>> list(zope.interface.implementedBy(yfoo))
   [<InterfaceClass __builtin__.IFoo>]
 
-Note that the implementer decorator may modify it's argument. Callers
+Note that the implementer decorator may modify its argument. Callers
 should not assume that a new object is created.
 
 Using implementer also works on callable objects. This is used by
-zope.formlib, as an example:
+:py:mod:`zope.formlib`, as an example:
 
 .. doctest::
 
@@ -285,7 +285,7 @@ zope.formlib, as an example:
 
 XXX: Double check and update these version numbers:
 
-In zope.interface 3.5.2 and lower, the implementer decorator can not
+In :py:mod:`zope.interface` 3.5.2 and lower, the implementer decorator can not
 be used for classes, but in 3.6.0 and higher it can:
 
 .. doctest::
@@ -294,7 +294,7 @@ be used for classes, but in 3.6.0 and higher it can:
   >>> list(zope.interface.providedBy(Foo()))
   [<InterfaceClass __builtin__.IFoo>]
   
-Note that class decorators using the @implementer(IFoo) syntax are only 
+Note that class decorators using the ``@implementer(IFoo)`` syntax are only 
 supported in Python 2.6 and later.
 
 
@@ -302,10 +302,10 @@ Declaring provided interfaces
 -----------------------------
 
 We can declare interfaces directly provided by objects.  Suppose that
-we want to document what the `__init__` method of the `Foo` class
-does.  It's not *really* part of `IFoo`.  You wouldn't normally call
-the `__init__` method on Foo instances.  Rather, the `__init__` method
-is part of the `Foo`'s `__call__` method:
+we want to document what the ``__init__`` method of the ``Foo`` class
+does.  It's not *really* part of ``IFoo``.  You wouldn't normally call
+the ``__init__`` method on Foo instances.  Rather, the ``__init__`` method
+is part of ``Foo``'s ``__call__`` method:
 
 .. doctest::
 
@@ -358,14 +358,14 @@ declaration from within a class statement:
   >>> IFooFactory.providedBy(Foo2)
   True
 
-There's a similar function, `moduleProvides`, that supports interface
+There's a similar function, ``moduleProvides``, that supports interface
 declarations from within module definitions.  For example, see the use
-of `moduleProvides` call in `zope.interface.__init__`, which declares that
-the package `zope.interface` provides `IInterfaceDeclaration`.
+of ``moduleProvides`` call in ``zope.interface.__init__``, which declares that
+the package ``zope.interface`` provides ``IInterfaceDeclaration``.
 
 Sometimes, we want to declare interfaces on instances, even though
 those instances get interfaces from their classes.  Suppose we create
-a new interface, `ISpecial`:
+a new interface, ``ISpecial``:
 
 .. doctest::
 
@@ -374,8 +374,8 @@ a new interface, `ISpecial`:
   ...     def brag():
   ...         "Brag about being special"
 
-We can make an existing foo instance special by providing `reason`
-and `brag` attributes:
+We can make an existing foo instance special by providing ``reason``
+and ``brag`` attributes:
 
 .. doctest::
 
@@ -434,7 +434,7 @@ Normally, declarations are inherited:
   [<InterfaceClass __builtin__.ISpecial>, <InterfaceClass __builtin__.IFoo>]
 
 Sometimes, you don't want to inherit declarations.  In that case, you
-can use `implementsOnly`, instead of `implements`:
+can use ``implementsOnly``, instead of ``implements``:
 
 .. doctest::
 
@@ -456,7 +456,7 @@ External declarations
 Normally, we make implementation declarations as part of a class
 definition. Sometimes, we may want to make declarations from outside
 the class definition. For example, we might want to declare interfaces
-for classes that we didn't write.  The function `classImplements` can
+for classes that we didn't write.  The function ``classImplements`` can
 be used for this purpose:
 
 .. doctest::
@@ -468,7 +468,7 @@ be used for this purpose:
   >>> list(zope.interface.implementedBy(C))
   [<InterfaceClass __builtin__.IFoo>]
 
-We can use `classImplementsOnly` to exclude inherited interfaces:
+We can use ``classImplementsOnly`` to exclude inherited interfaces:
 
 .. doctest::
 
@@ -550,7 +550,7 @@ the other interfaces as base interfaces:
   >>> names
   ['bar', 'eek', 'x', 'y']
 
-Note that `IBaz` overrides eek:
+Note that ``IBaz`` overrides ``eek``:
 
 .. doctest::
 
@@ -559,7 +559,7 @@ Note that `IBaz` overrides eek:
   >>> IBaz['eek'].__doc__
   'eek in baz blah'
 
-We were careful to override eek in a compatible way.  When extending
+We were careful to override ``eek`` in a compatible way.  When extending
 an interface, the extending interface should be compatible [#compat]_
 with the extended interfaces.
 
@@ -579,7 +579,7 @@ Note that interfaces don't extend themselves:
   >>> IBaz.extends(IBaz)
   False
 
-Sometimes we wish they did, but we can, instead use `isOrExtends`:
+Sometimes we wish they did, but we can instead use ``isOrExtends``:
 
 .. doctest::
 
@@ -592,7 +592,7 @@ Sometimes we wish they did, but we can, instead use `isOrExtends`:
 
 When we iterate over an interface, we get all of the names it defines,
 including names defined by base interfaces. Sometimes, we want *just*
-the names defined by the interface directly. We bane use the `names`
+the names defined by the interface directly. We can use the ``names``
 method for that:
 
 .. doctest::
@@ -625,8 +625,8 @@ inherited from the most specific interface. For example, with:
   >>> class ISub(IBase1, IBase2):
   ...     pass
 
-ISub's definition of foo is the one from IBase2, since IBase2 is more
-specific that IBase:
+``ISub``'s definition of ``foo`` is the one from ``IBase2``, since ``IBase2`` is more
+specific than ``IBase``:
 
 .. doctest::
 
@@ -671,7 +671,7 @@ interfaces that they declare:
   >>> baz_implements.isOrExtends(baz_implements)
   True
 
-Specifications (interfaces and declarations) provide an `__sro__`
+Specifications (interfaces and declarations) provide an ``__sro__``
 that lists the specification and all of it's ancestors:
 
 .. doctest::
@@ -735,7 +735,7 @@ Invariants
 Interfaces can express conditions that must hold for objects that
 provide them. These conditions are expressed using one or more
 invariants.  Invariants are callable objects that will be called with
-an object that provides an interface. An invariant raises an `Invalid`
+an object that provides an interface. An invariant raises an ``Invalid``
 exception if the condition doesn't hold.  Here's an example:
 
 .. doctest::
@@ -780,9 +780,9 @@ Interfaces have a method for checking their invariants:
   RangeError: Range(2, 1)
 
 If you have multiple invariants, you may not want to stop checking
-after the first error.  If you pass a list to `validateInvariants`,
-then a single `Invalid` exception will be raised with the list of
-exceptions as it's argument:
+after the first error.  If you pass a list to ``validateInvariants``,
+then a single ``Invalid`` exception will be raised with the list of
+exceptions as its argument:
 
 .. doctest::
 
@@ -801,7 +801,6 @@ And the list will be filled with the individual exceptions:
   >>> errors
   [RangeError(Range(2, 1))]
 
-
   >>> del errors[:]
 
 Adaptation
@@ -809,9 +808,9 @@ Adaptation
 
 Interfaces can be called to perform adaptation.
 
-The semantics are based on those of the PEP 246 adapt function.
+The semantics are based on those of the PEP 246 ``adapt`` function.
 
-If an object cannot be adapted, then a TypeError is raised:
+If an object cannot be adapted, then a ``TypeError`` is raised:
 
 .. doctest::
 
@@ -824,7 +823,6 @@ If an object cannot be adapted, then a TypeError is raised:
   TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)
 
 
-
 unless an alternate value is provided as a second positional argument:
 
 .. doctest::
@@ -843,7 +841,7 @@ If an object already implements the interface, then it will be returned:
   >>> I(obj) is obj
   True
 
-If an object implements __conform__, then it will be used:
+If an object implements ``__conform__``, then it will be used:
 
 .. doctest::
 
@@ -855,7 +853,7 @@ If an object implements __conform__, then it will be used:
   >>> I(C())
   0
 
-Adapter hooks (see __adapt__) will also be used, if present:
+Adapter hooks (see ``__adapt__``) will also be used, if present:
 
 .. doctest::
 
@@ -874,23 +872,23 @@ Adapter hooks (see __adapt__) will also be used, if present:
   ...
   TypeError: ('Could not adapt', 0, <InterfaceClass __builtin__.I>)
 
-__adapt__
----------
+``__adapt__``
+-------------
 
 .. doctest::
 
   >>> class I(zope.interface.Interface):
   ...     pass
 
-Interfaces implement the PEP 246 __adapt__ method.
+Interfaces implement the PEP 246 ``__adapt__`` method.
 
 This method is normally not called directly. It is called by the PEP
-246 adapt framework and by the interface __call__ operator.
+246 adapt framework and by the interface ``__call__`` operator.
 
-The adapt method is responsible for adapting an object to the
+The ``adapt`` method is responsible for adapting an object to the
 reciever.
 
-The default version returns None:
+The default version returns ``None``:
 
 .. doctest::
 
@@ -909,7 +907,7 @@ unless the object given provides the interface:
 
 Adapter hooks can be provided (or removed) to provide custom
 adaptation. We'll install a silly hook that adapts 0 to 42.
-We install a hook by simply adding it to the adapter_hooks
+We install a hook by simply adding it to the ``adapter_hooks``
 list:
 
 .. doctest::
@@ -923,7 +921,7 @@ list:
   >>> I.__adapt__(0)
   42
 
-Hooks must either return an adapter, or None if no adapter can
+Hooks must either return an adapter, or ``None`` if no adapter can
 be found.
 
 Hooks can be uninstalled by removing them from the list:
@@ -934,14 +932,14 @@ Hooks can be uninstalled by removing them from the list:
   >>> I.__adapt__(0)
 
 
-.. [#create] The main reason we subclass `Interface` is to cause the
+.. [#create] The main reason we subclass ``Interface`` is to cause the
              Python class statement to create an interface, rather
              than a class.
 
              It's possible to create interfaces by calling a special
              interface class directly.  Doing this, it's possible
              (and, on rare occasions, useful) to create interfaces
-             that don't descend from `Interface`.  Using this
+             that don't descend from ``Interface``.  Using this
              technique is beyond the scope of this document.
 
 .. [#factory] Classes are factories.  They can be called to create
@@ -953,8 +951,8 @@ Hooks can be uninstalled by removing them from the list:
 .. [#compat] The goal is substitutability.  An object that provides an
              extending interface should be substitutable for an object
              that provides the extended interface.  In our example, an
-             object that provides IBaz should be usable whereever an
-             object that provides IBlat is expected.
+             object that provides ``IBaz`` should be usable wherever an
+             object that provides ``IBlat`` is expected.
 
-             The interface implementation doesn't enforce this.
+             The interface implementation doesn't enforce this,
              but maybe it should do some checks.
diff --git a/docs/adapter.rst b/docs/adapter.rst
index b948705..c5c65e5 100644
--- a/docs/adapter.rst
+++ b/docs/adapter.rst
@@ -22,33 +22,33 @@ Let's look at a simple example, using a single required specification:
   >>> from zope.interface.adapter import AdapterRegistry
   >>> import zope.interface
 
-  >>> class IR1(zope.interface.Interface):
+  >>> class IRequire1(zope.interface.Interface):
   ...     pass
-  >>> class IP1(zope.interface.Interface):
+  >>> class IProvide1(zope.interface.Interface):
   ...     pass
-  >>> class IP2(IP1):
+  >>> class IProvide2(IProvide1):
   ...     pass
 
   >>> registry = AdapterRegistry()
 
-We'll register an object that depends on IR1 and "provides" IP2:
+We'll register an object that depends on ``IRequire1`` and "provides" ``IProvide2``:
 
 .. doctest::
 
-  >>> registry.register([IR1], IP2, '', 12)
+  >>> registry.register([IRequire1], IProvide2, '', 12)
 
 Given the registration, we can look it up again:
 
 .. doctest::
 
-  >>> registry.lookup([IR1], IP2, '')
+  >>> registry.lookup([IRequire1], IProvide2, '')
   12
 
 Note that we used an integer in the example.  In real applications,
 one would use some objects that actually depend on or provide
 interfaces. The registry doesn't care about what gets registered, so
 we'll use integers and strings to keep the examples simple. There is
-one exception.  Registering a value of None unregisters any
+one exception.  Registering a value of ``None`` unregisters any
 previously-registered value.
 
 If an object depends on a specification, it can be looked up with a
@@ -56,9 +56,9 @@ specification that extends the specification that it depends on:
 
 .. doctest::
 
-  >>> class IR2(IR1):
+  >>> class IRequire2(IRequire1):
   ...     pass
-  >>> registry.lookup([IR2], IP2, '')
+  >>> registry.lookup([IRequire2], IProvide2, '')
   12
 
 We can use a class implementation specification to look up the object:
@@ -66,9 +66,9 @@ We can use a class implementation specification to look up the object:
 .. doctest::
 
   >>> class C2:
-  ...     zope.interface.implements(IR2)
+  ...     zope.interface.implements(IRequire2)
 
-  >>> registry.lookup([zope.interface.implementedBy(C2)], IP2, '')
+  >>> registry.lookup([zope.interface.implementedBy(C2)], IProvide2, '')
   12
 
 
@@ -77,9 +77,9 @@ extends:
 
 .. doctest::
 
-  >>> registry.lookup([IR1], IP1, '')
+  >>> registry.lookup([IRequire1], IProvide1, '')
   12
-  >>> registry.lookup([IR2], IP1, '')
+  >>> registry.lookup([IRequire2], IProvide1, '')
   12
 
 But if you require a specification that doesn't extend the specification the
@@ -87,13 +87,13 @@ object depends on, you won't get anything:
 
 .. doctest::
 
-  >>> registry.lookup([zope.interface.Interface], IP1, '')
+  >>> registry.lookup([zope.interface.Interface], IProvide1, '')
 
 By the way, you can pass a default value to lookup:
 
 .. doctest::
 
-  >>> registry.lookup([zope.interface.Interface], IP1, '', 42)
+  >>> registry.lookup([zope.interface.Interface], IProvide1, '', 42)
   42
 
 If you try to get an interface the object doesn't provide, you also
@@ -101,46 +101,46 @@ won't get anything:
 
 .. doctest::
 
-  >>> class IP3(IP2):
+  >>> class IProvide3(IProvide2):
   ...     pass
-  >>> registry.lookup([IR1], IP3, '')
+  >>> registry.lookup([IRequire1], IProvide3, '')
 
 You also won't get anything if you use the wrong name:
 
 .. doctest::
 
-  >>> registry.lookup([IR1], IP1, 'bob')
-  >>> registry.register([IR1], IP2, 'bob', "Bob's 12")
-  >>> registry.lookup([IR1], IP1, 'bob')
+  >>> registry.lookup([IRequire1], IProvide1, 'bob')
+  >>> registry.register([IRequire1], IProvide2, 'bob', "Bob's 12")
+  >>> registry.lookup([IRequire1], IProvide1, 'bob')
   "Bob's 12"
 
 You can leave the name off when doing a lookup:
 
 .. doctest::
 
-  >>> registry.lookup([IR1], IP1)
+  >>> registry.lookup([IRequire1], IProvide1)
   12
 
-If we register an object that provides IP1:
+If we register an object that provides ``IProvide1``:
 
 .. doctest::
 
-  >>> registry.register([IR1], IP1, '', 11)
+  >>> registry.register([IRequire1], IProvide1, '', 11)
 
-then that object will be prefered over O(12):
+then that object will be prefered over ``O(12)``:
 
 .. doctest::
 
-  >>> registry.lookup([IR1], IP1, '')
+  >>> registry.lookup([IRequire1], IProvide1, '')
   11
 
-Also, if we register an object for IR2, then that will be prefered
-when using IR2:
+Also, if we register an object for ``IRequire2``, then that will be preferred
+when using ``IRequire2``:
 
 .. doctest::
 
-  >>> registry.register([IR2], IP1, '', 21)
-  >>> registry.lookup([IR2], IP1, '')
+  >>> registry.register([IRequire2], IProvide1, '', 21)
+  >>> registry.lookup([IRequire2], IProvide1, '')
   21
 
 Finding out what, if anything, is registered
@@ -152,23 +152,23 @@ exact match:
 
 .. doctest::
 
-  >>> print registry.registered([IR1], IP1)
+  >>> print registry.registered([IRequire1], IProvide1)
   11
 
-  >>> print registry.registered([IR1], IP2)
+  >>> print registry.registered([IRequire1], IProvide2)
   12
 
-  >>> print registry.registered([IR1], IP2, 'bob')
+  >>> print registry.registered([IRequire1], IProvide2, 'bob')
   Bob's 12
 
 
-  >>> print registry.registered([IR2], IP1)
+  >>> print registry.registered([IRequire2], IProvide1)
   21
 
-  >>> print registry.registered([IR2], IP2)
+  >>> print registry.registered([IRequire2], IProvide2)
   None
 
-In the last example, None was returned because nothing was registered
+In the last example, ``None`` was returned because nothing was registered
 exactly for the given interfaces.
 
 lookup1
@@ -179,9 +179,9 @@ version of lookup that takes a single required interface:
 
 .. doctest::
 
-  >>> registry.lookup1(IR2, IP1, '')
+  >>> registry.lookup1(IRequire2, IProvide1, '')
   21
-  >>> registry.lookup1(IR2, IP1)
+  >>> registry.lookup1(IRequire2, IProvide1)
   21
 
 Actual Adaptation
@@ -202,19 +202,19 @@ factories:
    ...     zope.interface.implements(IR)
 
    >>> class Y:
-   ...     zope.interface.implements(IP1)
+   ...     zope.interface.implements(IProvide1)
    ...     def __init__(self, context):
    ...         self.context = context
 
-  >>> registry.register([IR], IP1, '', Y)
+  >>> registry.register([IR], IProvide1, '', Y)
 
 In this case, we registered a class as the factory. Now we can call
-`queryAdapter` to get the adapted object:
+``queryAdapter`` to get the adapted object:
 
 .. doctest::
 
   >>> x = X()
-  >>> y = registry.queryAdapter(x, IP1)
+  >>> y = registry.queryAdapter(x, IProvide1)
   >>> y.__class__.__name__
   'Y'
   >>> y.context is x
@@ -227,14 +227,14 @@ We can register and lookup by name too:
   >>> class Y2(Y):
   ...     pass
 
-  >>> registry.register([IR], IP1, 'bob', Y2)
-  >>> y = registry.queryAdapter(x, IP1, 'bob')
+  >>> registry.register([IR], IProvide1, 'bob', Y2)
+  >>> y = registry.queryAdapter(x, IProvide1, 'bob')
   >>> y.__class__.__name__
   'Y2'
   >>> y.context is x
   True
 
-When the adapter factory produces `None`, then this is treated as if no
+When the adapter factory produces ``None``, then this is treated as if no
 adapter has been found. This allows us to prevent adaptation (when desired)
 and let the adapter factory determine whether adaptation is possible based on
 the state of the object being adapted:
@@ -250,33 +250,33 @@ the state of the object being adapted:
   ...     zope.interface.implements(IR)
   ...     name = 'object'
 
-  >>> registry.register([IR], IP1, 'conditional', factory)
+  >>> registry.register([IR], IProvide1, 'conditional', factory)
   >>> obj = Object()
-  >>> registry.queryAdapter(obj, IP1, 'conditional')
+  >>> registry.queryAdapter(obj, IProvide1, 'conditional')
   'adapter'
   >>> obj.name = 'no object'
-  >>> registry.queryAdapter(obj, IP1, 'conditional') is None
+  >>> registry.queryAdapter(obj, IProvide1, 'conditional') is None
   True
-  >>> registry.queryAdapter(obj, IP1, 'conditional', 'default')
+  >>> registry.queryAdapter(obj, IProvide1, 'conditional', 'default')
   'default'
 
-An alternate method that provides the same function as `queryAdapter()` is
+An alternate method that provides the same function as ``queryAdapter()`` is
 `adapter_hook()`:
 
 .. doctest::
 
-  >>> y = registry.adapter_hook(IP1, x)
+  >>> y = registry.adapter_hook(IProvide1, x)
   >>> y.__class__.__name__
   'Y'
   >>> y.context is x
   True
-  >>> y = registry.adapter_hook(IP1, x, 'bob')
+  >>> y = registry.adapter_hook(IProvide1, x, 'bob')
   >>> y.__class__.__name__
   'Y2'
   >>> y.context is x
   True
 
-The `adapter_hook()` simply switches the order of the object and
+The ``adapter_hook()`` simply switches the order of the object and
 interface arguments.  It is used to hook into the interface call
 mechanism.
 
@@ -285,11 +285,11 @@ Default Adapters
 ----------------
 
 Sometimes, you want to provide an adapter that will adapt anything.
-For that, provide None as the required interface:
+For that, provide ``None`` as the required interface:
 
 .. doctest::
 
-  >>> registry.register([None], IP1, '', 1)
+  >>> registry.register([None], IProvide1, '', 1)
 
 then we can use that adapter for interfaces we don't have specific
 adapters for:
@@ -298,14 +298,14 @@ adapters for:
 
   >>> class IQ(zope.interface.Interface):
   ...     pass
-  >>> registry.lookup([IQ], IP1, '')
+  >>> registry.lookup([IQ], IProvide1, '')
   1
 
 Of course, specific adapters are still used when applicable:
 
 .. doctest::
 
-  >>> registry.lookup([IR2], IP1, '')
+  >>> registry.lookup([IRequire2], IProvide1, '')
   21
 
 
@@ -317,8 +317,8 @@ same as registering them for a class:
 
 .. doctest::
 
-  >>> registry.register([zope.interface.implementedBy(C2)], IP1, '', 'C21')
-  >>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
+  >>> registry.register([zope.interface.implementedBy(C2)], IProvide1, '', 'C21')
+  >>> registry.lookup([zope.interface.implementedBy(C2)], IProvide1, '')
   'C21'
 
 Dict adapters
@@ -337,15 +337,15 @@ bug. Let's make sure this works now:
 Unregistering
 -------------
 
-You can unregister by registering None, rather than an object:
+You can unregister by registering ``None``, rather than an object:
 
 .. doctest::
 
-  >>> registry.register([zope.interface.implementedBy(C2)], IP1, '', None)
-  >>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
+  >>> registry.register([zope.interface.implementedBy(C2)], IProvide1, '', None)
+  >>> registry.lookup([zope.interface.implementedBy(C2)], IProvide1, '')
   21
 
-Of course, this means that None can't be registered. This is an
+Of course, this means that ``None`` can't be registered. This is an
 exception to the statement, made earlier, that the registry doesn't
 care what gets registered.
 
@@ -356,24 +356,24 @@ You can adapt multiple specifications:
 
 .. doctest::
 
-  >>> registry.register([IR1, IQ], IP2, '', '1q2')
-  >>> registry.lookup([IR1, IQ], IP2, '')
+  >>> registry.register([IRequire1, IQ], IProvide2, '', '1q2')
+  >>> registry.lookup([IRequire1, IQ], IProvide2, '')
   '1q2'
-  >>> registry.lookup([IR2, IQ], IP1, '')
+  >>> registry.lookup([IRequire2, IQ], IProvide1, '')
   '1q2'
 
   >>> class IS(zope.interface.Interface):
   ...     pass
-  >>> registry.lookup([IR2, IS], IP1, '')
+  >>> registry.lookup([IRequire2, IS], IProvide1, '')
 
   >>> class IQ2(IQ):
   ...     pass
 
-  >>> registry.lookup([IR2, IQ2], IP1, '')
+  >>> registry.lookup([IRequire2, IQ2], IProvide1, '')
   '1q2'
 
-  >>> registry.register([IR1, IQ2], IP2, '', '1q22')
-  >>> registry.lookup([IR2, IQ2], IP1, '')
+  >>> registry.register([IRequire1, IQ2], IProvide2, '', '1q22')
+  >>> registry.lookup([IRequire2, IQ2], IProvide1, '')
   '1q22'
 
 Multi-adaptation
@@ -398,7 +398,7 @@ As with single adapters, we register a factory, which is often a class:
   ...         self.x, self.q = x, q
   >>> registry.register([IR, IQ], IM, '', M)
 
-And then we can call `queryMultiAdapter` to compute an adapter:
+And then we can call ``queryMultiAdapter`` to compute an adapter:
 
 .. doctest::
 
@@ -426,25 +426,25 @@ Default Adapters
 ----------------
 
 As with single adapters, you can define default adapters by specifying
-None for the *first* specification:
+``None`` for the *first* specification:
 
 .. doctest::
 
-  >>> registry.register([None, IQ], IP2, '', 'q2')
-  >>> registry.lookup([IS, IQ], IP2, '')
+  >>> registry.register([None, IQ], IProvide2, '', 'q2')
+  >>> registry.lookup([IS, IQ], IProvide2, '')
   'q2'
 
 Null Adapters
 =============
 
-You can also adapt no specification:
+You can also adapt **no** specification:
 
 .. doctest::
 
-  >>> registry.register([], IP2, '', 2)
-  >>> registry.lookup([], IP2, '')
+  >>> registry.register([], IProvide2, '', 2)
+  >>> registry.lookup([], IProvide2, '')
   2
-  >>> registry.lookup([], IP1, '')
+  >>> registry.lookup([], IProvide1, '')
   2
 
 Listing named adapters
@@ -455,7 +455,7 @@ adapters for given interfaces:
 
 .. doctest::
 
-  >>> adapters = list(registry.lookupAll([IR1], IP1))
+  >>> adapters = list(registry.lookupAll([IRequire1], IProvide1))
   >>> adapters.sort()
   >>> assert adapters == [(u'', 11), (u'bob', "Bob's 12")]
 
@@ -463,8 +463,8 @@ This works for multi-adapters too:
 
 .. doctest::
 
-  >>> registry.register([IR1, IQ2], IP2, 'bob', '1q2 for bob')
-  >>> adapters = list(registry.lookupAll([IR2, IQ2], IP1))
+  >>> registry.register([IRequire1, IQ2], IProvide2, 'bob', '1q2 for bob')
+  >>> adapters = list(registry.lookupAll([IRequire2, IQ2], IProvide1))
   >>> adapters.sort()
   >>> assert adapters == [(u'', '1q22'), (u'bob', '1q2 for bob')]
 
@@ -472,24 +472,24 @@ And even null adapters:
 
 .. doctest::
 
-  >>> registry.register([], IP2, 'bob', 3)
-  >>> adapters = list(registry.lookupAll([], IP1))
+  >>> registry.register([], IProvide2, 'bob', 3)
+  >>> adapters = list(registry.lookupAll([], IProvide1))
   >>> adapters.sort()
   >>> assert adapters == [(u'', 2), (u'bob', 3)]
 
 Subscriptions
 =============
 
-Normally, we want to look up an object that most-closely matches a
+Normally, we want to look up an object that most closely matches a
 specification.  Sometimes, we want to get all of the objects that
-match some specification.  We use subscriptions for this.  We
+match some specification.  We use *subscriptions* for this.  We
 subscribe objects against specifications and then later find all of
 the subscribed objects:
 
 .. doctest::
 
-  >>> registry.subscribe([IR1], IP2, 'sub12 1')
-  >>> registry.subscriptions([IR1], IP2)
+  >>> registry.subscribe([IRequire1], IProvide2, 'sub12 1')
+  >>> registry.subscriptions([IRequire1], IProvide2)
   ['sub12 1']
 
 Note that, unlike regular adapters, subscriptions are unnamed.
@@ -498,19 +498,19 @@ You can have multiple subscribers for the same specification:
 
 .. doctest::
 
-  >>> registry.subscribe([IR1], IP2, 'sub12 2')
-  >>> registry.subscriptions([IR1], IP2)
+  >>> registry.subscribe([IRequire1], IProvide2, 'sub12 2')
+  >>> registry.subscriptions([IRequire1], IProvide2)
   ['sub12 1', 'sub12 2']
 
 If subscribers are registered for the same required interfaces, they
 are returned in the order of definition.
 
-You can register subscribers for all specifications using None:
+You can register subscribers for all specifications using ``None``:
 
 .. doctest::
 
-  >>> registry.subscribe([None], IP1, 'sub_1')
-  >>> registry.subscriptions([IR2], IP1)
+  >>> registry.subscribe([None], IProvide1, 'sub_1')
+  >>> registry.subscriptions([IRequire2], IProvide1)
   ['sub_1', 'sub12 1', 'sub12 2']
 
 Note that the new subscriber is returned first.  Subscribers defined
@@ -521,71 +521,71 @@ Subscriptions may be combined over multiple compatible specifications:
 
 .. doctest::
 
-  >>> registry.subscriptions([IR2], IP1)
+  >>> registry.subscriptions([IRequire2], IProvide1)
   ['sub_1', 'sub12 1', 'sub12 2']
-  >>> registry.subscribe([IR1], IP1, 'sub11')
-  >>> registry.subscriptions([IR2], IP1)
+  >>> registry.subscribe([IRequire1], IProvide1, 'sub11')
+  >>> registry.subscriptions([IRequire2], IProvide1)
   ['sub_1', 'sub12 1', 'sub12 2', 'sub11']
-  >>> registry.subscribe([IR2], IP2, 'sub22')
-  >>> registry.subscriptions([IR2], IP1)
+  >>> registry.subscribe([IRequire2], IProvide2, 'sub22')
+  >>> registry.subscriptions([IRequire2], IProvide1)
   ['sub_1', 'sub12 1', 'sub12 2', 'sub11', 'sub22']
-  >>> registry.subscriptions([IR2], IP2)
+  >>> registry.subscriptions([IRequire2], IProvide2)
   ['sub12 1', 'sub12 2', 'sub22']
 
 Subscriptions can be on multiple specifications:
 
 .. doctest::
 
-  >>> registry.subscribe([IR1, IQ], IP2, 'sub1q2')
-  >>> registry.subscriptions([IR1, IQ], IP2)
+  >>> registry.subscribe([IRequire1, IQ], IProvide2, 'sub1q2')
+  >>> registry.subscriptions([IRequire1, IQ], IProvide2)
   ['sub1q2']
 
 As with single subscriptions and non-subscription adapters, you can
-specify None for the first required interface, to specify a default:
+specify ``None`` for the first required interface, to specify a default:
 
 .. doctest::
 
-  >>> registry.subscribe([None, IQ], IP2, 'sub_q2')
-  >>> registry.subscriptions([IS, IQ], IP2)
+  >>> registry.subscribe([None, IQ], IProvide2, 'sub_q2')
+  >>> registry.subscriptions([IS, IQ], IProvide2)
   ['sub_q2']
-  >>> registry.subscriptions([IR1, IQ], IP2)
+  >>> registry.subscriptions([IRequire1, IQ], IProvide2)
   ['sub_q2', 'sub1q2']
 
-You can have subscriptions that are indepenent of any specifications:
+You can have subscriptions that are independent of any specifications:
 
 .. doctest::
 
-  >>> list(registry.subscriptions([], IP1))
+  >>> list(registry.subscriptions([], IProvide1))
   []
 
-  >>> registry.subscribe([], IP2, 'sub2')
-  >>> registry.subscriptions([], IP1)
+  >>> registry.subscribe([], IProvide2, 'sub2')
+  >>> registry.subscriptions([], IProvide1)
   ['sub2']
-  >>> registry.subscribe([], IP1, 'sub1')
-  >>> registry.subscriptions([], IP1)
+  >>> registry.subscribe([], IProvide1, 'sub1')
+  >>> registry.subscriptions([], IProvide1)
   ['sub2', 'sub1']
-  >>> registry.subscriptions([], IP2)
+  >>> registry.subscriptions([], IProvide2)
   ['sub2']
 
 Unregistering subscribers
 -------------------------
 
 We can unregister subscribers.  When unregistering a subscriber, we
-can unregister a specific subscriber:
+can unregister a *specific* subscriber:
 
 .. doctest::
 
-  >>> registry.unsubscribe([IR1], IP1, 'sub11')
-  >>> registry.subscriptions([IR1], IP1)
+  >>> registry.unsubscribe([IRequire1], IProvide1, 'sub11')
+  >>> registry.subscriptions([IRequire1], IProvide1)
   ['sub_1', 'sub12 1', 'sub12 2']
 
-If we don't specify a value, then all subscribers matching the given
+If we don't specify a value, then *all* subscribers matching the given
 interfaces will be unsubscribed:
 
 .. doctest::
 
-  >>> registry.unsubscribe([IR1], IP2)
-  >>> registry.subscriptions([IR1], IP1)
+  >>> registry.unsubscribe([IRequire1], IProvide2)
+  >>> registry.subscriptions([IRequire1], IProvide1)
   ['sub_1']
 
 
@@ -611,7 +611,7 @@ example of multiple-object subscribers:
   >>> [(s.x is x and s.q is q) for s in subscribers]
   [True, True]
 
-adapter factory subcribers can't return None values:
+Adapter factory subscribers can't return ``None`` values:
 
 .. doctest::
 
@@ -627,16 +627,16 @@ Handlers
 --------
 
 A handler is a subscriber factory that doesn't produce any normal
-output.  It returns None.  A handler is unlike adapters in that it does
+output.  It returns ``None``.  A handler is unlike adapters in that it does
 all of its work when the factory is called.
 
-To register a handler, simply provide None as the provided interface:
+To register a handler, simply provide ``None`` as the provided interface:
 
 .. doctest::
 
   >>> def handler(event):
   ...     print 'handler', event
 
-  >>> registry.subscribe([IR1], None, handler)
-  >>> registry.subscriptions([IR1], None) == [handler]
+  >>> registry.subscribe([IRequire1], None, handler)
+  >>> registry.subscriptions([IRequire1], None) == [handler]
   True
diff --git a/docs/api.rst b/docs/api.rst
index 07979a1..c51624f 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -407,10 +407,10 @@ an instance:
    >>> implementedBy(Callable())
    <implementedBy __builtin__.?>
 
-Note that the name of the spec ends with a '?', because the `Callable`
-instance does not have a `__name__` attribute.
+Note that the name of the spec ends with a '?', because the ``Callable``
+instance does not have a ``__name__`` attribute.
 
-This also manages storage of implementation specifications
+This also manages storage of implementation specifications.
 
 
 :func:`zope.interface.declarations.classImplementsOnly`
@@ -687,9 +687,9 @@ subtract the unwanted interfaces. For example:
    >>> int(I2 in providedBy(ob))
    0
 
-removes I2 from the interfaces directly provided by ``ob``. The object,
+removes ``I2`` from the interfaces directly provided by ``ob``. The object,
 ``ob`` no longer directly provides ``I2``, although it might still
-provide ``I2`` if it's class implements ``I2``.
+provide ``I2`` if its class implements ``I2``.
 
 To add directly provided interfaces, use ``directlyProvidedBy`` and
 include additional interfaces.  For example:
@@ -700,7 +700,7 @@ include additional interfaces.  For example:
    0
    >>> directlyProvides(ob, directlyProvidedBy(ob), I2)
    
-adds ``I2`` to the interfaces directly provided by ob:
+adds ``I2`` to the interfaces directly provided by ``ob``:
 
 .. doctest::
 
@@ -778,7 +778,7 @@ Consider the following example:
 
 The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
 instances have been declared for instances of ``C``. Notice that the
-alsoProvides just extends the provided interfaces.
+``alsoProvides`` just extends the provided interfaces.
 
 
 :func:`zope.interface.declarations.noLongerProvides`
@@ -815,7 +815,7 @@ by the object:
    >>> I2.providedBy(c)
    True
 
-Remove I2 from c again:
+Remove ``I2`` from ``c`` again:
 
 .. doctest::
 
@@ -1057,5 +1057,5 @@ For example:
    'foo'
 
 When registering an adapter or utility component, the registry looks for the
-`__component_name__` attribute and uses it, if no name was explicitly
+``__component_name__`` attribute and uses it, if no name was explicitly
 provided.
diff --git a/docs/hacking.rst b/docs/hacking.rst
index c483caf..145a307 100644
--- a/docs/hacking.rst
+++ b/docs/hacking.rst
@@ -82,7 +82,7 @@ The ``dev`` command alias downloads and installs extra tools, like the
 
    OK
 
-If you have the :mod:`coverage` pacakge installed in the virtualenv,
+If you have the :mod:`coverage` package installed in the virtualenv,
 you can see how well the tests cover the code:
 
 .. code-block:: sh
diff --git a/docs/human.rst b/docs/human.rst
index f87c637..139c582 100644
--- a/docs/human.rst
+++ b/docs/human.rst
@@ -2,7 +2,7 @@
 Using the Adapter Registry
 ==========================
 
-This is a small demonstration of the ``zope.interface`` package including its
+This is a small demonstration of the :mod:`zope.interface` package including its
 adapter registry. It is intended to provide a concrete but narrow example on
 how to use interfaces and adapters outside of Zope 3.
 
@@ -36,8 +36,8 @@ provides the size of something:
   ...         'Return the size of an object.'
   ...
 
-Now we need to implement the file. It is essential that the object states
-that it implements the `IFile` interface. We also provide a default body
+Now we need to implement the file interface. It is essential that the object states
+that it implements the ``IFile`` interface. We also provide a default body
 value (just to make things simpler for this example):
 
 .. doctest::
@@ -48,19 +48,19 @@ value (just to make things simpler for this example):
   ...      body = 'foo bar'
   ...
 
-Next we implement an adapter that can provide the `ISize` interface given any
-object providing `IFile`. By convention we use `__used_for__` to specify the
+Next we implement an adapter that can provide the ``ISize`` interface given any
+object providing ``IFile``. By convention we use ``__used_for__`` to specify the
 interface that we expect the adapted object to provide, in our case
-`IFile`. However, this attribute is not used for anything. If you have
+``IFile``. However, this attribute is not used for anything. If you have
 multiple interfaces for which an adapter is used, just specify the interfaces
 via a tuple.
 
 Again by convention, the constructor of an adapter takes one argument, the
-context. The context in this case is an instance of `File` (providing `IFile`)
+context. The context in this case is an instance of ``File`` (providing ``IFile``)
 that is used to extract the size from. Also by convention the context is
-stored in an attribute named `context` on the adapter. The twisted community
-refers to the context as the `original` object. However, you may feel free to
-use a specific argument name, such as `file`:
+stored in an attribute named ``context`` on the adapter. The `twisted`_ community
+refers to the context as the ``original`` object. However, you may feel free to
+use a specific argument name, such as ``file``:
 
 .. doctest::
 
@@ -87,17 +87,17 @@ global registry; thus we have to instantiate one for our example manually:
 
 
 The registry keeps a map of what adapters implement based on another
-interface, the object already provides. Therefore, we next have to register an
-adapter that adapts from `IFile` to `ISize`. The first argument to
-the registry's `register()` method is a list of original interfaces.In our
-cause we have only one original interface, `IFile`. A list makes sense, since
+interface the object already provides. Therefore, we next have to register an
+adapter that adapts from ``IFile`` to ``ISize``. The first argument to
+the registry's ``register()`` method is a list of original interfaces.In our
+cause we have only one original interface, ``IFile``. A list makes sense, since
 the interface package has the concept of multi-adapters, which are adapters
 that require multiple objects to adapt to a new interface. In these
 situations, your adapter constructor will require an argument for each
 specified interface.
 
 The second argument is the interface the adapter provides, in our case
-`ISize`. The third argument is the name of the adapter. Since we do not care
+``ISize``. The third argument is the name of the adapter. Since we do not care
 about names, we simply leave it as an empty string. Names are commonly useful,
 if you have adapters for the same set of interfaces, but they are useful in
 different situations. The last argument is simply the adapter class:
@@ -113,9 +113,9 @@ You can now use the the registry to lookup the adapter:
   >>> registry.lookup1(IFile, ISize, '')
   <class 'FileSize'>
 
-Let's get a little bit more practical. Let's create a `File` instance and
+Let's get a little bit more practical. Let's create a ``File`` instance and
 create the adapter using a registry lookup. Then we see whether the adapter
-returns the correct size by calling `getSize()`:
+returns the correct size by calling ``getSize()``:
 
 .. doctest::
 
@@ -126,10 +126,10 @@ returns the correct size by calling `getSize()`:
 
 However, this is not very practical, since I have to manually pass in the
 arguments to the lookup method. There is some syntactic candy that will allow
-us to get an adapter instance by simply calling `ISize(file)`. To make use of
-this functionality, we need to add our registry to the adapter_hooks list,
+us to get an adapter instance by simply calling ``ISize(file)``. To make use of
+this functionality, we need to add our registry to the ``adapter_hooks`` list,
 which is a member of the adapters module. This list stores a collection of
-callables that are automatically invoked when IFoo(obj) is called; their
+callables that are automatically invoked when ``IFoo(obj)`` is called; their
 purpose is to locate adapters that implement an interface for a certain
 context instance.
 
@@ -137,8 +137,8 @@ You are required to implement your own adapter hook; this example covers one
 of the simplest hooks that use the registry, but you could implement one that
 used an adapter cache or persistent adapters, for instance. The helper hook is
 required to expect as first argument the desired output interface (for us
-`ISize`) and as the second argument the context of the adapter (here
-`file`). The function returns an adapter, i.e. a `FileSize` instance:
+``ISize``) and as the second argument the context of the adapter (here
+``file``). The function returns an adapter, i.e. a ``FileSize`` instance:
 
 .. doctest::
 
@@ -148,7 +148,7 @@ required to expect as first argument the desired output interface (for us
   ...     return adapter(object)
   ...
 
-We now just add the hook to an `adapter_hooks` list:
+We now just add the hook to an ``adapter_hooks`` list:
 
 .. doctest::
 
@@ -163,8 +163,8 @@ Once the hook is registered, you can use the desired syntax:
   >>> size.getSize()
   7
 
-Now we have to cleanup after ourselves, so that others after us have a clean
-`adapter_hooks` list:
+Now we have to clean up after ourselves, so that others after us have a clean
+``adapter_hooks`` list:
 
 .. doctest::
 
@@ -173,6 +173,8 @@ Now we have to cleanup after ourselves, so that others after us have a clean
 That's it. I have intentionally left out a discussion of named adapters and
 multi-adapters, since this text is intended as a practical and simple
 introduction to Zope 3 interfaces and adapters. You might want to read the
-`adapter.txt` in the `zope.interface` package for a more formal, referencial
+``adapter.txt`` in the ``zope.interface`` package for a more formal, referential
 and complete treatment of the package. Warning: People have reported that
-`adapter.txt` makes their brain feel soft!
+``adapter.txt`` makes their brain feel soft!
+
+.. _twisted: https://twistedmatrix.com/
diff --git a/docs/verify.rst b/docs/verify.rst
index 2481186..0ae7fdf 100644
--- a/docs/verify.rst
+++ b/docs/verify.rst
@@ -18,13 +18,13 @@ Verifying objects
 An object provides an interface if
 
 - either its class declares that it implements the interfaces, or the object
-  declares that it directly provides the interface
+  declares that it directly provides the interface;
 
-- the object defines all the methods required by the interface
+- the object defines all the methods required by the interface;
 
-- all the methods have the correct signature
+- all the methods have the correct signature;
 
-- the object defines all non-method attributes required by the interface
+- the object defines all non-method attributes required by the interface.
 
 This doctest currently covers only the latter item.
 
@@ -80,7 +80,7 @@ If either attribute is missing, verification will fail:
            The x attribute was not provided.
    <BLANKLINE>
 
-If an attribute is implemented as a property that raises an AttributeError
+If an attribute is implemented as a property that raises an ``AttributeError``
 when trying to get its value, the attribute is considered missing:
 
 .. doctest::
diff --git a/src/zope/interface/adapter.py b/src/zope/interface/adapter.py
index 64274b7..db2a49b 100644
--- a/src/zope/interface/adapter.py
+++ b/src/zope/interface/adapter.py
@@ -468,7 +468,7 @@ class AdapterLookupBase(object):
     # We could separate this by order and name, thus reducing the
     # number of provided interfaces to search at run time.  The tradeoff,
     # however, is that we have to store more information.  For example,
-    # is the same interface is provided for multiple names and if the
+    # if the same interface is provided for multiple names and if the
     # interface extends many interfaces, we'll have to keep track of
     # a fair bit of information for each name.  It's better to
     # be space efficient here and be time efficient in the cache