diff --git a/py/doc/conftest.py b/py/doc/conftest.py
index ab853f161..9cba7977f 100644
--- a/py/doc/conftest.py
+++ b/py/doc/conftest.py
@@ -14,25 +14,27 @@ option = py.test.config.addoptions("documentation check options",
         )
 ) 
 
-_initialized = False
-def checkdocutils(path): 
-    global _initialized
+def checkdocutils():
     try:
         import docutils
     except ImportError:
         py.test.skip("docutils not importable")
-    if not _initialized:
-        from py.__.rest import directive
-        directive.register_linkrole('api', get_resolve_linkrole(path))
-        directive.register_linkrole('source', get_resolve_linkrole(path))
-        _initialized = True
+
+def initrestdirectives(path):
+    from py.__.rest import directive
+    dirpath = path.dirpath()
+    # XXX note that this gets called for every test, because the path is
+    # different every test...
+    directive.register_linkrole('api', get_resolve_linkrole(dirpath))
+    directive.register_linkrole('source', get_resolve_linkrole(dirpath))
 
 def restcheck(path):
     localpath = path
     if hasattr(path, 'localpath'):
         localpath = path.localpath
     _checkskip(localpath)
-    checkdocutils(localpath) 
+    checkdocutils() 
+    initrestdirectives(localpath)
     import docutils.utils
 
     try: 
@@ -262,6 +264,7 @@ def get_resolve_linkrole(checkpath=None):
             if not py.path.local(checkpath).join(ret[1]).check():
                 raise AssertionError(
                     '%s linkrole: %s points to non-existant path %s' % (
-                     name, ret[0], ret[1]))
+                     name, ret[0], py.path.local(checkpath).join(ret[1])))
         return ret
     return resolve_linkrole
+
diff --git a/py/doc/misc.txt b/py/doc/misc.txt
index 7f51f823b..2bf95bb3d 100644
--- a/py/doc/misc.txt
+++ b/py/doc/misc.txt
@@ -93,7 +93,8 @@ sources:
 Currently, the py lib offers two ways to interact with
 system executables. :api:`py.process.cmdexec()` invokes
 the shell in order to execute a string.  The other
-one, :api:`py.path.local.sysexec()` lets you directly execute a binary. 
+one, :api:`py.path.local`'s 'sysexec()' method lets you 
+directly execute a binary. 
 
 Both approaches will raise an exception in case of a return-
 code other than 0 and otherwise return the stdout-output 
@@ -217,3 +218,4 @@ are pure-Python reimplementations. These currently are:
    module)
 
 :api:`py.builtin.BaseException` is just ``Exception`` before Python 2.5.
+
diff --git a/py/doc/path.txt b/py/doc/path.txt
index a2454c1b9..7c4b2c6b0 100644
--- a/py/doc/path.txt
+++ b/py/doc/path.txt
@@ -209,10 +209,10 @@ to provide this choice (and getting rid
 of platform-dependencies as much as possible). 
 
 There is some experimental small approach 
-(:source:`py/path/gateway`) aiming at having
+(:source:`py/path/gateway/`) aiming at having
 a convenient Remote Path implementation
 and some considerations about future 
-works in the according :source:`py/path/gateway/todo.txt`
+works in the according :source:`py/path/gateway/TODO.txt`
 
 There are various hacks out there to have
 Memory-Filesystems and even path objects