Changeset 3176:e5b3bee49d07 in livinglogic.python.xist

Show
Ignore:
Timestamp:
01/24/08 17:46:48 (12 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

Convert all docstrings in xsc.py to ReST.

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • src/ll/xist/xsc.py

    r3169 r3176  
    1010 
    1111""" 
    12 This module contains all the central &xml; tree classes, the namespace classes, 
     12This module contains all the central XML tree classes, the namespace classes, 
    1313exception and warning classes and a few helper classes and functions. 
    1414""" 
     
    3434 
    3535 
    36 __docformat__ = "xist" 
     36__docformat__ = "reStructuredText" 
    3737 
    3838 
     
    5757def tonode(value): 
    5858    """ 
    59     <p>convert <arg>value</arg> to an &xist; <pyref class="Node"><class>Node</class></pyref>.</p> 
    60  
    61     <p>If <arg>value</arg> is a tuple or list, it will be (recursively) converted 
    62     to a <pyref class="Frag"><class>Frag</class></pyref>. Integers, strings, etc. 
    63     will be converted to a <pyref class="Text"><class>Text</class></pyref>. 
    64     If <arg>value</arg> is a <pyref class="Node"><class>Node</class></pyref> already, 
    65     it will be returned unchanged. In the case of <lit>None</lit> the &xist; Null 
    66     (<class>ll.xist.xsc.Null</class>) will be returned. If <arg>value</arg> is 
    67     iterable, a <class>Frag</class> will be generated from the items. 
    68     Anything else will raise an <class>IllegalObjectError</class> exception.</p> 
     59    convert :var:`value` to an XIST :class:`Node`. 
     60 
     61    If :var:`value` is a tuple or list, it will be (recursively) converted to a 
     62    :class:`Frag`. Integers, strings, etc. will be converted to a :class:`Text`. 
     63    If :var:`value` is a :class:`Node` already, it will be returned unchanged. 
     64    In the case of :const:`None` the XIST Null (:data:`ll.xist.xsc.Null`) will be 
     65    returned. If :var:`value` is iterable, a :class:`Frag` will be generated 
     66    from the items. Anything else will raise an :exc:`IllegalObjectError` 
     67    exception. 
    6968    """ 
    7069    if isinstance(value, Node): 
     
    9493def add(*args, **kwargs): 
    9594    """ 
    96     <func>add</func> appends items in <arg>args</arg> and sets attributes 
    97     in <arg>kwargs</arg> in the currenly active node in the <lit>with</lit> stack. 
     95    :func:`add` appends items in :var:`args` and sets attributes in 
     96    :var:`kwargs` in the currenly active node in the ``with`` stack. 
    9897    """ 
    9998    getstack()[-1](*args, **kwargs) 
     
    114113class WalkFilter(object): 
    115114    """ 
    116     A <class>WalkFilter</class> can be passed to the 
    117     <pyref class="Node" method="walk"><meth>walk</meth></pyref> method of 
    118     nodes to specify how to traverse the tree and which nodes to output. 
     115    A :class:`WalkFilter` can be passed to the :meth:`walk` method of nodes to 
     116    specify how to traverse the tree and which nodes to output. 
    119117    """ 
    120118    @misc.notimplemented 
     
    222220class Context(object): 
    223221    """ 
    224     <p>This is an empty class, that can be used by the 
    225     <pyref class="Node" method="convert"><meth>convert</meth></pyref> 
    226     method to hold element or namespace specific data during the convert call. 
    227     The method <pyref class="Converter" method="__getitem__"><meth>Converter.__getitem__</meth></pyref> 
    228     will return a unique instance of this class.</p> 
     222    This is an empty class, that can be used by the :meth:`convert` method to 
     223    hold element or namespace specific data during the convert call. The method 
     224    :meth:`Converter.__getitem__` will return a unique instance of this class. 
    229225    """ 
    230226    __fullname__ = "Context" 
     
    237233class Error(Exception): 
    238234    """ 
    239     Base class for all &xist; exceptions 
     235    Base class for all XIST exceptions 
    240236    """ 
    241237    pass 
     
    252248class IllegalAttrValueWarning(Warning): 
    253249    """ 
    254     Warning that is issued when an attribute has an illegal value when parsing or 
    255     publishing. 
     250    Warning that is issued when an attribute has an illegal value when parsing 
     251    or publishing. 
    256252    """ 
    257253 
     
    266262class RequiredAttrMissingWarning(Warning): 
    267263    """ 
    268     Warning that is issued when a required attribute is missing during parsing or publishing. 
     264    Warning that is issued when a required attribute is missing during parsing 
     265    or publishing. 
    269266    """ 
    270267 
     
    275272    def __str__(self): 
    276273        return "Required attribute%s %s missing in %s" % (("s" if len(self.reqattrs)>1 else ""), ", ".join(repr(attr) for attr in self.reqattrs), self.attrs._str(fullname=True, xml=False, decorate=False)) 
    277  
    278  
    279 class IllegalDTDChildWarning(Warning): 
    280     """ 
    281     Warning that is issued when the <pyref module="ll.xist.parsers" class="HTMLParser"><class>HTMLParser</class></pyref> 
    282     detects an element that is not allowed inside its parent element according to the &html; &dtd; 
    283     """ 
    284  
    285     def __init__(self, childname, parentname): 
    286         self.childname = childname 
    287         self.parentname = parentname 
    288  
    289     def __str__(self): 
    290         return "Element %s not allowed as a child of element %s" % (self.childname, self.parentname) 
    291  
    292  
    293 class IllegalCloseTagWarning(Warning): 
    294     """ 
    295     Warning that is issued when the <pyref module="ll.xist.parsers" class="HTMLParser"><class>HTMLParser</class></pyref> 
    296     finds an end tag that has no corresponding start tag. 
    297     """ 
    298  
    299     def __init__(self, name): 
    300         self.name = name 
    301  
    302     def __str__(self): 
    303         return "Element %s has never been opened" % (self.name,) 
    304  
    305  
    306 class PrefixNeededError(Error, ValueError): 
    307     """ 
    308     Exception that is raised when something requires a prefix on publishing. 
    309     """ 
    310     def __init__(self, xmlns): 
    311         self.xmlns = xmlns 
    312  
    313     def __str__(self): 
    314         return "namespace %s needs a prefix" % nsclark(self.xmlns) 
    315274 
    316275 
     
    419378class AmbiguousNodeError(Error, LookupError): 
    420379    """ 
    421     exception that is raised, when an node class is ambiguous (most commonly for processing instructions or entities) 
     380    Exception that is raised, when an node class is ambiguous (most commonly 
     381    for processing instructions or entities) 
    422382    """ 
    423383 
     
    458418    """ 
    459419    Exception that is raised, when an element has an illegal nesting 
    460     (e.g. <lit>&lt;a&gt;&lt;b&gt;&lt;/a&gt;&lt;/b&gt;</lit>) 
     420    (e.g. ``&lt;a&gt;&lt;b&gt;&lt;/a&gt;&lt;/b&gt;``) 
    461421    """ 
    462422 
     
    498458class IllegalObjectError(TypeError): 
    499459    """ 
    500     Exception that is raised when an &xist; constructor gets passed an unconvertable object. 
     460    Exception that is raised when an XIST constructor gets passed an 
     461    unconvertable object. 
    501462    """ 
    502463 
     
    508469 
    509470 
    510 class MalformedCharRefWarning(Warning): 
    511     """ 
    512     Exception that is raised when a character reference is malformed (e.g. <lit>&amp;#foo;</lit>) 
     471class AmbiguousNodeError(Warning): 
     472    """ 
     473    Exception that is raised when a character reference is malformed 
     474    (e.g. ``&amp;#foo;``) 
    513475    """ 
    514476 
     
    523485    """ 
    524486    Warning that is issued when there is an illegal comment, i.e. one 
    525     containing <lit>--</lit> or ending in <lit>-</lit>. 
    526     (This can only happen, when the comment is instantiated by the 
    527     program, not when parsed from an &xml; file.) 
     487    containing ``--`` or ending in ``-``. (This can only happen, when the 
     488    comment is instantiated by the program, not when parsed from an XML file.) 
    528489    """ 
    529490 
     
    537498class IllegalProcInstFormatError(Error): 
    538499    """ 
    539     Exception that is raised, when there is an illegal processing instruction, i.e. one containing <lit>?&gt;</lit>. 
    540     (This can only happen, when the processing instruction is instantiated by the 
    541     program, not when parsed from an &xml; file.) 
     500    Exception that is raised, when there is an illegal processing instruction, 
     501    i.e. one containing ``?>``. (This can only happen, when the processing 
     502    instruction is instantiated by the program, not when parsed from an XML 
     503    file.) 
    542504    """ 
    543505 
     
    551513class IllegalXMLDeclFormatError(Error): 
    552514    """ 
    553     Exception that is raised, when there is an illegal XML declaration, 
    554     i.e. there something wrong in <lit>&lt;?xml ...?&gt;</lit>. 
    555     (This can only happen, when the processing instruction is instantiated by the 
    556     program, not when parsed from an &xml; file.) 
     515    Exception that is raised, when there is an illegal XML declaration, i.e. 
     516    there something wrong in ``<?xml ...?>``. (This can only happen, when the 
     517    processing instruction is instantiated by the program, not when parsed 
     518    from an XML file.) 
    557519    """ 
    558520 
     
    579541class IllegalProcInstParseWarning(IllegalProcInstError, ParseWarning): 
    580542    """ 
    581     Warning about an illegal processing instruction that is issued during parsing. 
     543    Warning about an illegal processing instruction that is issued during 
     544    parsing. 
    582545    """ 
    583546warnings.filterwarnings("error", category=IllegalProcInstParseWarning) 
     
    586549class AmbiguousProcInstParseWarning(AmbiguousProcInstError, ParseWarning): 
    587550    """ 
    588     Warning about an ambigous processing instruction that is issued during parsing. 
     551    Warning about an ambigous processing instruction that is issued during 
     552    parsing. 
    589553    """ 
    590554warnings.filterwarnings("error", category=AmbiguousProcInstParseWarning) 
     
    614578class AmbiguousCharRefParseWarning(AmbiguousCharRefError, ParseWarning): 
    615579    """ 
    616     Warning about an ambigous character references that is issued during parsing. 
     580    Warning about an ambigous character references that is issued during 
     581    parsing. 
    617582    """ 
    618583warnings.filterwarnings("error", category=AmbiguousCharRefParseWarning) 
     
    628593class NodeOutsideContextError(Error): 
    629594    """ 
    630     Error that is raised, when a convert method can't find required context info. 
     595    Error that is raised, when a convert method can't find required context 
     596    info. 
    631597    """ 
    632598 
     
    690656class Node(object): 
    691657    """ 
    692     base class for nodes in the document tree. Derived classes must 
    693     overwrite <pyref method="convert"><meth>convert</meth></pyref> 
    694     and may overwrite <pyref method="publish"><meth>publish</meth></pyref>. 
     658    base class for nodes in the document tree. Derived classes may 
     659    overwrite :meth:`convert` or :meth:`publish`. 
    695660    """ 
    696661    __metaclass__ = _Node_Meta 
    697662 
    698     # location of this node in the XML file (will be hidden in derived classes, but is 
    699     # specified here, so that no special tests are required. In derived classes 
    700     # this will be set by the parser) 
     663    # location of this node in the XML file (will be hidden in derived classes, 
     664    # but is specified here, so that no special tests are required. In derived 
     665    # classes this will be set by the parser) 
    701666    startloc = None 
    702667    endloc = None 
    703668 
    704669    # Subclasses relevant for parsing (i.e. Element, ProcInst, Entity and CharRef) 
    705     # have an additional class attribute named register. This attribute may have three values: 
    706     # False: Don't register for parsing. 
    707     # True:  Use for parsing. 
    708     # If register is not set it defaults to True 
     670    # have an additional class attribute named register. This attribute may have 
     671    # three values: 
     672    # :const:`False`: Don't register for parsing. 
     673    # :const:`True`:  Use for parsing. 
     674    # If register is not set it defaults to :const:`True` 
    709675 
    710676    Context = Context 
     
    765731    def clone(self): 
    766732        """ 
    767         return a clone of <self/>. Compared to <pyref method="deepcopy"><meth>deepcopy</meth></pyref> <meth>clone</meth> 
    768         will create multiple instances of objects that can be found in the tree more than once. <meth>clone</meth> can't 
    769         clone trees that contain cycles. 
     733        return a clone of ``self``. Compared to :meth:`deepcopy` :meth:`clone` 
     734        will create multiple instances of objects that can be found in the tree 
     735        more than once. :meth:`clone` can't clone trees that contain cycles. 
    770736        """ 
    771737        return self 
     
    773739    def copy(self): 
    774740        """ 
    775         Return a shallow copy of <self/>. 
     741        Return a shallow copy of ``self``. 
    776742        """ 
    777743        return self.__copy__() 
     
    782748    def deepcopy(self): 
    783749        """ 
    784         Return a deep copy of <self/>. 
     750        Return a deep copy of ``self``. 
    785751        """ 
    786752        return self.__deepcopy__() 
     
    792758    def present(self, presenter): 
    793759        """ 
    794         <p><meth>present</meth> is used as a central dispatch method for 
    795         the <pyref module="ll.xist.presenters">presenter classes</pyref>. Normally 
    796         it is not called by the user, but internally by the presenter. The user 
    797         should call <pyref method="repr"><meth>repr</meth></pyref> 
    798         instead.</p> 
    799         """ 
    800         # Subclasses of Node implement this method by calling the appropriate present* method in the publisher (i.e. double dispatch) 
     760        :meth:`present` is used as a central dispatch method for the 
     761        presenter classes. Normally it is not called by the user, but internally 
     762        by the presenter. The user should use the appropriate presenter class 
     763        directly. 
     764        """ 
     765        # Subclasses of ``Node`` implement this method by calling the appropriate 
     766        # ``present*`` method in the publisher (i.e. double dispatch) 
    801767 
    802768    def conv(self, converter=None, root=None, mode=None, stage=None, target=None, lang=None, function=None, makeaction=None, makeproject=None): 
    803769        """ 
    804         <p>Convenience method for calling <pyref method="convert"><meth>convert</meth></pyref>.</p> 
    805         <p><meth>conv</meth> will automatically set <lit><arg>converter</arg>.node</lit> to <self/> to remember the 
    806         <z>document root node</z> for which <meth>conv</meth> has been called, this means that you should not call 
    807         <meth>conv</meth> in any of the recursive calls, as you would loose this information. Call 
    808         <pyref method="convert"><meth>convert</meth></pyref> directly instead.</p> 
     770        Convenience method for calling :meth:`convert`. 
     771 
     772        :meth:`conv` will automatically set ``:var:`converter`.node`` to ``self`` 
     773        to remember the "document root node" for which :meth:`conv` has been 
     774        called, this means that you should not call :meth:`conv` in any of the 
     775        recursive calls, as you would loose this information. Call :meth:`convert` 
     776        directly instead. 
    809777        """ 
    810778        if converter is None: 
     
    820788    def convert(self, converter): 
    821789        """ 
    822         <p>implementation of the conversion method. When you define your own 
    823         element classes you have to overwrite this method and implement the desired 
    824         conversion.</p> 
    825  
    826         <p>This method must return an instance of <class>Node</class>. 
    827         It may <em>not</em> change <self/>.</p> 
    828         """ 
    829         pass 
     790        implementation of the conversion method. When you define your own element 
     791        classes you have to overwrite this method and implement the desired 
     792        conversion. 
     793 
     794        This method must return an instance of :class:`Node`. It may *not* change 
     795        ``self``. 
     796        """ 
    830797 
    831798    @misc.notimplemented 
    832799    def __unicode__(self): 
    833800        """ 
    834         <p>Return the character content of <self/> as a unicode string. 
    835         This means that comments and processing instructions will be filtered out. 
    836         For elements you'll get the element content.</p> 
    837  
    838         <p><meth>__unicode__</meth> can be used everywhere where 
    839         a plain string representation of the node is required.</p> 
     801        Return the character content of ``self`` as a unicode string. This means 
     802        that comments and processing instructions will be filtered out. For 
     803        elements you'll get the element content. 
     804 
     805        :meth:`__unicode__` can be used everywhere where a plain string 
     806        representation of the node is required. 
    840807        """ 
    841808        pass 
     
    843810    def __str__(self): 
    844811        """ 
    845         Return the character content of <self/> as a string (if possible, i.e. 
     812        Return the character content of ``self`` as a string (if possible, i.e. 
    846813        there are no characters that are unencodable in the default encoding). 
    847814        """ 
     
    850817    def __int__(self): 
    851818        """ 
    852         Convert the character content of <self/> to an <class>int</class>. 
     819        Convert the character content of ``self`` to an :class:`int`. 
    853820        """ 
    854821        return int(unicode(self)) 
     
    856823    def __long__(self): 
    857824        """ 
    858         Convert the character content of <self/> to an <class>long</class>. 
     825        Convert the character content of ``self`` to an :class:`long`. 
    859826        """ 
    860827        return long(unicode(self)) 
     
    862829    def asFloat(self, decimal=".", ignore=""): 
    863830        """ 
    864         <p>Convert the character content of <self/> to an <class>float</class>. 
    865         <arg>decimal</arg> specifies which decimal separator is used in the value 
    866         (e.g. <lit>"."</lit> (the default) or <lit>","</lit>). 
    867         <arg>ignore</arg> specifies which character will be ignored.</p> 
     831        Convert the character content of ``self`` to an :class:`float`. 
     832        :var:`decimal` specifies which decimal separator is used in the value 
     833        (e.g. ``"."`` (the default) or ``","``). :var:`ignore` specifies which 
     834        characters will be ignored.</p> 
    868835        """ 
    869836        s = unicode(self) 
     
    876843    def __float__(self): 
    877844        """ 
    878         Convert the character content of <self/> to an <class>float</class>. 
     845        Convert the character content of ``self`` to an :class:`float`. 
    879846        """ 
    880847        return self.asFloat() 
     
    882849    def __complex__(self): 
    883850        """ 
    884         Convert the character content of <self/> to an <class>complex</class>. 
     851        Convert the character content of ``self`` to an :class:`complex`. 
    885852        """ 
    886853        return complex(unicode(self)) 
     
    888855    def parsed(self, parser, start=None): 
    889856        """ 
    890         <p>This method will be called by the parser <arg>parser</arg> once after 
    891         <self/> is created by the parser and must return the node that is to be 
    892         put into the tree (in most cases this is <self/>, it's used e.g. by 
    893         <pyref class="URLAttr"><class>URLAttr</class></pyref> to incorporate 
    894         the base <pyref module="ll.url" class="URL"><class>URL</class></pyref> 
    895         into the attribute.</p> 
    896  
    897         <p>For elements <func>parsed</func> will be called twice: 
    898         Once at the beginning (i.e. before the content is parsed) with 
    899         <lit><arg>start</arg>==True</lit> and once at the end after parsing of 
    900         the content is finished <lit><arg>start</arg>==False</lit>. For the 
    901         second call the return value will be ignored.</p> 
     857        This method will be called by the parser :var:`parser` once after 
     858        ``self`` is created by the parser and must return the node that is to be 
     859        put into the tree (in most cases this is ``self``, it's used e.g. by 
     860        :class:`URLAttr` to incorporate the base URL into the attribute. 
     861 
     862        For elements :func:`parsed` will be called twice: Once at the beginning 
     863        (i.e. before the content is parsed) with :var:`start` being :const:`True` 
     864        and once at the end after parsing of the content is finished with 
     865        ``:var:`start` being :const:`False`. For the second call the return value 
     866        will be ignored. 
    902867        """ 
    903868        return self 
     
    905870    def checkvalid(self): 
    906871        """ 
    907         <p>This method will be called when parsing or publishing to check 
    908         whether <self/> is valid.</p> 
    909  
    910         <p>If <self/> is found to be invalid a warning should be issued through 
    911         the <pyref module="warnings">Python warning framework</pyref>.</p> 
     872        This method will be called when parsing or publishing to check whether 
     873        ``self`` is valid. 
     874 
     875        If ``self`` is found to be invalid a warning should be issued through 
     876        the Python warning framework. 
    912877        """ 
    913878 
     
    915880    def publish(self, publisher): 
    916881        """ 
    917         <p>Generate unicode strings for the node. <arg>publisher</arg> must be an instance of 
    918         <pyref module="ll.xist.publishers" class="Publisher"><class>ll.xist.publishers.Publisher</class></pyref>.</p> 
    919  
    920         <p>The encoding and xhtml specification are taken from the <arg>publisher</arg>.</p> 
     882        Generate unicode strings for the node. :var:`publisher` must be an 
     883        instance of :class:`ll.xist.publishers.Publisher`. 
     884 
     885        The encoding and xhtml specification are taken from the :var:`publisher`. 
    921886        """ 
    922887 
    923888    def iterbytes(self, base=None, publisher=None, **publishargs): 
    924889        """ 
    925         <p>A generator that will produce this node as a serialized byte string.</p> 
    926  
    927         <p>For the possible parameters see the 
    928         <pyref module="ll.xist.publishers" class="Publisher"><class>ll.xist.publishers.Publisher</class></pyref> 
    929         constructor.</p> 
     890        A generator that will produce this node as a serialized byte string. 
     891 
     892        For the possible parameters see the :class:`ll.xist.publishers.Publisher` 
     893        constructor. 
    930894        """ 
    931895        if publisher is None: 
     
    936900    def bytes(self, base=None, publisher=None, **publishargs): 
    937901        """ 
    938         <p>Return this node as a serialized byte string.</p> 
    939  
    940         <p>For the possible parameters see the 
    941         <pyref module="ll.xist.publishers" class="Publisher"><class>ll.xist.publishers.Publisher</class></pyref> 
    942         constructor.</p> 
     902        Return ``self`` as a serialized byte string. 
     903 
     904        For the possible parameters see the :class:`ll.xist.publishers.Publisher` 
     905        constructor. 
    943906        """ 
    944907        return "".join(self.iterbytes(base, publisher, **publishargs)) 
     
    946909    def iterstring(self, base=None, publisher=None, **publishargs): 
    947910        """ 
    948         <p>A generator that will produce this node as a serialized byte string.</p> 
    949  
    950         <p>For the possible parameters see the 
    951         <pyref module="ll.xist.publishers" class="Publisher"><class>ll.xist.publishers.Publisher</class></pyref> 
    952         constructor.</p> 
     911        A generator that will produce a serialized byte string of ``self``. 
     912 
     913        For the possible parameters see the :class:`ll.xist.publishers.Publisher` 
     914        constructor. 
    953915        """ 
    954916        if publisher is None: 
     
    965927    def string(self, base=None, publisher=None, **publishargs): 
    966928        """ 
    967         <p>Return this node as a serialized unicode string.</p> 
    968  
    969         <p>For the possible parameters see the 
    970         <pyref module="ll.xist.publishers" class="Publisher"><class>ll.xist.publishers.Publisher</class></pyref> 
    971         constructor.</p> 
     929        Return a serialized unicode string for ``self``. 
     930 
     931        For the possible parameters see the :class:`ll.xist.publishers.Publisher` 
     932        constructor. 
    972933        """ 
    973934        if publisher is None: 
     
    979940    def write(self, stream, *args, **publishargs): 
    980941        """ 
    981         <p>Write <self/> to the file-like object <arg>stream</arg> (which must 
    982         provide a <meth>write</meth> method).</p> 
    983  
    984         <p>For the rest of the parameters see the 
    985         <pyref module="ll.xist.publishers" class="Publisher"><class>ll.xist.publishers.Publisher</class></pyref> 
    986         constructor.</p> 
     942        Write ``self`` to the file-like object :var:`stream` (which must provide 
     943        a :meth:`write` method). 
     944 
     945        For the rest of the parameters see the :class:`ll.xist.publishers.Publisher` 
     946        constructor. 
    987947        """ 
    988948        for part in self.bytes(*args, **publishargs): 
     
    991951    def _walk(self, walkfilter, path): 
    992952        """ 
    993         <p>Internal helper for <pyref method="walk"><meth>walk</meth></pyref>.</p> 
     953        Internal helper for :meth:`walk`. 
    994954        """ 
    995955        for option in walkfilter.filterpath(path): 
     
    999959    def walk(self, walkfilter=(True, entercontent)): 
    1000960        """ 
    1001         <p>Return an iterator for traversing the tree rooted at <self/>.</p> 
    1002  
    1003         <p><arg>walkfilter</arg> is used for specifying whether or not a node 
    1004         should be yielded and when the children of this node should be traversed. 
    1005         If <arg>walkfilter</arg> is callable, it will be called for each node 
    1006         visited during the traversal. A path (i.e. a list of all nodes from the 
    1007         root to the current node) will be passed to the filter on each call and 
    1008         the filter must return a sequence of <z>node handling options</z>. 
    1009         If <arg>walkfilter</arg> is not callable, it must be a sequence of node 
    1010         handling options that will be used for all visited nodes.</p> 
    1011  
    1012         <p>Entries in this returned sequence can be the following:</p> 
    1013  
    1014         <dl> 
    1015         <dt><lit>True</lit></dt><dd>This tells <meth>walk</meth> to 
    1016         yield this node from the iterator.</dd> 
    1017         <dt><lit>False</lit></dt><dd>Don't yield this node from the iterator.</dd> 
    1018         <dt><lit>enterattrs</lit></dt><dd>This is a global constant in 
    1019         <mod>ll.xist.xsc</mod> and tells <meth>walk</meth> to traverse 
    1020         the attributes of this node (if it's an 
    1021         <pyref class="Element"><class>Element</class></pyref>, otherwise this 
    1022         option will be ignored).</dd> 
    1023         <dt><lit>entercontent</lit></dt><dd>This is a global constant in 
    1024         <mod>ll.xist.xsc</mod> and tells <meth>walk</meth> to traverse 
    1025         the child nodes of this node (if it's an 
    1026         <pyref class="Element"><class>Element</class></pyref>, otherwise this 
    1027         option will be ignored).</dd> 
    1028         </dl> 
    1029  
    1030         <p>These options will be executed in the order they are specified in the 
     961        Return an iterator for traversing the tree rooted at ``self``. 
     962 
     963        :var:`walkfilter` is used for specifying whether or not a node should be 
     964        yielded and when the children of this node should be traversed. If 
     965        :var:`walkfilter` is callable, it will be called for each node visited 
     966        during the traversal. A path (i.e. a list of all nodes from the root to 
     967        the current node) will be passed to the filter on each call and the 
     968        filter must return a sequence of "node handling options". If 
     969        :var:`walkfilter` is not callable, it must be a sequence of node 
     970        handling options that will be used for all visited nodes. 
     971 
     972        Entries in this returned sequence can be the following: 
     973 
     974        :const:`True` 
     975            This tells :meth:`walk` to yield this node from the iterator. 
     976 
     977        :const:`False` 
     978            Don't yield this node from the iterator. 
     979 
     980        :const:`enterattrs` 
     981            This is a global constant in :mod:`ll.xist.xsc` and tells :meth:`walk` 
     982            to traverse the attributes of this node (if it's an :class:`Element`, 
     983            otherwise this option will be ignored). 
     984 
     985        :const:`entercontent` 
     986            This is a global constant in :mod:`ll.xist.xsc` and tells :meth:`walk` 
     987            to traverse the child nodes of this node (if it's an :class:`Element`, 
     988            otherwise this option will be ignored). 
     989 
     990        These options will be executed in the order they are specified in the 
    1031991        sequence, so to get a top down traversal of a tree (without entering 
    1032         attributes), the following call can be made:</p> 
    1033  
    1034         <prog> 
    1035         <rep>node</rep>.walk((True, xsc.entercontent)) 
    1036         </prog> 
    1037  
    1038         <p>For a bottom up traversal the following call can be made:</p> 
    1039  
    1040         <prog> 
    1041         <rep>node</rep>.walk((xsc.entercontent, True)) 
    1042         </prog> 
    1043  
    1044         <p>Each item produced by the iterator is a path list. 
    1045         <meth>walk</meth> reuses this list, so you can't rely on the value 
    1046         of the list being the same across calls to <meth>next</meth>.</p> 
     992        attributes), ``(True, xsc.entercontent)`` can be used. For a bottom up 
     993        traversal ``(xsc.entercontent, True)`` can be used. 
     994 
     995        Each item produced by the iterator is a path list. :meth:`walk` reuses 
     996        this list, so you can't rely on the value of the list being the same 
     997        across calls to :meth:`next`. 
    1047998        """ 
    1048999        return self._walk(makewalkfilter(walkfilter), [self]) 
     
    10501001    def walknode(self, walkfilter=(True, entercontent)): 
    10511002        """ 
    1052         Return an iterator for traversing the tree. <arg>filter</arg> works the 
    1053         same as the <arg>walkfilter</arg> argument for 
    1054         <pyref method="walk"><meth>walk</meth></pyref>. 
    1055         The items produced by the iterator are the nodes themselves. 
     1003        Return an iterator for traversing the tree. :var:`filter` works the same 
     1004        as the :var:`walkfilter` argument for :meth:`walk`. The items produced 
     1005        by the iterator are the nodes themselves. 
    10561006        """ 
    10571007        walkfilter = makewalkfilter(walkfilter) 
     
    10631013    def walkpath(self, walkfilter=(True, entercontent)): 
    10641014        """ 
    1065         Return an iterator for traversing the tree. <arg>walkfilter</arg> works 
    1066         the same as the <arg>walkfilter</arg> argument for 
    1067         <pyref method="walk"><meth>walk</meth></pyref>. The items produced by 
    1068         the iterator are copies of the path. 
     1015        Return an iterator for traversing the tree. :var:`walkfilter` works 
     1016        the same as the :var:`walkfilter` argument for :meth:`walk`. The items 
     1017        produced by the iterator are copies of the path. 
    10691018        """ 
    10701019        walkfilter = makewalkfilter(walkfilter) 
     
    10761025    def compact(self): 
    10771026        """ 
    1078         Return a version of <self/>, where textnodes or character references that 
    1079         contain only linefeeds are removed, i.e. potentially needless whitespace 
    1080         is removed. 
     1027        Return a version of ``self``, where textnodes or character references 
     1028        that contain only linefeeds are removed, i.e. potentially needless 
     1029        whitespace is removed. 
    10811030        """ 
    10821031        return self 
     
    10841033    def _decoratenode(self, node): 
    10851034        """ 
    1086         Decorate the <pyref class="Node"><class>Node</class></pyref> 
    1087         <arg>node</arg> with the same location information as <self/>. 
     1035        Decorate the :class:`Node` :var:`node` with the same location information 
     1036        as ``self``. 
    10881037        """ 
    10891038 
     
    10941043    def mapped(self, function, converter=None, **converterargs): 
    10951044        """ 
    1096         <p>Return the node mapped through the function <arg>function</arg>. This 
    1097         call works recursively (for <pyref class="Frag"><class>Frag</class></pyref> 
    1098         and <pyref class="Element"><class>Element</class></pyref>).</p> 
    1099  
    1100         <p>When you want an unmodified node you simply can return <self/>. 
    1101         <meth>mapped</meth> will make a copy of it and fill the content 
    1102         recursively. Note that element attributes will not be mapped. When you 
    1103         return a different node from <func>function</func> this node will 
    1104         be incorporated into the result as-is. 
     1045        Return the node mapped through the function :var:`function`. This call 
     1046        works recursively (for :class:`Frag` and :class:`Element`). 
     1047 
     1048        When you want an unmodified node you simply can return ``self``. 
     1049        :meth:`mapped` will make a copy of it and fill the content recursively. 
     1050        Note that element attributes will not be mapped. When you return a 
     1051        different node from :func:`function` this node will be incorporated 
     1052        into the result as-is. 
    11051053        """ 
    11061054        if converter is None: 
     
    11121060    def normalized(self): 
    11131061        """ 
    1114         <p>Return a normalized version of <self/>, which means that consecutive 
    1115         <pyref class="Text"><class>Text</class> nodes</pyref> are merged.</p> 
     1062        Return a normalized version of ``self``, which means that consecutive 
     1063        :class:`Text` nodes are merged. 
    11161064        """ 
    11171065        return self 
     
    11191067    def __mul__(self, factor): 
    11201068        """ 
    1121         <p>Return a <pyref class="Frag"><class>Frag</class></pyref> with 
    1122         <arg>factor</arg> times the node as an entry. Note that the node will not 
    1123         be copied, i.e. it is a <z>shallow <meth>__mul__</meth></z>.</p> 
     1069        Return a :class:`Frag` with :var:`factor` times the node as an entry. 
     1070        Note that the node will not be copied, i.e. this is a 
     1071        "shallow :meth:`__mul__`". 
    11241072        """ 
    11251073        return Frag(*factor*[self]) 
     
    11271075    def __rmul__(self, factor): 
    11281076        """ 
    1129         <p>Return a <pyref class="Frag"><class>Frag</class></pyref> with 
    1130         <arg>factor</arg> times the node as an entry.</p> 
     1077        Return a :class:`Frag` with :var:`factor` times the node as an entry. 
    11311078        """ 
    11321079        return Frag(*[self]*factor) 
     
    11341081    def pretty(self, level=0, indent="\t"): 
    11351082        """ 
    1136         <p>Return a prettyfied version of <self/>, i.e. one with properly 
    1137         nested and indented tags (as far as possible). If an element has mixed 
    1138         content (i.e. <pyref class="Text"><class>Text</class></pyref> and 
    1139         non-<pyref class="Text"><class>Text</class></pyref> nodes) the content 
    1140         will be returned as is.</p> 
    1141  
    1142         <p>Note that whitespace will prevent pretty printing too, so 
    1143         you might want to call <pyref method="normalized"><meth>normalized</meth></pyref> 
    1144         and <pyref method="compact"><meth>compact</meth></pyref> before 
    1145         calling <meth>pretty</meth> to remove whitespace.</p> 
     1083        Return a prettyfied version of ``self``, i.e. one with properly nested 
     1084        and indented tags (as far as possible). If an element has mixed content 
     1085        (i.e. :class:`Text` and non-:class:`Text` nodes) the content will be 
     1086        returned as is. 
     1087 
     1088        Note that whitespace will prevent pretty printing too, so you might want 
     1089        to call :meth:`normalized` and :meth:`compact` before calling 
     1090        :meth:`pretty` to remove whitespace. 
    11461091        """ 
    11471092        if level: 
     
    12471192class CharacterData(Node): 
    12481193    """ 
    1249     <p>Base class for &xml; character data (<pyref class="Text"><class>Text</class></pyref>, 
    1250     <pyref class="ProcInst"><class>ProcInst</class></pyref>, 
    1251     <pyref class="Comment"><class>Comment</class></pyref> and 
    1252     <pyref class="DocType"><class>DocType</class></pyref>)</p> 
    1253  
    1254     <p>Provides nearly the same functionality as <class>UserString</class>, 
    1255     but omits a few methods.</p> 
     1194    Base class for XML character data (:class:`Text`, :class:`ProcInst`, 
     1195    :class:`Comment` and :class:`DocType`). 
     1196 
     1197    (Provides nearly the same functionality as :class:`UserString`, 
     1198    but omits a few methods.) 
    12561199    """ 
    12571200    __slots__ = ("_content",) 
     
    12681211    class content(misc.propclass): 
    12691212        """ 
    1270         The text content of the node as a <class>unicode</class> object. 
     1213        The text content of the node as a :class:`unicode` object. 
    12711214        """ 
    12721215        def __get__(self): 
     
    14031346class Text(CharacterData): 
    14041347    """ 
    1405     <p>A text node. The characters <markup>&lt;</markup>, <markup>&gt;</markup>, <markup>&amp;</markup> 
    1406     (and <markup>"</markup> inside attributes) will be <z>escaped</z> with the 
    1407     appropriate character entities when this node is published.</p> 
     1348    A text node. The characters ``<``, ``>``, ``&`` (and ``"`` inside 
     1349    attributes) will be "escaped" with the appropriate character entities when 
     1350    this node is published. 
    14081351    """ 
    14091352 
     
    14321375class Frag(Node, list): 
    14331376    """ 
    1434     <p>A fragment contains a list of nodes and can be used for dynamically constructing content. 
    1435     The member <lit>content</lit> of an <pyref class="Element"><class>Element</class></pyref> is a <class>Frag</class>.</p> 
     1377    A fragment contains a list of nodes and can be used for dynamically 
     1378    constructing content. The attribute :attr:`content` of an :class:`Element` 
     1379    is a :class:`Frag`. 
    14361380    """ 
    14371381 
     
    14681412    def _create(self): 
    14691413        """ 
    1470         <p>internal helper that is used to create an empty clone of <self/>. 
    1471         This is overwritten by <pyref class="Attr"><class>Attr</class></pyref> 
    1472         to insure that attributes don't get initialized with the default 
    1473         value when used in various methods that create new attributes.</p> 
    1474         """ 
     1414        internal helper that is used to create an empty clone of ``self``. 
     1415        """ 
     1416        # This is overwritten by :class:`Attr` to insure that attributes don't 
     1417        # get initialized with the default value when used in various methods 
     1418        # that create new attributes. 
    14751419        return self.__class__() 
    14761420 
    14771421    def clear(self): 
    14781422        """ 
    1479         Make <self/> empty. 
     1423        Make ``self`` empty. 
    14801424        """ 
    14811425        del self[:] 
     
    14961440    def __copy__(self): 
    14971441        """ 
    1498         helper for the <pyref module="copy"><mod>copy</mod></pyref> module. 
     1442        helper for the :mod:`copy` module. 
    14991443        """ 
    15001444        node = self._create() 
     
    15041448    def __deepcopy__(self, memo=None): 
    15051449        """ 
    1506         helper for the <pyref module="copy"><mod>copy</mod></pyref> module. 
     1450        helper for the :mod:`copy` module. 
    15071451        """ 
    15081452        node = self._create() 
     
    15291473    def __getitem__(self, index): 
    15301474        """ 
    1531         <p>Return the <arg>index</arg>'th node for the content of the fragment. 
    1532         If <arg>index</arg> is a list <meth>__getitem__</meth> will work 
    1533         recursively. If <arg>index</arg> is an empty list, <self/> will be returned.</p> 
     1475        Return the :var:`index`'th node for the content of the fragment. If 
     1476        :var:`index` is a list :meth:`__getitem__` will work recursively. 
     1477        If :var:`index` is an empty list, ``self`` will be returned. 
     1478        :meth:`__getitem__` also supports walk filters. 
    15341479        """ 
    15351480        if isinstance(index, list): 
     
    15531498    def __setitem__(self, index, value): 
    15541499        """ 
    1555         <p>Allows you to replace the <arg>index</arg>'th content node of the fragment 
    1556         with the new value <arg>value</arg> (which will be converted to a node). 
    1557         If  <arg>index</arg> is a list <meth>__setitem__</meth> will be applied 
    1558         to the innermost index after traversing the rest of <arg>index</arg> recursively. 
    1559         If <arg>index</arg> is an empty list, an exception will be raised.</p> 
     1500        Allows you to replace the :var:`index`'th content node of the fragment 
     1501        with the new value :var:`value` (which will be converted to a node). 
     1502        If  :var:`index` is a list :meth:`__setitem__` will be applied to the 
     1503        innermost index after traversing the rest of :var:`index` recursively. 
     1504        If :var:`index` is an empty list, an exception will be raised. 
     1505        :meth:`__setitem__` also supports walk filters. 
    15601506        """ 
    15611507        if isinstance(index, list): 
     
    15901536    def __delitem__(self, index): 
    15911537        """ 
    1592         <p>Remove the <arg>index</arg>'th content node from the fragment 
    1593         If <arg>index</arg> is a list, the innermost index will be deleted, 
    1594         after traversing the rest of <arg>index</arg> recursively. 
    1595         If <arg>index</arg> is an empty list, an exception will be raised. 
    1596         Anything except <class>list</class>s, <class>int</class>s and 
    1597         slices will be turned into a walk filter and any child node matching 
    1598         this filter will be deleted from <self/>.</p> 
     1538        Remove the :var:`index`'th content node from the fragment If :var:`index` 
     1539        is a list, the innermost index will be deleted, after traversing the rest 
     1540        of :var:`index` recursively. If :var:`index` is an empty list, an 
     1541        exception will be raised. Anything except :class:`list`, :class:`int` and 
     1542        :class:`slice` objects will be turned into a walk filter and any child 
     1543        node matching this filter will be deleted from ``self``. 
    15991544        """ 
    16001545        if isinstance(index, list): 
     
    16291574    def __mul__(self, factor): 
    16301575        """ 
    1631         Return a <pyref class="Frag"><class>Frag</class></pyref> with 
    1632         <arg>factor</arg> times the content of <self/>. Note that no copies of the 
    1633         content will be generated, so this is a <z>shallow <meth>__mul__</meth></z>. 
     1576        Return a :class:`Frag` with :var:`factor` times the content of ``self``. 
     1577        Note that no copies of the content will be generated, so this is a 
     1578        "shallow :meth:`__mul__`". 
    16341579        """ 
    16351580        node = self._create() 
     
    16471592    def append(self, *others): 
    16481593        """ 
    1649         <p>Append every item in <arg>others</arg> to <self/>.</p> 
     1594        Append every item in :var:`others` to ``self``. 
    16501595        """ 
    16511596        for other in others: 
     
    16581603    def extend(self, items): 
    16591604        """ 
    1660         <p>Append all items from the sequence <arg>items</arg> to <self/>.</p> 
     1605        Append all items from the sequence :var:`items` to ``self``. 
    16611606        """ 
    16621607        self.append(items) 
     
    16641609    def insert(self, index, *others): 
    16651610        """ 
    1666         <p>Insert all items in <arg>others</arg> at the position <arg>index</arg>. 
    1667         (this is the same as <lit><self/>[<arg>index</arg>:<arg>index</arg>] = <arg>others</arg></lit>) 
     1611        Insert all items in :var:`others` at the position :var:`index`. (this is 
     1612        the same as ``self[index:index] = others``) 
    16681613        """ 
    16691614        other = Frag(*others) 
     
    16891634    def withsep(self, separator, clone=False): 
    16901635        """ 
    1691         <p>Return a version of <self/> with a separator node between the nodes of <self/>.</p> 
    1692  
    1693         <p>if <arg>clone</arg> is false one node will be inserted several times, 
    1694         if <arg>clone</arg> is true, clones of this node will be used.</p> 
     1636        Return a version of ``self`` with a separator node between the nodes of 
     1637        ``self``. 
     1638 
     1639        if :var:`clone` is false one node will be inserted several times, if 
     1640        :var:`clone` is true, clones of this node will be used. 
    16951641        """ 
    16961642        node = self._create() 
     
    17061652    def sorted(self, cmp=None, key=None, reverse=False): 
    17071653        """ 
    1708         <p>Return a sorted version of the <self/>. <arg>cmp</arg>, <arg>key</arg> 
    1709         and <arg>reverse</arg> have to same meaning as for the builtin function 
    1710         <func>sorted</func>. 
     1654        Return a sorted version of the ``self``. :var:`cmp`, :var:`key` and 
     1655        :var:`reverse` have to same meaning as for the builtin function 
     1656        :func:`sorted`. 
    17111657        """ 
    17121658        return self.__class__(sorted(self, cmp, key, reverse)) 
     
    17141660    def reversed(self): 
    17151661        """ 
    1716         <p>Return a reversed version of the <self/>.</p> 
     1662        Return a reversed version of the ``self``. 
    17171663        """ 
    17181664        node = list(self) 
     
    17221668    def filtered(self, function): 
    17231669        """ 
    1724         <p>Return a filtered version of the <self/>, i.e. a copy of <self/>, 
    1725         where only content nodes for which <func>function</func> returns 
    1726         true will be copied.</p> 
     1670        Return a filtered version of the ``self``, i.e. a copy of ``self``, 
     1671        where only content nodes for which :func:`function` returns true will 
     1672        be copied. 
    17271673        """ 
    17281674        node = self._create() 
     
    17321678    def shuffled(self): 
    17331679        """ 
    1734         <p>Return a shuffled version of <self/>, i.e. a copy of <self/> where 
    1735         the content nodes are randomly reshuffled.</p> 
     1680        Return a shuffled version of ``self``, i.e. a copy of ``self`` where the 
     1681        content nodes are randomly reshuffled. 
    17361682        """ 
    17371683        content = list(self) 
     
    17891735class Comment(CharacterData): 
    17901736    """ 
    1791     An &xml; comment. 
     1737    An XML comment. 
    17921738    """ 
    17931739 
     
    18191765class DocType(CharacterData): 
    18201766    """ 
    1821     An &xml; document type declaration. 
     1767    An XML document type declaration. 
    18221768    """ 
    18231769 
     
    18541800class ProcInst(CharacterData): 
    18551801    """ 
    1856     <p>Base class for processing instructions. This class is abstract.</p> 
    1857  
    1858     <p>Processing instructions for specific targets must 
    1859     be implemented as subclasses of <class>ProcInst</class>.</p> 
     1802    Base class for processing instructions. 
     1803 
     1804    Processing instructions for specific targets must be implemented as 
     1805    subclasses of :class:`ProcInst`. 
    18601806    """ 
    18611807    __metaclass__ = _ProcInst_Meta 
     
    19531899class Attr(Frag): 
    19541900    """ 
    1955     <p>Base class of all attribute classes.</p> 
    1956  
    1957     <p>The content of an attribute may be any other &xist; node. This is different from 
    1958     a normal &dom;, where only text and character references are allowed. The reason for 
    1959     this is to allow dynamic content (implemented as elements or processing instructions) 
    1960     to be put into attributes.</p> 
    1961  
    1962     <p>Of course, this dynamic content when finally converted to &html; will normally result in 
    1963     a fragment consisting only of text and character references. But note that it is allowed 
    1964     to have elements and processing instructions inside of attributes even when publishing. 
    1965     Processing instructions will be published as is and for elements their content will be 
    1966     published.</p> 
    1967     <example><h>Elements inside attributes</h> 
    1968     <tty> 
    1969     <prompt>&gt;&gt;&gt; </prompt><input>from ll.xist.ns import html, php</input> 
    1970     <prompt>&gt;&gt;&gt; </prompt><input>node = html.img(</input> 
    1971     <prompt>... </prompt><input>   src=php.php("echo 'eggs.gif'"),</input> 
    1972     <prompt>... </prompt><input>   alt=html.abbr(</input> 
    1973     <prompt>... </prompt><input>      "EGGS",</input> 
    1974     <prompt>... </prompt><input>      title="Extensible Graphics Generation System",</input> 
    1975     <prompt>... </prompt><input>      lang="en"</input> 
    1976     <prompt>... </prompt><input>   )</input> 
    1977     <prompt>... </prompt><input>)</input> 
    1978     &gt;&gt;&gt; print node.bytes() 
    1979     &lt;img alt="EGGS" src="&lt;?php echo 'eggs.gif'?&gt;" /&gt; 
    1980     </tty> 
    1981     </example> 
     1901    Base class of all attribute classes. 
     1902 
     1903    The content of an attribute may be any other XIST node. This is different 
     1904    from a normal DOM, where only text and character references are allowed. 
     1905    The reason for this is to allow dynamic content (implemented as elements or 
     1906    processing instructions) to be put into attributes. 
     1907 
     1908    Of course, this dynamic content when finally converted to HTML should 
     1909    normally result in a fragment consisting only of text and character 
     1910    references. But note that it is allowed to have elements and processing 
     1911    instructions inside of attributes even when publishing. Processing 
     1912    instructions will be published as is and for elements their content will be 
     1913    published:: 
     1914 
     1915        >>> from ll.xist.ns import html, php 
     1916        >>> node = html.img( 
     1917        ...    src=php.php("echo 'eggs.gif'"), 
     1918        ...    alt=html.abbr( 
     1919        ...       "EGGS", 
     1920        ...       title="Extensible Graphics Generation System", 
     1921        ...       lang="en" 
     1922        ...    ) 
     1923        ... ) 
     1924        >>> print node.bytes() 
     1925        <img alt="EGGS" src="<?php echo 'eggs.gif'?>" /> 
    19821926    """ 
    19831927    __metaclass__ = _Attr_Meta 
     
    19881932    def isfancy(self): 
    19891933        """ 
    1990         <p>Return whether <self/> contains nodes other than 
    1991         <pyref class="Text"><class>Text</class></pyref>.</p> 
     1934        Return whether ``self`` contains nodes other than :class:`Text`. 
    19921935        """ 
    19931936        for child in self: 
     
    20051948    def checkvalid(self): 
    20061949        """ 
    2007         <p>Check whether <self/> has an allowed value, i.e. one 
    2008         that is specified in the class attribute <lit>values</lit>. 
    2009         If the value is not allowed a warning will be issued through 
    2010         the Python warning framework.</p> 
    2011         <p>If <self/> is <pyref method="isfancy">isfancy</pyref>, 
    2012         no check will be done.</p> 
     1950        Check whether ``self`` has an allowed value, i.e. one that is specified 
     1951        in the class attribute ``values``. If the value is not allowed a warning 
     1952        will be issued through the Python warning framework. 
     1953 
     1954        If ``self`` is "fancy" (i.e. contains non-:class:`Text` nodes), no check 
     1955        will be done. 
    20131956        """ 
    20141957        values = self.__class__.values 
     
    20371980    def _publishattrvalue(self, publisher): 
    20381981        # Internal helper that is used to publish the attribute value 
    2039         # (can be overwritten in subclass (done by e.g. StyleAttr and URLAttr) 
     1982        # (can be overwritten in subclass (done by e.g. :class:`StyleAttr` and 
     1983        # :class:`URLAttr`) 
    20401984        return Frag.publish(self, publisher) 
    20411985 
     
    20702014class TextAttr(Attr): 
    20712015    """ 
    2072     <p>Attribute class that is used for normal text attributes.</p> 
     2016    Attribute class that is used for normal text attributes. 
    20732017    """ 
    20742018 
     
    20762020class IDAttr(Attr): 
    20772021    """ 
    2078     <p>Attribute used for ids.</p> 
     2022    Attribute used for ids. 
    20792023    """ 
    20802024 
     
    20822026class NumberAttr(Attr): 
    20832027    """ 
    2084     <p>Attribute class that is used for when the attribute value may be any kind 
    2085     of number.</p> 
     2028    Attribute class that is used for when the attribute value may be any kind 
     2029    of number. 
    20862030    """ 
    20872031 
     
    20892033class IntAttr(NumberAttr): 
    20902034    """ 
    2091     <p>Attribute class that is used when the attribute value may be an 
    2092     integer.</p> 
     2035    Attribute class that is used when the attribute value may be an 
     2036    integer. 
    20932037    """ 
    20942038 
     
    20962040class FloatAttr(NumberAttr): 
    20972041    """ 
    2098     <p>Attribute class that is used when the attribute value may be a 
    2099     floating point value.</p> 
     2042    Attribute class that is used when the attribute value may be a 
     2043    floating point value. 
    21002044    """ 
    21012045 
     
    21032047class BoolAttr(Attr): 
    21042048    """ 
    2105     <p>Attribute class that is used for boolean attributes. When publishing 
    2106     the value will always be the attribute name, regardless of the real value.</p> 
     2049    Attribute class that is used for boolean attributes. When publishing 
     2050    the value will always be the attribute name, regardless of the real value. 
    21072051    """ 
    21082052 
     
    21252069class ColorAttr(Attr): 
    21262070    """ 
    2127     <p>Attribute class that is used for a color attributes.</p> 
     2071    Attribute class that is used for a color attributes. 
    21282072    """ 
    21292073 
     
    21312075class StyleAttr(Attr): 
    21322076    """ 
    2133     <p>Attribute class that is used for &css; style attributes.</p> 
     2077    Attribute class that is used for CSS style attributes. 
    21342078    """ 
    21352079 
     
    21612105    def urls(self, base=None): 
    21622106        """ 
    2163         <p>Return a list of all the <pyref module="ll.url" class="URL"><class>URL</class></pyref>s 
    2164         found in the style attribute.</p> 
     2107        Return a list of all the URLs (as :class:`URL` objects) found in the style 
     2108        attribute. 
    21652109        """ 
    21662110        from ll.xist import css 
     
    21762120class URLAttr(Attr): 
    21772121    """ 
    2178     <p>Attribute class that is used for &url;s. See the module <pyref module="ll.url"><mod>ll.url</mod></pyref> 
    2179     for more information about &url; handling.</p> 
     2122    Attribute class that is used for URLs. See the module :mod:`ll.url` for more 
     2123    information about URL handling. 
    21802124    """ 
    21812125 
     
    21922136    def asURL(self): 
    21932137        """ 
    2194         <p>Return <self/> as a <pyref module="ll.url" class="URL"><class>URL</class></pyref> 
    2195         instance (note that non-character content will be filtered out).</p> 
     2138        Return ``self`` as a :class:`URL` object (note that non-:class:`Text` 
     2139        content will be filtered out). 
    21962140        """ 
    21972141        return url_.URL(Attr.__unicode__(self)) 
     
    21992143    def forInput(self, root=None): 
    22002144        """ 
    2201         <p>return a <pyref module="ll.url" class="URL"><class>URL</class></pyref> pointing 
    2202         to the real location of the referenced resource. <arg>root</arg> must be the 
    2203         root &url; relative to which <self/> will be interpreted and usually 
    2204         comes from the <lit>root</lit> attribute of the <arg>converter</arg> argument in 
    2205         <pyref class="Node" method="convert"><meth>convert</meth></pyref>.</p> 
     2145        return a :class:`URL` pointing to the real location of the referenced 
     2146        resource. :var:`root` must be the root URL relative to which ``self`` 
     2147        will be interpreted and usually comes from the ``root`` attribute of the 
     2148        :var:`converter` argument in :meth:`convert`. 
    22062149        """ 
    22072150        u = self.asURL() 
     
    22312174    def openread(self, root=None): 
    22322175        """ 
    2233         Return a <pyref module="ll.url" class="ReadResource"><class>ReadResource</class></pyref> 
    2234         for reading from the &url;. 
     2176        Return a :class:`Resource` for reading from the URL. 
    22352177        """ 
    22362178        return self.forInput(root).openread() 
     
    22382180    def openwrite(self, root=None): 
    22392181        """ 
    2240         Return a <pyref module="ll.url" class="WriteResource"><class>WriteResource</class></pyref> 
    2241         for writing to the &url;. 
     2182        Return a :class:`Resource` for writing to the URL. 
    22422183        """ 
    22432184        return self.forInput(root).openwrite() 
     
    22722213class Attrs(Node, dict): 
    22732214    """ 
    2274     <p>An attribute map. Allowed entries are specified through nested subclasses 
    2275     of <pyref class="Attr"><class>Attr</class></pyref>.</p> 
     2215    An attribute map. Allowed entries are specified through nested subclasses 
     2216    of :class:`Attr`. 
    22762217    """ 
    22772218    __metaclass__ = _Attrs_Meta 
     
    23662307    def checkvalid(self): 
    23672308        # collect required attributes 
    2368         attrs = set() 
    2369         for value in self.allowedattrs(): 
    2370             if value.required: 
    2371                 attrs.add(value) 
    2372         # Check each attribute and remove it from the list of required ones 
     2309        attrs = set(value for value in self.allowedattrs() if value.required) 
     2310        # Check each existing attribute and remove it from the list of required ones 
    23732311        for value in self.values(): 
    23742312            value.checkvalid() 
     
    24692407    def has(self, name): 
    24702408        """ 
    2471         <p>return whether <self/> has an attribute with a Python name <arg>name</arg>. 
    2472         <arg>name</arg> may also be an attribute class (either from <lit><self/>.Attrs</lit> 
    2473         are a global attribute).</p> 
     2409        Return whether ``self`` has an attribute with a Python name :var:`name`. 
     2410        :var:`name` may also be an attribute class (either from ``self.Attrs`` 
     2411        or a global attribute). 
    24742412        """ 
    24752413        try: 
     
    24812419    def has_xml(self, name): 
    24822420        """ 
    2483         <p>return whether <self/> has an attribute with an XML name <arg>name</arg>. 
    2484         <arg>name</arg> may also be an attribute class (either from <lit><self/>.Attrs</lit> 
    2485         or for a global attribute).</p> 
     2421        Similar to :meth:`has`, but :var:`name` is treated as the XML name 
     2422        instead of the Python name. 
    24862423        """ 
    24872424        try: 
     
    24962433    def get(self, name, default=None): 
    24972434        """ 
    2498         <p>works like the dictionary method <meth>get</meth>, 
    2499         it returns the attribute with the Python name <arg>name</arg>, 
    2500         or <arg>default</arg> if <self/> has no such attribute. 
    2501         <arg>name</arg> may also be an attribute class (either from 
    2502         <lit><self/>.Attrs</lit> or for a global attribute).</p> 
     2435        works like the dictionary method :meth:`get`, it returns the attribute 
     2436        with the Python name :var:`name`, or :var:`default` if ``self`` has no 
     2437        such attribute. :var:`name` may also be an attribute class (either from 
     2438        ``self.Attrs`` or a global attribute). 
    25032439        """ 
    25042440        attr = self.attr(name) 
     
    25092445    def get_xml(self, name, default=None): 
    25102446        """ 
    2511         <p>works like the dictionary method <meth>get</meth>, 
    2512         it returns the attribute with the XML name <arg>name</arg>, 
    2513         or <arg>default</arg> if <self/> has no such attribute. 
    2514         <arg>name</arg> may also be an attribute class (either from 
    2515         <lit><self/>.Attrs</lit> or for a global attribute).</p> 
     2447        Similar to :meth:`get`, but :var:`name` is treated as the XML name 
     2448        instead of the Python name. 
    25162449        """ 
    25172450        attr = self.attr_xml(name) 
     
    25222455    def set(self, name, value): 
    25232456        """ 
    2524         <p>Set the attribute with the Python <arg>name</arg> to the value <arg>value</arg>. 
    2525         <arg>name</arg> may be a string or an attribute class.</p> 
    2526         <p>The newly set attribute will be returned.</p> 
     2457        Set the attribute with the Python :var:`name` to the value :var:`value`. 
     2458        :var:`name` may be a string or an attribute class. The newly set attribute 
     2459        will be returned. 
    25272460        """ 
    25282461        attr = self.allowedattr(name) 
     
    25332466    def set_xml(self, name, value): 
    25342467        """ 
    2535         <p>Set the attribute with the XML <arg>name</arg> to the value <arg>value</arg>.</p> 
    2536         <p>The newly set attribute will be returned.</p> 
     2468        Similar to :meth:`set`, but :var:`name` is treated as the XML name 
     2469        instead of the Python name. 
    25372470        """ 
    25382471        attr = self.allowedattr_xml(name) 
     
    25432476    def setdefault(self, name, default): 
    25442477        """ 
    2545         <p>works like the dictionary method <meth>setdefault</meth>, 
    2546         it returns the attribute with the Python name <arg>name</arg>. 
    2547         If <self/> has no such attribute, it will be set to <arg>default</arg> 
    2548         and <arg>default</arg> will be returned as the new attribute value.</p> 
     2478        Works like the dictionary method :meth:`setdefault`, it returns the 
     2479        attribute with the Python name :var:`name`. If ``self`` has no such 
     2480        attribute, it will be set to :var:`default` and :var:`default` will be 
     2481        returned as the new attribute value. 
    25492482        """ 
    25502483        value = self.attr(name) 
     
    25572490    def setdefault_xml(self, name, default): 
    25582491        """ 
    2559         <p>works like the dictionary method <meth>setdefault</meth>, 
    2560         it returns the attribute with the XML name <arg>name</arg>. 
    2561         If <self/> has no such attribute, it will be set to <arg>default</arg> 
    2562         and <arg>default</arg> will be returned as the new attribute value.</p> 
     2492        Similar to :meth:`setdefault`, but :var:`name` is treated as the XML name 
     2493        instead of the Python name. 
    25632494        """ 
    25642495        value = self.attr_xml(name) 
     
    25712502    def update(self, *args, **kwargs): 
    25722503        """ 
    2573         Copies attributes over from all mappings in <arg>args</arg> and from <arg>kwargs</arg>. 
     2504        Copies attributes over from all mappings in :var:`args` and from 
     2505        :var:`kwargs`. 
    25742506        """ 
    25752507        for mapping in args + (kwargs,): 
     
    25862518    def allowedattrs(cls): 
    25872519        """ 
    2588         <p>Return an iterator over all allowed attribute classes. 
     2520        Return an iterator over all allowed attribute classes. 
    25892521        """ 
    25902522        return cls._bypyname.itervalues() 
     
    26802612    def filtered(self, function): 
    26812613        """ 
    2682         returns a filtered version of the <self/>. 
     2614        Return a filtered version of the ``self``. 
    26832615        """ 
    26842616        node = self._create() 
     
    27122644    def withnames(self, *names): 
    27132645        """ 
    2714         <p>Return a copy of <self/> where only the attributes with Python names 
    2715         in <arg>names</arg> are kept, all others are removed.</p> 
     2646        Return a copy of ``self`` where only the attributes with Python names 
     2647        in :var:`names` are kept, all others are removed. 
    27162648        """ 
    27172649        def isok(node): 
     
    27232655    def withnames_xml(self, *names): 
    27242656        """ 
    2725         <p>Return a copy of <self/> where only the attributes with XML names 
    2726         in <arg>names</arg> are kept, all others are removed.</p> 
     2657        Return a copy of ``self`` where only the attributes with XML names 
     2658        in :var:`names` are kept, all others are removed. 
    27272659        """ 
    27282660        def isok(node): 
     
    27342666    def withoutnames(self, *names): 
    27352667        """ 
    2736         <p>Return a copy of <self/> where all the attributes with Python names 
    2737         in <arg>names</arg> are removed.</p> 
     2668        Return a copy of ``self`` where all the attributes with Python names 
     2669        in :var:`names` are removed. 
    27382670        """ 
    27392671        def isok(node): 
     
    27452677    def withoutnames_xml(self, *names): 
    27462678        """ 
    2747         <p>Return a copy of <self/> where all the attributes with XML names 
    2748         in <arg>names</arg> are removed.</p> 
     2679        Return a copy of ``self`` where all the attributes with XML names 
     2680        in :var:`names` are removed. 
    27492681        """ 
    27502682        def isok(node): 
     
    27702702 
    27712703def _patchclassnames(dict, name): 
    2772     # If an Attrs class has been provided patch up its class names 
     2704    # If an :class:`Attrs` class has been provided patch up its class names 
    27732705    try: 
    27742706        attrs = dict["Attrs"] 
     
    28072739class Element(Node): 
    28082740    """ 
    2809     <p>This class represents &xml;/&xist; elements. All elements implemented 
    2810     by the user must be derived from this class.</p> 
    2811  
    2812     <p>Elements support the following class variables:</p> 
    2813     <dl> 
    2814     <dt><lit>model</lit></dt><dd>This is an object that is used for 
    2815     validating the content of the element. See the module 
    2816     <pyref module="ll.xist.sims"><mod>ll.xist.sims</mod></pyref> 
    2817     for more info. If <lit>model</lit> is <lit>None</lit> validation will 
    2818     be skipped, otherwise it will be performed when parsing or publishing.</dd> 
    2819  
    2820     <dt><lit>Attrs</lit></dt><dd>This is a class derived from 
    2821     <pyref class="Element.Attrs"><class>Element.Attrs</class></pyref> 
    2822     and should define all attributes as classes nested inside this 
    2823     <class>Attrs</class> class.</dd> 
    2824  
    2825     <dt><lit>xmlns</lit></dt><dd>This is the name of the namespace this 
    2826     element belong to.</dd> 
    2827  
    2828     <dt><lit>register</lit></dt><dd>If <lit>register</lit> is false the 
    2829     element won't be registered with the parser.</dd> 
    2830  
    2831     <dt><lit>xmlname</lit></dt><dd>If the class name has to be different 
    2832     from the &xml; name (e.g. because the &xml; name is not a valid Python identifier) 
    2833     <lit>xmlname</lit> can be used to specify the real &xml; name.</dd> 
    2834     </dl> 
     2741    This class represents XML/XIST elements. All elements implemented by the 
     2742    user must be derived from this class. 
     2743 
     2744    Elements support the following class variables: 
     2745 
     2746    :attr:`model` : object with :meth:`checkvalid` method 
     2747        This is an object that is used for validating the content of the element. 
     2748        See the module :mod:`ll.xist.sims` for more info. If ``model`` is 
     2749        :const:`None` validation will be skipped, otherwise it will be performed 
     2750        when parsing or publishing. 
     2751 
     2752    :attr:`Attrs` : :class:`Element.Attrs` subclass 
     2753        This is a class derived from :class:`Element.Attrs` and must define all 
     2754        attributes as classes nested inside this :class:`Attrs` class. 
     2755 
     2756    :attr:`xmlns` : string 
     2757        This is the name of the namespace this element belong to. 
     2758 
     2759    :attr:`register` : bool 
     2760        If :attr:`register` is false the element will never be registered in a 
     2761        :class:`Pool`. The default is :const:`True`. 
     2762 
     2763    :attr:`xmlname` : string 
     2764        If the class name has to be different from the XML name (e.g. because the 
     2765        XML name is not a valid Python identifier) :attr:`xmlname` can be used to 
     2766        specify the real XML name. Otherwise the XML name will be the Python name. 
    28352767    """ 
    28362768    __metaclass__ = _Element_Meta 
     
    28412773    Attrs = Attrs 
    28422774 
    2843     def __enter__(self): 
    2844         stack = getstack() 
    2845         if stack: 
    2846             stack[-1].append(self) 
    2847         stack.append(self) 
    2848         return self 
    2849  
    2850     def __exit__(self, type, value, traceback): 
    2851         getstack().pop() 
    2852  
    28532775    def __init__(self, *content, **attrs): 
    28542776        """ 
    2855         <p>Create a new <class>Element</class> instance.</p> 
    2856  
    2857         <p>positional arguments are treated as content nodes. 
    2858         Keyword arguments and dictionaries are treated as attributes.</p> 
     2777        Create a new :class:`Element` instance. 
     2778 
     2779        Positional arguments are treated as content nodes. Keyword arguments and 
     2780        dictionaries are treated as attributes. 
    28592781        """ 
    28602782        self.attrs = self.Attrs() 
     
    28912813            self.attrs[key] = value 
    28922814 
     2815    def __enter__(self): 
     2816        """ 
     2817        :class:`Element` nodes can be used in with blocks to build XIST trees. 
     2818        Inside a with block ``+`` and :func:`add` can be used to append node to 
     2819        the currently active element in the with block:: 
     2820 
     2821            with html.ul() as node: 
     2822                +html.li("I hear and I forget.") 
     2823                +html.li("I see and I believe.") 
     2824                +html.li("I do and I understand.") 
     2825                xsc.add(class_="quote") 
     2826            print node.bytes() 
     2827        """ 
     2828        stack = getstack() 
     2829        if stack: 
     2830            stack[-1].append(self) 
     2831        stack.append(self) 
     2832        return self 
     2833 
     2834    def __exit__(self, type, value, traceback): 
     2835        getstack().pop() 
     2836 
    28932837    def __call__(self, *content, **attrs): 
     2838        """ 
     2839        Calling an element add items in :var:`content` to the element content 
     2840        and set attributes from :var:`attrs`. The element itself will be returned. 
     2841        """ 
    28942842        for child in content: 
    28952843            if isinstance(child, dict): 
     
    29212869    def append(self, *items): 
    29222870        """ 
    2923         <p>Append every item in <arg>items</arg> to the element content.</p> 
     2871        Append every item in :var:`items` to the element content. 
    29242872        """ 
    29252873        self.content.append(*items) 
     
    29272875    def extend(self, items): 
    29282876        """ 
    2929         <p>Append all items in <arg>items</arg> to element content.</p> 
     2877        Append all items in :var:`items` to element content. 
    29302878        """ 
    29312879        self.content.extend(items) 
     
    29332881    def insert(self, index, *items): 
    29342882        """ 
    2935         <p>Insert every item in <arg>items</arg> at the position <arg>index</arg>.</p> 
     2883        Insert every item in :var:`items` at the position :var:`index`. 
    29362884        """ 
    29372885        self.content.insert(index, *items) 
     
    29452893    def clone(self): 
    29462894        node = self.__class__() # "virtual" constructor 
    2947         node.content = self.content.clone() # this is faster than passing it in the constructor (no tonode call) 
     2895        node.content = self.content.clone() # this is faster than passing it in the constructor (no :func:`tonode` call) 
    29482896        node.attrs = self.attrs.clone() 
    29492897        return self._decoratenode(node) 
     
    29692917    def _addimagesizeattributes(self, url, widthattr=None, heightattr=None): 
    29702918        """ 
    2971         <p>Automatically set image width and height attributes.</p> 
    2972  
    2973         <p>The size of the image with the &url; <arg>url</arg> will be determined and 
    2974         the width of the image will be put into the attribute with the name <arg>widthattr</arg> 
    2975         if <arg>widthattr</arg> is not <lit>None</lit> and the attribute is not set. The 
    2976         same will happen for the height, which will be put into the <arg>heighattr</arg>.</p> 
     2919        Automatically set image width and height attributes. 
     2920 
     2921        The size of the image with the URL :var:`url` will be determined and the 
     2922        width of the image will be put into the attribute with the name 
     2923        :var:`widthattr` if :var:`widthattr` is not :const:`None` and the 
     2924        attribute is not set already. The same will happen for the height, which 
     2925        will be put into the attribute named :var:`heighattr`. 
    29772926        """ 
    29782927 
     
    30002949        """ 
    30012950        Does the full publication of the element. If you need full elements 
    3002         inside attributes (e.g. for &jsp; tag libraries), you can overwrite 
    3003         <meth>publish</meth> and simply call this method. 
     2951        inside attributes (e.g. for JSP tag libraries), you can overwrite 
     2952        :meth:`publish` and simply call this method. 
    30042953        """ 
    30052954        name = self._publishname(publisher) 
     
    30533002    def __getitem__(self, index): 
    30543003        """ 
    3055         <p>If <arg>index</arg> is a string, return the attribute with this (Python) name.</p> 
    3056         <p>If <arg>index</arg> is a tuple consisting of a namespace and a string, 
    3057         return the global attribute with this (Python) name.</p> 
    3058         <p>If <arg>index</arg> is a number return the appropriate content node.</p> 
    3059         <p><arg>index</arg> may also be a list, in with case <meth>__getitem__</meth> 
    3060         will be applied recusively.</p> 
     3004        If :var:`index` is a string, return the attribute with this (Python) 
     3005        name. If :var:`index` is an attribute class, return the attribute 
     3006        that is an instance of this class. If :var:`index` is a number or slice 
     3007        return the appropriate content node. :var:`index` may also be a list, in 
     3008        with case :meth:`__getitem__` will be applied recusively. 
     3009        :meth:`__getitem__` also supports walk filters. 
     3010 
    30613011        """ 
    30623012        if isinstance(index, (basestring, _Attr_Meta)): 
     
    30753025    def __setitem__(self, index, value): 
    30763026        """ 
    3077         <p>Set an attribute or content node to the value <arg>value</arg>.</p> 
    3078         <p>For possible types for <arg>index</arg> see <pyref method="__getitem__"><meth>__getitem__</meth></pyref>.</p> 
     3027        Set an attribute or content node to the value :var:`value`. For possible 
     3028        types for :var:`index` see :meth:`__getitem__`. 
    30793029        """ 
    30803030        if isinstance(index, (basestring, _Attr_Meta)): 
     
    30973047    def __delitem__(self, index): 
    30983048        """ 
    3099         <p>Remove an attribute or content node.</p> 
    3100         <p>For possible types for <arg>index</arg> see <pyref method="__getitem__"><meth>__getitem__</meth></pyref>.</p> 
     3049        Remove an attribute or content node. For possible types for :var:`index` 
     3050        see :meth:`__getitem__`. 
    31013051        """ 
    31023052        if isinstance(index, (basestring, _Attr_Meta)): 
     
    31103060    def __getslice__(self, index1, index2): 
    31113061        """ 
    3112         Returns a copy of the element that contains a slice of the content. 
     3062        Return a copy of the element that contains a slice of the content. 
    31133063        """ 
    31143064        return self.content[index1:index2] 
     
    31163066    def __setslice__(self, index1, index2, sequence): 
    31173067        """ 
    3118         Replaces a slice of the content of the element. 
     3068        Replace a slice of the content of the element. 
    31193069        """ 
    31203070        self.content[index1:index2] = sequence 
     
    31223072    def __delslice__(self, index1, index2): 
    31233073        """ 
    3124         Removes a slice of the content of the element. 
     3074        Remove a slice of the content of the element. 
    31253075        """ 
    31263076        del self.content[index1:index2] 
     
    31323082    def __len__(self): 
    31333083        """ 
    3134         return the number of children. 
     3084        Return the number of children. 
    31353085        """ 
    31363086        return len(self.content) 
     
    31583108    def withsep(self, separator, clone=False): 
    31593109        """ 
    3160         <p>returns a version of <self/> with a separator node between the child 
    3161         nodes of <self/>. For more info see 
    3162         <pyref class="Frag" method="withsep"><meth>Frag.withsep</meth></pyref>.</p> 
     3110        Return a version of ``self`` with a separator node between the child 
     3111        nodes of ``self``. For more info see :meth:`Frag.withsep`. 
    31633112        """ 
    31643113        node = self.__class__() 
     
    31693118    def sorted(self, cmp=None, key=None, reverse=False): 
    31703119        """ 
    3171         returns a sorted version of <self/>. <arg>compare</arg> is a comparison 
    3172         function. If <arg>compare</arg> is omitted, the character content will 
    3173         be compared. 
     3120        Return a sorted version of ``self``. :var:`compare` is a comparison 
     3121        function. The arguments :var:`cmp`, :var:`key` and :var:`reverse` have 
     3122        the same meaning as fot the builtin :func:`sorted` function. 
    31743123        """ 
    31753124        node = self.__class__() 
     
    31803129    def reversed(self): 
    31813130        """ 
    3182         returns a reversed version of <self/>. 
     3131        Return a reversed version of ``self``. 
    31833132        """ 
    31843133        node = self.__class__() 
     
    31893138    def filtered(self, function): 
    31903139        """ 
    3191         returns a filtered version of the <self/>. 
     3140        Return a filtered version of the ``self``. 
    31923141        """ 
    31933142        node = self.__class__() 
     
    31983147    def shuffled(self): 
    31993148        """ 
    3200         returns a shuffled version of the <self/>. 
     3149        Return a shuffled version of the ``self``. 
    32013150        """ 
    32023151        node = self.__class__() 
     
    32733222class Entity(Node): 
    32743223    """ 
    3275     <p>Class for entities. Derive your own entities from it and overwrite 
    3276     <pyref class="Node" method="convert"><meth>convert</meth></pyref>.</p> 
     3224    Class for entities. Derive your own entities from it and overwrite 
     3225    :meth:`convert`. 
    32773226    """ 
    32783227    __metaclass__ = _Entity_Meta 
     
    33163265class CharRef(Text, Entity): 
    33173266    """ 
    3318     <p>A simple character reference, the codepoint is in the class attribute 
    3319     <lit>codepoint</lit>.</p> 
     3267    A simple named character reference, the codepoint is in the class attribute 
     3268    :attr:`codepoint`. 
    33203269    """ 
    33213270    __metaclass__ = _CharRef_Meta 
     
    33993348 
    34003349class Pool(misc.Pool): 
     3350    """ 
     3351    A :class:`Pool` stores a collection of XIST classes and can be passed to a 
     3352    parser. The parser will ask the pool which classes to use when elements, 
     3353    processing instructions etc. have to be instantiated. 
     3354    """ 
    34013355    def __init__(self, *objects): 
     3356        """ 
     3357        Create a :class:`Pool` object. All items in :var:`objects` will be 
     3358        registered in the pool. 
     3359        """ 
    34023360        self._elementsbyxmlname = {} 
    34033361        self._elementsbypyname = {} 
     
    34153373    def register(self, object): 
    34163374        """ 
    3417         <p>Register <arg>object</arg> in the pool. <arg>object</arg> can be:</p> 
    3418         <ul> 
    3419         <li>A <pyref class="Element"><class>Element</class></pyref>, 
    3420         <pyref class="ProcInst"><class>ProcInst</class></pyref>, 
    3421         <pyref class="Entity"><class>Entity</class></pyref>, 
    3422         <pyref class="CharRef"><class>CharRef</class></pyref> class;</li> 
    3423         <li>An <pyref class="Attr"><class>Attr</class></pyref> class 
    3424         for a global attribute;</li> 
    3425         <li>An <pyref class="Attrs"><class>Attrs</class></pyref> class 
    3426         containing global attributes;</li> 
    3427         <li>A <class>dict</class> (all <class>Node</class> classes in the 
    3428         values will be registered, this makes it possible to e.g. register all 
    3429         local variables by passing <lit>vars()</lit>);</li> 
    3430         <li>A module (all <class>Node</class> classes and the <lit>xmlns</lit> attribute 
    3431         if it's a string) in the module will be registered);</li> 
    3432         </ul> 
     3375        Register :var:`object` in the pool. :var:`object` can be: 
     3376 
     3377        *   A :class:`Element`, :class:`ProcInst`, :class:`Entity`, or 
     3378            :class:`CharRef` class; 
     3379 
     3380        *   An :class:`Attr` class for a global attribute; 
     3381 
     3382        *   An :class:`Attrs` class containing global attributes; 
     3383 
     3384        *   A :class:`dict` (all values will be registered, this makes it possible 
     3385            to e.g. register all local variables by passing ``vars()``); 
     3386 
     3387        *   A module (all attributes in the module will be registered). 
    34333388        """ 
    34343389        if isinstance(object, type): 
     
    34843439    def elementclass(self, name, xmlns): 
    34853440        """ 
    3486         Return the element class for the element with the Python name 
    3487         <arg>name</arg> and the namespace <arg>xmlns</arg>. If the element can't 
    3488         be found a <class>IllegalElementError</class> will be raised. 
     3441        Return the element class for the element with the Python name :var:`name` 
     3442        and the namespace :var:`xmlns`. If the element can't be found a 
     3443        :exc:`IllegalElementError` will be raised. 
    34893444        """ 
    34903445        if isinstance(xmlns, (list, tuple)): 
     
    35103465    def elementclass_xml(self, name, xmlns): 
    35113466        """ 
    3512         Return the element class for the element type with the &xml; name 
    3513         <arg>name</arg> and the namespace <arg>xmlns</arg>. If the element can't 
    3514         be found a <class>IllegalElementError</class> will be raised. 
     3467        Return the element class for the element type with the XML name 
     3468        :var:`name` and the namespace :var:`xmlns`. If the element can't 
     3469        be found a :exc:`IllegalElementError` will be raised. 
    35153470        """ 
    35163471        if isinstance(xmlns, (list, tuple)): 
     
    35373492        """ 
    35383493        Return an element object for the element type with the Python name 
    3539         <arg>name</arg> and the namespace <arg>xmlns</arg>. 
     3494        :var:`name` and the namespace :var:`xmlns`. 
    35403495        """ 
    35413496        return self.elementclass(name, xmlns)() 
     
    35433498    def element_xml(self, name, xmlns): 
    35443499        """ 
    3545         Return an element object for the element type with the &xml; name 
    3546         <arg>name</arg> and the namespace <arg>xmlns</arg>. 
     3500        Return an element object for the element type with the XML name 
     3501        :var:`name` and the namespace :var:`xmlns`. 
    35473502        """ 
    35483503        return self.elementclass_xml(name, xmlns)() 
     
    35503505    def haselement(self, name, xmlns): 
    35513506        """ 
    3552         Is there a registered element class in <self/> for the element type 
    3553         with the Python name <arg>name</arg> and the namespace <arg>xmlns</arg>? 
     3507        Is there a registered element class in ``self`` for the element type 
     3508        with the Python name :var:`name` and the namespace :var:`xmlns`? 
    35543509        """ 
    35553510        return (name, nsname(xmlns)) in self._elementsbypyname or any(base.haselement(name, xmlns) for base in self.bases) 
     
    35573512    def haselement_xml(self, name, xmlns): 
    35583513        """ 
    3559         Is there a registered element class in <self/> for the element type 
    3560         with the &xml; name <arg>name</arg> and the namespace <arg>xmlns</arg>? 
     3514        Is there a registered element class in ``self`` for the element type 
     3515        with the XML name :var:`name` and the namespace :var:`xmlns`? 
    35613516        """ 
    35623517        return (name, nsname(xmlns)) in self._elementsbyxmlname or any(base.haselement_xml(name, xmlns) for base in self.bases) 
     
    35713526        """ 
    35723527        Return the processing instruction class for the PI with the Python name 
    3573         <arg>name</arg>. If the element can't be found a 
    3574         <class>IllegalProcInstError</class> will be raised. 
     3528        :var:`name`. If the element can't be found a :exc:`IllegalProcInstError` 
     3529        will be raised. 
    35753530        """ 
    35763531        try: 
     
    35863541    def procinstclass_xml(self, name): 
    35873542        """ 
    3588         Return the processing instruction class for the PI with the &xml; name 
    3589         <arg>name</arg>. If the element can't be found a 
    3590         <class>IllegalProcInstError</class> will be raised. 
     3543        Return the processing instruction class for the PI with the XML name 
     3544        :var:`name`. If the element can't be found a :exc:`IllegalProcInstError` 
     3545        will be raised. 
    35913546        """ 
    35923547        try: 
     
    36033558        """ 
    36043559        Return a processing instruction object for the PI type with the Python 
    3605         target name <arg>name</arg>. 
     3560        target name :var:`name`. 
    36063561        """ 
    36073562        return self.procinstclass(name)(content) 
     
    36093564    def procinst_xml(self, name, content): 
    36103565        """ 
    3611         Return a processing instruction object for the PI type with the &xml; 
    3612         target name <arg>name</arg>. 
     3566        Return a processing instruction object for the PI type with the XML 
     3567        target name :var:`name`. 
    36133568        """ 
    36143569        return self.procinstclass_xml(name)(content) 
     
    36163571    def hasprocinst(self, name): 
    36173572        """ 
    3618         Is there a registered processing instruction class in <self/> for the 
    3619         PI with the Python name <arg>name</arg>? 
     3573        Is there a registered processing instruction class in ``self`` for the 
     3574        PI with the Python name :var:`name`? 
    36203575        """ 
    36213576        return name in self._procinstsbypyname or any(base.hasprocinst(name) for base in self.bases) 
     
    36233578    def hasprocinst_xml(self, name): 
    36243579        """ 
    3625         Is there a registered processing instruction class in <self/> for the 
    3626         PI with the &xml; name <arg>name</arg>? 
     3580        Is there a registered processing instruction class in ``self`` for the 
     3581        PI with the XML name :var:`name`? 
    36273582        """ 
    36283583        return name in self._procinstsbyxmlname or any(base.hasprocinst_xml(name) for base in self.bases) 
     
    36363591    def entityclass(self, name): 
    36373592        """ 
    3638         Return the entity for the entity with the Python name <arg>name</arg>. 
    3639         If the entity can't be found a <class>IllegalEntityError</class> will 
    3640         be raised. 
     3593        Return the entity for the entity with the Python name :var:`name`. 
     3594        If the entity can't be found a :exc:`IllegalEntityError` will be raised. 
    36413595        """ 
    36423596        try: 
     
    36523606    def entityclass_xml(self, name): 
    36533607        """ 
    3654         Return the entity for the entity with the &xml; name <arg>name</arg>. 
    3655         If the entity can't be found a <class>IllegalEntityError</class> will be 
    3656         raised. 
     3608        Return the entity for the entity with the XML name :var:`name`. 
     3609        If the entity can't be found a :exc:`IllegalEntityError` will be raised. 
    36573610        """ 
    36583611        try: 
     
    36683621    def entity(self, name): 
    36693622        """ 
    3670         Return an entity object for the entity with the Python name 
    3671         <arg>name</arg>. 
     3623        Return an entity object for the entity with the Python name :var:`name`. 
    36723624        """ 
    36733625        return self.entityclass(name)() 
     
    36753627    def entity_xml(self, name): 
    36763628        """ 
    3677         Return an entity object for the entity with the &xml; name 
    3678         <arg>name</arg>. 
     3629        Return an entity object for the entity with the XML name :var:`name`. 
    36793630        """ 
    36803631        return self.entityclass_xml(name)() 
     
    36823633    def hasentity(self, name): 
    36833634        """ 
    3684         Is there a registered entity class in <self/> for the entity with the 
    3685         Python name <arg>name</arg>? 
     3635        Is there a registered entity class in ``self`` for the entity with the 
     3636        Python name :var:`name`? 
    36863637        """ 
    36873638        return name in self._entitiesbypyname or any(base.hasentity(name) for base in self.bases) 
     
    36893640    def hasentity_xml(self, name): 
    36903641        """ 
    3691         Is there a registered entity class in <self/> for the entity with the 
    3692         &xml; name <arg>name</arg>? 
     3642        Is there a registered entity class in ``self`` for the entity with the 
     3643        XML name :var:`name`? 
    36933644        """ 
    36943645        return name in self._entitiesbyxmlname or any(base.hasentity_xml(name) for base in self.bases) 
     
    37023653    def charrefclass(self, name): 
    37033654        """ 
    3704         Return the character entity with the Python name <arg>name</arg>. 
    3705         <arg>name</arg> can also be an <class>int</class> specifying the codepoint. 
    3706         If the character entity can't be found a <class>IllegalEntityError</class> 
     3655        Return the character entity with the Python name :var:`name`. 
     3656        :var:`name` can also be an :class:`int` specifying the codepoint. 
     3657        If the character entity can't be found a :exc:`IllegalEntityError` 
    37073658        will be raised. 
    37083659        """ 
     
    37213672    def charrefclass_xml(self, name): 
    37223673        """ 
    3723         Return the character entity with the &xml; name <arg>name</arg>. 
    3724         <arg>name</arg> can also be an <class>int</class> specifying the codepoint. 
    3725         If the character entity can't be found a <class>IllegalEntityError</class> 
     3674        Return the character entity with the XML name :var:`name`. 
     3675        :var:`name` can also be an :class:`int` specifying the codepoint. 
     3676        If the character entity can't be found a :exc:`IllegalEntityError` 
    37263677        will be raised. 
    37273678        """ 
     
    37403691    def charref(self, name): 
    37413692        """ 
    3742         Return a character entity object for the chacter with the Python name 
    3743         or codepoint <arg>name</arg>. 
     3693        Return a character entity object for the character with the Python name 
     3694        or codepoint :var:`name`. 
    37443695        """ 
    37453696        return self.charrefclass(name)() 
     
    37473698    def charref_xml(self, name): 
    37483699        """ 
    3749         Return a character entity object for the chacter with the &xml; name 
    3750         or codepoint <arg>name</arg>. 
     3700        Return a character entity object for the character with the XML name 
     3701        or codepoint :var:`name`. 
    37513702        """ 
    37523703        return self.charrefclass_xml(name)() 
     
    37543705    def hascharref(self, name): 
    37553706        """ 
    3756         Is there a registered character entity class in <self/> with the Python 
    3757         name or codepoint <arg>name</arg>? 
     3707        Is there a registered character entity class in ``self`` with the Python 
     3708        name or codepoint :var:`name`? 
    37583709        """ 
    37593710        if isinstance(name, (int, long)): 
     
    37653716    def hascharref_xml(self, name): 
    37663717        """ 
    3767         Is there a registered character entity class in <self/> with the &xml; 
    3768         name or codepoint <arg>name</arg>? 
     3718        Is there a registered character entity class in ``self`` with the XML 
     3719        name or codepoint :var:`name`? 
    37693720        """ 
    37703721        if isinstance(name, (int, long)): 
     
    37773728        """ 
    37783729        Return the aatribute class for the global attribute with the Python name 
    3779         <arg>name</arg> and the namespace <arg>xmlns</arg>. If the attribute can't 
    3780         be found a <class>IllegalAttrError</class> will be raised. 
     3730        :var:`name` and the namespace :var:`xmlns`. If the attribute can't 
     3731        be found a :exc:`IllegalAttrError` will be raised. 
    37813732        """ 
    37823733        if not isinstance(xmlns, (list, tuple)): 
     
    37973748    def attrclass_xml(self, name, xmlns): 
    37983749        """ 
    3799         Return the aatribute class for the global attribute with the &xml; name 
    3800         <arg>name</arg> and the namespace <arg>xmlns</arg>. If the attribute can't 
    3801         be found a <class>IllegalAttrError</class> will be raised. 
     3750        Return the attribute class for the global attribute with the XML name 
     3751        :var:`name` and the namespace :var:`xmlns`. If the attribute can't 
     3752        be found a :exc:`IllegalAttrError` will be raised. 
    38023753        """ 
    38033754        if not isinstance(xmlns, (list, tuple)): 
     
    38183769    def text(self, content): 
    38193770        """ 
    3820         Create a text node with the content <arg>content</arg>. 
     3771        Create a text node with the content :var:`content`. 
    38213772        """ 
    38223773        return Text(content) 
     
    38243775    def comment(self, content): 
    38253776        """ 
    3826         Create a comment node with the content <arg>content</arg>. 
     3777        Create a comment node with the content :var:`content`. 
    38273778        """ 
    38283779        return Comment(content) 
     
    38373788 
    38383789    def clear(self): 
     3790        """ 
     3791        Make <self/> empty. 
     3792        """ 
    38393793        self._elementsbyxmlname.clear() 
    38403794        self._elementsbypyname.clear() 
     
    38523806    def clone(self): 
    38533807        """ 
    3854         Return a copy of <self/>. 
     3808        Return a copy of ``self``. 
    38553809        """ 
    38563810        copy = Pool.clone(self) 
     
    38883842def docprefixes(): 
    38893843    """ 
    3890     Return a prefix mapping suitable for parsing &xist; docstrings. 
     3844    Return a prefix mapping suitable for parsing XIST docstrings. 
    38913845    """ 
    38923846    from ll.xist.ns import html, chars, abbr, doc, specials 
     
    38963850def nsname(xmlns): 
    38973851    """ 
    3898     If <arg>xmlns</arg> is a module, return <lit><arg>xmlns</arg>.xmlns</lit>. 
    3899     Else return <arg>xmlns</arg> unchanged. 
     3852    If :var:`xmlns` is a module, return ``xmlns.xmlns``, else return 
     3853    :var:`xmlns` unchanged. 
    39003854    """ 
    39013855    if xmlns is not None and not isinstance(xmlns, basestring): 
     
    39063860def nsclark(xmlns): 
    39073861    """ 
    3908     Return a namespace name in Clark notation. <arg>xmlns</arg> can be 
    3909     <lit>None</lit>, a string or a module. 
     3862    Return a namespace name in Clark notation. :var:`xmlns` can be :const:`None`, 
     3863    a string or a module. 
    39103864    """ 
    39113865    if xmlns is None: 
     
    39303884class Location(object): 
    39313885    """ 
    3932     <p>Represents a location in an &xml; entity.</p> 
     3886    Represents a location in an XML entity. 
    39333887    """ 
    39343888    __slots__ = ("url", "line", "col", "char") 
     
    39363890    def __init__(self, url=None, line=None, col=None): 
    39373891        """ 
    3938         Create a new <class>Location</class> object using the arguments 
    3939         passed in. <arg>url</arg> is the &url;/filename. <arg>line</arg> is 
    3940         the line number and <arg>col</arg> is the column number (both starting 
    3941         at 0). 
     3892        Create a new :class:`Location` object using the arguments passed in. 
     3893        :var:`url` is the URL/filename. :var:`line` is the line number and 
     3894        :var:`col` is the column number (both starting at 0). 
    39423895        """ 
    39433896        self.url = url 
     
    39473900    def offset(self, offset): 
    39483901        """ 
    3949         <p>Return a location where the line number is incremented by offset 
    3950         (and the column number is reset to 0).</p> 
     3902        Return a location where the line number is incremented by offset 
     3903        (and the column number is reset to 0). 
    39513904        """ 
    39523905        if offset==0: