diff --git a/doc/configapi.txt b/doc/configapi.txt
index 18d5706..91bcbec 100644
--- a/doc/configapi.txt
+++ b/doc/configapi.txt
@@ -46,7 +46,7 @@ Here are some private attributes of a `Config()` object, for a
 comprehension of the internal merchanism:
 
 - `_cfgimpl_descr =` `option.OptionDescription()`,
-  e.g. the `optionapi#schema`
+  e.g. the :ref:`optdescr`
 
 - `_cfgimpl_values` contains the `option.Option()`'s values.
   Yes, the values of the options: remember that the values are stored **inside**
@@ -57,7 +57,7 @@ comprehension of the internal merchanism:
 ::
 
     {'int': 0, 'wantframework': False, 'objspace': 'std', 'bool': False,
-    'str': 'abc', 'gc': <config.Config object at 0xa33f8ec>, 'wantref': False}
+    'str': 'abc', 'wantref': False}
 
 We can see that values can also be config objects, it's the
 sub-namespaces that are stored in the values as `Config()` objects.
@@ -69,7 +69,7 @@ With this `config.Config()` configuration management entry point,
 it is possible to
 
 - `iter` on config, notice that there is an iteration order wich is
-  the order of the `optionapi#schema` specification entries,
+  the order of the :ref:`optdescr` specification entries,
 - compare two configs (equality),
 - export the whole config into a `dict` with `config.make_dict()`,
 
diff --git a/doc/getting-started.txt b/doc/getting-started.txt
index 2ada618..02530aa 100644
--- a/doc/getting-started.txt
+++ b/doc/getting-started.txt
@@ -16,8 +16,8 @@ What is Tiramisu ?
 
 Tiramisu is yet another configuration handler, wich aims at producing
 flexible and fast configuration options access. The main advantages are
-its access `glossary#rules` and the fact that the configuration 's
-consistency is preserved at any time, see `glossary#consistency`.
+its access rules and the fact that the configuration 's
+consistency is preserved at any time, see :doc:`consistency`.
 
 There are type and structures's validations for configuration options,
 and validations towards the whole configuration.
@@ -47,7 +47,7 @@ directory named ``tiramisu``.
 Understanding Tiramisu's architecture
 --------------------------------------
 
-The `glossary#schema` is loaded from an XML file, and the values of
+The `schema` is loaded from an XML file, and the values of
 the configuration options are recovered from a `.ini` like file.
 
 By now, all the in-depth informations about the configuration are stored
diff --git a/doc/optionapi.txt b/doc/optionapi.txt
index 029daba..6c5a190 100644
--- a/doc/optionapi.txt
+++ b/doc/optionapi.txt
@@ -13,6 +13,8 @@ value of the option. If this argument is not supplied the default value
 is assumed to be ``None``.
 
 
+.. _optdescr:
+
 The `OptionDescription` class
 -------------------------------
 
diff --git a/tiramisu/config.py b/tiramisu/config.py
index 47ee6dc..ddead27 100644
--- a/tiramisu/config.py
+++ b/tiramisu/config.py
@@ -36,6 +36,7 @@ class Config(object):
 
     def __init__(self, descr, parent=None, context=None):
         """ Configuration option management master class
+
         :param descr: describes the configuration schema
         :type descr: an instance of ``option.OptionDescription``
         :param parent: is None if the ``Config`` is root parent Config otherwise
@@ -226,7 +227,8 @@ class Config(object):
     def setoption(self, name, value, who=None):
         """effectively modifies the value of an Option()
         (typically called by the __setattr__)
-        :param who : an object that lives in `setting.owners`
+        
+        :param who: an object that lives in `setting.owners`
         """
         child = getattr(self._cfgimpl_descr, name)
         if type(child) != SymLinkOption:
@@ -258,6 +260,7 @@ class Config(object):
         do what I mean"-interface to option setting. Searches all paths
         starting from that config for matches of the optional arguments
         and sets the found option if the match is not ambiguous.
+        
         :param kwargs: dict of name strings to values.
         """
         all_paths = [p.split(".") for p in self.getpaths(allpaths=True)]
@@ -377,6 +380,7 @@ class Config(object):
         """iteration on groups objects only.
         All groups are returned if `group_type` is `None`, otherwise the groups
         can be filtered by categories (families, or whatever).
+        
         :param group_type: if defined, is an instance of `groups.GroupType`
                            or `groups.MasterGroupType` that lives in
                            `setting.groups`