Anonymous avatar Anonymous committed 27ef5e8

Added build.bat batch file for VC Toolkit 2003 build support.
Added registry key for VC Toolkit 2003 build support.
Added VC build instructions.
Brushed up HTML documentation generator(s).

Comments (0)

Files changed (42)

+rem In case you are using the VC++ Toolkit
+rem --------------------------------------
+rem Set the PATH, INCLUDE and LIB to include the Platform SDK and VC++ Toolkit,
+rem and .NET Framework SDK 1.1 VC++ library paths of your system, in case they
+rem  are not already.
+rem
+
+Set PATH=%VCToolkitInstallDir%\bin;%MSSdk%\Bin;%PATH%
+Set INCLUDE=%VCToolkitInstallDir%\include;%MSSdk%\Include;%INCLUDE%
+rem Set LIB=C:\Program files\Microsoft Visual Studio .NET 2003\Vc7\lib;%VCToolkitInstallDir%\lib;%MSSdk%\Lib;%LIB%
+Set LIB=C:\Programe\Microsoft Visual Studio .NET 2003\Vc7\lib;%VCToolkitInstallDir%\lib;%MSSdk%\Lib;%LIB%
+
+rem Delete the previous builds
+del /S /Q build
+
+rem Build anything.
+python setup.py build install
+
+pause
 Building Pygame2 using Microsoft Visual C++
 -------------------------------------------
+In contrast to the MinGW build (see BuildMinGW.txt), the Microsoft Visual C++
+build will require a bit more ground work before you actually can start to
+make your own pygame2 package.
+
+Setting up Visual C++ and the environment
+-----------------------------------------
+First of all, you have to make sure, that you have at least a Microsoft Visual
+C++ compiler that matches your current Python version. For Python <= 2.5 this
+usually will be the Visual C++ 7.x compiler, shipped with e.g. the
+VC Toolkit 2003 or Visual Studio.NET 2003.
+For later Python releases, Visual Studio.NET 2008 or Visual C++ 2008 Express
+are required. 
+
+NOTE: If you are going to use the VC Toolkit 2003, make sure, you have some
+      proper registry keys set. Otherwise Python's distutils will not be able to
+      detect the settings. Within the util/ directory you can find an example
+      registry key. Change the paths within it according to your system
+      configuration and import it into your registry to allow C Python modules
+      to be built with the VC Toolkit 2003.
+
+Setting up the dependencies
+---------------------------
+NOTE: The following list of dependencies might not be the most actual one.
+      Please check the README.txt file in the top source directory for the
+      most actual dependency list!
+      
+Make sure, you have at least one of the following Python versions installed:
+* Python 2.4, 2.5, 2.6, 3.0 (http://www.python.org)
+
+To build anything, you will have to download the following additional packages:
+
+* SDL >= 1.2.10              (http://www.libsdl.org)
+* SDL_mixer >= 1.2.8         (http://www.libsdl.org/projects/SDL_mixer/)
+* SDL_ttf >= 2.0.9           (http://www.libsdl.org/projects/SDL_ttf/)
+* SDL_image >= 1.2.6         (http://www.libsdl.org/projects/SDL_image/)
+* SDL_gfx >= 2.0.17          (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
+* libpng >= 1.2.24           (http://www.libpng.org)
+      
+The Win32 build chain for Pygame2 does not support building all dependencies
+from scratch. Instead it relies on already built libraries, correctly configured
+settings and matching includes. Thus you will either need  to build them
+yourself or to rely on the offered prebuilt packages.
+
+Once you downloaded and/or built all the dependencies, you have to make sure
+that they can be found by Pygame2's build script. The script will search the
+directory where it resides, the parent directory of it and a directory named
+'prebuilt' for the libraries and headers. If you installed the dependencies
+to different locations, you should change the _searchdirs entry within the
+config/config_win.py script to include the directories.
+
+NOTE: At this point, we strongly recommend a directory named 'prebuilt' that is
+      created under the Pygame2 source directory.
+NOTE: The 'prebuilt' directory should have the following layout:
+      prebuilt\include  -> Contains all header files and header subdirectories
+                           as installed  by the dependencies.
+      prebuilt\lib      -> Contains all library files (both, .dll and .lib)
+                           as installed by the dependencies.
+
+Building Pygame2
+----------------
+If anything you can proceed to build and install Pygame2 itself. Simply type:
+
+    python setup.py build install
+
+This will build and install Pygame2 in one step.
+
+You also can use the small build.bat batch script, which optionally can set up
+the VC++ include and library paths. Change it to your needs and then execute it
+using
+
+    build.bat
+
+This will build and install Pygame2 as above.
 
 Make sure, the C API header does not conflict with another header to be
 installed. Headers used on the module scope only (internally used
-headers) can be named as you like. The C API headers should use the "pyg"
+headers) can be named as you like. The C API headers should use the "pg"
 prefix to avoid naming issues with system or 3rd party library headers.
 
 C API
 If the module has external dependencies, which cannot be guaranteed to
 be available on each platform, add a
 
-    WITH_MOD = False
+    WITH_MOD = istrue (os.getenv ("WITH_MOD", True))
 
 to the cfg.py configuration file so that users can enable/disable the
-module on demand.
+module on demand using the build and environment settings.
 
 Adjust the various config/config_XXX.py files to check for needed dependencies
 of your module and such. As this can vary from platform to platform,

doc/api_template.xml

 <?xml version="1.0" encoding="utf-8" ?>
 
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func | class)*)>
+<!ELEMENT module (short, desc, (func | class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
 
 <!ELEMENT desc (#PCDATA)>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 
 <!ELEMENT func (call, desc)>
      RST/HTML documentation.
 -->
 <module name="NAME">
+  <short>SHORT DESC (single line)</short>
   <desc>DESCRIPTION</desc>
   
     <func name="METHODNAME">
+=============
+Pygame2 C API
+=============
+
+C API:
+
+.. toctree::
+
+

doc/create_cref.py

 
 def prepare_text (text):
     newtext = ""
+    tmptext = ""
     text = text.replace ("\"", "\\\"")
     lines = text.split ("\n")
     for l in lines:
         l = l.strip ().rstrip ("::")
-        newtext += l + "\\n"
-    newtext = newtext.strip ("\\n")
-    if len (newtext) > 2040:
+        if l.startswith ("|"):
+            # Peserve spacings.
+            l = l.replace (":const:", "       ")
+            l = l.replace (":class:", "       ")
+            l = l.replace ("`", " ")
+        else:
+            l = l.replace (":const:", "")
+            l = l.replace (":class:", "")
+            l = l.replace ("`", "")
+        
+        tmptext += l + "\\n"
+    tmptext = tmptext.strip ("\\n")
+    while len (tmptext) > 2040:
         # Split once after 2040 characters to avoid
         # problems with the Visual C++ 2048 character limit
-        newtext = newtext[:2040] + "\"\"" + newtext[2040:]
+        newtext += tmptext[:2040] + "\" \\\n\""
+        tmptext = tmptext[2040:]
+    newtext += tmptext
     return newtext
 
 def create_cref (dom, buf):
     classes = module.getElementsByTagName ("class")
     for cls in classes:
         name = cls.getAttribute ("name").upper ()
-        constructor = cls.getElementsByTagName \
-                      ("constructor")[0].firstChild.nodeValue + "\n"
+        node = cls.getElementsByTagName ("constructor")
+        constructor = "TODO\n"
+        if node and node[0].firstChild:
+            constructor = node[0].firstChild.nodeValue + "\n"
         desc = constructor
         node = cls.getElementsByTagName ("desc")
         if node and node[0].firstChild:

doc/create_rstref.py

     def __init__ (self, filename):
         self.filename = filename
         self.modulename = None
-        self.description = ""
+        self.shortdesc = "TODO"
+        self.description = "TODO"
         self.classes = []
         self.functions = []
     
     def get_module_docs (self, dom):
         module = dom.getElementsByTagName ("module")[0]
         self.modulename = module.getAttribute ("name")
+        node = module.getElementsByTagName ("short")[0]
+        if node.firstChild:
+            self.shortdesc = node.firstChild.nodeValue
         node = module.getElementsByTagName ("desc")[0]
         if node.firstChild:
             self.description = node.firstChild.nodeValue
         functions = module.getElementsByTagName ("func")
         for func in functions:
             name = func.getAttribute ("name")
+            if len (name) == 0:
+                name = "TODO"
             node = func.getElementsByTagName ("call")[0]
             if node.firstChild:
                 call = node.firstChild.nodeValue
             else:
-                call = ""
+                call = "TODO"
             node = func.getElementsByTagName ("desc")[0]
             if node.firstChild:
                 desc = node.firstChild.nodeValue
             else:
-                desc = ""
+                desc = "TODO"
             self.functions.append (DocMethod (None, name, call, desc))
 
     def get_class_refs (self, module):
         classes = module.getElementsByTagName ("class")
         for cls in classes:
             name = cls.getAttribute ("name")
+            if len (name) == 0:
+                name = "TODO"
             node = cls.getElementsByTagName ("constructor")[0]
             if node.firstChild:
                 const = node.firstChild.nodeValue
             else:
-                const = ""
+                const = "TODO"
             node = cls.getElementsByTagName ("desc")[0]
             if node.firstChild:
                 desc = node.firstChild.nodeValue
             else:
-                desc = ""
+                desc = "TODO"
             clsdoc = DocClass (name, const, desc)
 
             attrs = cls.getElementsByTagName ("attr")
 
     def create_attr_ref (self, doccls, attr):
         name = attr.getAttribute ("name")
+        if len (name) == 0:
+            name = "TODO"
         if attr.firstChild:
             desc = attr.firstChild.nodeValue
         else:
-            desc = ""
+            desc = "TODO"
         doccls.attributes.append (DocAttribute (name, desc))
 
     def create_method_ref (self, doccls, method):
         name = method.getAttribute ("name")
+        if len (name) == 0:
+            name = "TODO"
         node = method.getElementsByTagName ("call")[0]
         if node.firstChild:
             call = node.firstChild.nodeValue
         else:
-            call = ""
+            call = "TODO"
         node = method.getElementsByTagName ("desc")[0]
         if node.firstChild:
             desc = node.firstChild.nodeValue
         else:
-            desc = ""
+            desc = "TODO"
         doccls.methods.append (DocMethod (doccls, name, call, desc))
 
-    def create_desc_rst (self, desc, refcache):
+    def create_desc_rst (self, desc, offset=0):
         written = 0
         data = ""
         cindent = indent = 0
                     # We are in a source code block. update the indentation
                     indent = cindent + 1
                     cindent += 1 # Set for following, empty lines.
-
+            
             if written > 0 and line == "":
                 data += "\n"
             elif line != "":
-                data += "\n" + line
+                data += "\n" + " " * offset + line
                 written += 1
         if written == 0:
             return ""
         return data + "\n\n"
     
-    def create_func_rst (self, func, refcache):
-        data = "**%s**\n" % (func.name)
-        data += "*%s*\n" % (func.call)
-        data += "%s\n" % self.create_desc_rst (func.description, refcache)
+    def create_func_rst (self, func):
+        data = ".. function:: %s\n" % func.call
+        data += "%s\n" % self.create_desc_rst (func.description, 2)
         return data
     
-    def create_rst (self, refcache):
+    def create_rst (self):
         fname = os.path.join ("ref", "%s.rst")
         fp = open (fname % self.modulename.replace (".", "_"), "w")
         fp.write (RST_HEADER)
         
-        fp.write ("%s\n" % self.modulename)
-        fp.write ("=" * len (self.modulename) + "\n")
-        fp.write ("%s\n\n" % self.create_desc_rst (self.description, refcache))
+        fp.write (":mod:`%s` -- %s\n" % (self.modulename, self.shortdesc))
+        fp.write ("%s\n" %
+                  ("=" * (11 + len (self.modulename) + len (self.shortdesc))))
+        fp.write ("%s" % self.create_desc_rst (self.description))
+        fp.write (".. module:: %s\n" % (self.modulename))
+        fp.write ("   :synopsis: %s\n\n" % (self.shortdesc))
         
         if len (self.functions) > 0:
-            fp.write ("\n")
             fp.write ("Module functions\n")
             fp.write ("----------------\n")
             for func in self.functions:
-                fp.write (self.create_func_rst (func, refcache))
+                fp.write (self.create_func_rst (func))
 
         if len (self.classes) > 0:
             for cls in self.classes:
                 fp.write (cls.name + "\n")
-                fp.write ("-" * len (cls.name) + "\n")
-                fp.write ("*" + cls.constructor + "*\n")
-                fp.write (self.create_desc_rst (cls.description, refcache))
+                fp.write ("%s\n" % ("-" * len (cls.name)))
+                fp.write (".. class:: %s\n" % cls.constructor)
+                fp.write (self.create_desc_rst (cls.description, 2))
                 if len (cls.attributes) > 0:
                         fp.write ("Attributes\n")
                         fp.write ("^^^^^^^^^^\n")
                         for attr in cls.attributes:
-                            fp.write ("**" + attr.name + "**")
-                            fp.write (self.create_desc_rst (attr.description,
-                                                            refcache))
+                            fp.write (".. attribute:: %s.%s\n"
+                                      % (cls.name, attr.name))
+                            fp.write (self.create_desc_rst (attr.description, 2))
                 if len (cls.methods) > 0:
                     fp.write ("Methods\n")
                     fp.write ("^^^^^^^\n")
                     for method in cls.methods:
-                        fp.write ("**" + method.name + "**\n")
-                        fp.write ("*" + method.call + "*\n")
-                        fp.write (self.create_desc_rst (method.description,
-                                                        refcache))
+                        fp.write (".. method:: %s.%s\n"
+                                  % (cls.name, method.call))
+                        fp.write (self.create_desc_rst (method.description, 2))
         fp.write ("\n")
         fp.write (RST_FOOTER)
         fp.close ()
         
 def create_rst (docs):
-    refcache = {}
     if not os.path.exists ("ref"):
         os.mkdir ("ref")
-
-    for doc in docs:
-        for cls in doc.classes:
-            refcache[cls.name] = doc.filename
-        for func in doc.functions:
-            refcache[func.name] = doc.filename
     for doc in docs:
         print ("Now writing RST for %s...." % doc.modulename)
-        doc.create_rst (refcache)
+        doc.create_rst ()
 
 def get_doc_files ():
     docs = []
    :maxdepth: 2
 
    modules.rst
+   capi.rst
 
 Indices and tables
 ==================
    ref/pygame2_sdl_cdrom
    ref/pygame2_sdl_event
    ref/pygame2_sdl_gl
+   ref/pygame2_sdl_image
    ref/pygame2_sdl_joystick
    ref/pygame2_sdl_keyboard
    ref/pygame2_sdl_mouse
    ref/pygame2_sdlgfx_base
    ref/pygame2_sdlgfx_primitives
    ref/pygame2_sdlgfx_rotozoom
-   ref/pygame2_sdlimage
    ref/pygame2_sdlimage_base
    ref/pygame2_sdlmixer_base
    ref/pygame2_sdlmixer_channel
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.base">
+  <short>basic features used by pygame2</short>
   <desc>Base module for pygame2 that contains features shared and used
   throughout the whole pygame2 package.</desc>
 
   <class name="BufferProxy">
     <constructor>BufferProxy () -> BufferProxy</constructor>
-    <desc>Creates a new, empty BufferProxy.
+    <desc>Creates a new, empty :class:`BufferProxy`.
 
     A buffer interface object that acts as a proxy on classes and attributes
-    not featuring the buffer interface. A BufferProxy usually should be
-    constructed from C code, not Python.</desc>
+    not featuring the buffer interface. A :class:`BufferProxy` usually should
+    be constructed from C code, not Python.</desc>
     <attr name="length">Gets the size of the buffer data in bytes.</attr>
-    <attr name="raw">Gets the raw buffer data as string. The string may contain NUL bytes.</attr>
+    <attr name="raw">
+      Gets the raw buffer data as string. The string may contain NUL bytes.
+    </attr>
     <method name="write">
-      <call>B.write (bufferproxy, buffer, offset) -> None</call>
+      <call>write (buffer, offset) -> None</call>
       <desc>
-        Writes raw data to the BufferProxy.
+        Writes raw data to the :class:`BufferProxy`.
 
-        Writes the raw data from buffer to the BufferProxy object, starting at
-        the specified offset within the BufferProxy.  If the length of the
-        passed buffer exceeds the length of the BufferProxy (reduced by the
-        offset), an IndexError will be raised.
+        Writes the raw data from buffer to the :class:`BufferProxy` object,
+        starting at the specified offset within the :class:`BufferProxy`. If
+        the length of the passed buffer exceeds the length of the
+        :class:`BufferProxy` (reduced by the offset), an :exc:`IndexError` will
+        be raised.
       </desc>
     </method>
   </class>
 
   <class name="Color">
     <constructor>Color (...) ->Color</constructor>
-    <desc>Creates a new Color object.
+    <desc>Creates a new :class:`Color` object.
 
-    The Color class represents RGBA color values using a value range of
+    The :class:`Color` class represents RGBA color values using a value range of
     0-255. It allows basic arithmetic operations to create new colors,
     supports conversions to other color spaces such as HSV or HSL and lets
     you adjust single color channels. The following constructors are supported:
     * Color ("#RRGGBBAA")
     * Color ("name")
     </desc>
-    <attr name="a">Gets or sets the alpha value of the Color.</attr>
-    <attr name="b">Gets or sets the blue value of the Color.</attr>
-    <attr name="cmy">The CMY representation of the Color. The CMY components are in the
-    ranges C = [0, 1], M = [0, 1], Y = [0, 1]. Note that this will not
-    return the absolutely exact CMY values for the set RGB values in all
-    cases. Due to the RGB mapping from 0-255 and the CMY mapping from 0-1
+    <attr name="a">Gets or sets the alpha value of the :class:`Color`.</attr>
+    <attr name="b">Gets or sets the blue value of the :class:`Color`.</attr>
+    <attr name="cmy">The CMY representation of the :class:`Color`. The CMY
+    components are in the ranges C = [0, 1], M = [0, 1], Y = [0, 1]. Note that
+    this will not return the absolutely exact CMY values for the set RGB values
+    in all cases. Due to the RGB mapping from 0-255 and the CMY mapping from 0-1
     rounding errors may cause the CMY values to differ slightly from what
     you might expect.</attr>
     <method name="correct_gamma">
-      <call>Color.correct_gamma (gamma) -> Color</call>
+      <call>correct_gamma (gamma) -> Color</call>
       <desc>
-        Applies a certain gamma value to the Color.
+        Applies a certain gamma value to the :class:`Color`.
 
-        Applies a certain gamma value to the Color and returns a new Color with
-        the adjusted RGBA values.
+        Applies a certain gamma value to the :class:`Color` and returns a new
+        :class:`Color` with the adjusted RGBA values.
       </desc>
     </method>
-    <attr name="g">Gets or sets the green value of the Color.</attr>
-    <attr name="hsla">The HSLA representation of the Color. The HSLA components are in the
-    ranges H = [0, 360], S = [0, 100], L = [0, 100], A = [0, 100]. Note that
-    this will not return the absolutely exact HSL values for the set RGB
-    values in all cases. Due to the RGB mapping from 0-255 and the HSL
-    mapping from 0-100 and 0-360 rounding errors may cause the HSL values to
-    differ slightly from what you might expect.</attr>
-    <attr name="hsva">The HSVA representation of the Color. The HSVA components are in the
-    ranges H = [0, 360], S = [0, 100], V = [0, 100], A = [0, 100]. Note that
-    this will not return the absolutely exact HSV values for the set RGB
-    values in all cases. Due to the RGB mapping from 0-255 and the HSV
-    mapping from 0-100 and 0-360 rounding errors may cause the HSV values to
-    differ slightly from what you might expect.</attr>
-    <attr name="i1i2i3">The I1I2I3 representation of the Color. The I1I2I3 components are in the
-    ranges I1 = [0, 1], I2 = [-0.5, 0.5], I3 = [-0.5, 0.5]. Note that this
-    will not return the absolutely exact I1I2I3 values for the set RGB
-    values in all cases. Due to the RGB mapping from 0-255 and the I1I2I3
-    mapping from 0-1 rounding errors may cause the I1I2I3 values to differ
-    slightly from what you might expect.</attr>
+    <attr name="g">Gets or sets the green value of the :class:`Color`.</attr>
+    <attr name="hsla">The HSLA representation of the :class:`Color`. The HSLA
+    components are in the ranges H = [0, 360], S = [0, 100], L = [0, 100],
+    A = [0, 100]. Note that this will not return the absolutely exact HSL
+    values for the set RGB values in all cases. Due to the RGB mapping from
+    0-255 and the HSL mapping from 0-100 and 0-360 rounding errors may cause
+    the HSL values to differ slightly from what you might expect.</attr>
+    <attr name="hsva">The HSVA representation of the :class:`Color`. The HSVA
+    components are in the ranges H = [0, 360], S = [0, 100], V = [0, 100],
+    A = [0, 100]. Note that this will not return the absolutely exact HSV
+    values for the set RGB values in all cases. Due to the RGB mapping from
+    0-255 and the HSV mapping from 0-100 and 0-360 rounding errors may cause
+    the HSV values todiffer slightly from what you might expect.</attr>
+    <attr name="i1i2i3">The I1I2I3 representation of the :class:`Color`.
+    The I1I2I3 components are in the ranges I1 = [0, 1], I2 = [-0.5, 0.5],
+    I3 = [-0.5, 0.5]. Note that this will not return the absolutely exact
+    I1I2I3 values for the set RGB values in all cases. Due to the RGB mapping
+    from 0-255 and the I1I2I3 from 0-1 rounding errors may cause the I1I2I3
+    values to differ slightly from what you might expect.</attr>
     <method name="normalize">
-      <call>Color.normalize() -> tuple</call>
+      <call>normalize() -> tuple</call>
       <desc>
-        Returns the normalized RGBA values of the Color.
+        Returns the normalized RGBA values of the :class:`Color`.
 
-        Returns the normalized RGBA values of the Color as floating point
-        values.
+        Returns the normalized RGBA values of the :class:`Color` as floating
+        point values.
       </desc>
     </method>
-    <attr name="r">Gets or sets the red value of the Color.</attr>
+    <attr name="r">Gets or sets the red value of the :class:`Color`.</attr>
   </class>
 
   <class name="Error">
 
   <class name="FRect">
     <constructor>FRect (...) -> FRect</constructor>
-    <desc>A class for storing rectangular coordinates.
+    <desc>
+      A class for storing rectangular coordinates.
 
-    A FRect is used to store and manipulate rectangular coordinates.  TODO</desc>
-    <attr name="bottom">Gets or sets the bottom edge position of the FRect.</attr>
-    <attr name="bottomleft">Gets or sets the bottom left corner position of the FRect.</attr>
-    <attr name="bottomright">Gets or sets the bottom right corner position of the FRect.</attr>
+      A :class:`FRect` is used to store and manipulate rectangular coordinates.
+      TODO
+    </desc>
+    <attr name="bottom">Gets or sets the bottom edge position of the :class:`FRect`.</attr>
+    <attr name="bottomleft">Gets or sets the bottom left corner position of the :class:`FRect`.</attr>
+    <attr name="bottomright">Gets or sets the bottom right corner position of the :class:`FRect`.</attr>
     <method name="ceil">
-      <call>FRect.ceil () -> Rect</call>
+      <call>ceil () -> Rect</call>
       <desc>
-        Creates a Rect from the specified FRect.
+        Creates a :class:`Rect` from the specified :class:`FRect`.
 
-        This creates a Rect using the smallest integral values greater
-        or equal to the FRect floating point values.
+        This creates a :class:`Rect` using the smallest integral values greater
+        or equal to the :class:`FRect` floating point values.
       </desc>
     </method>
-    <attr name="center">Gets or sets the center position of the FRect.</attr>
-    <attr name="centerx">Gets or sets the horizontal center position of the FRect.</attr>
-    <attr name="centery">Gets or sets the vertical center position of the FRect.</attr>
+    <attr name="center">Gets or sets the center position of the :class:`FRect`.</attr>
+    <attr name="centerx">Gets or sets the horizontal center position of the :class:`FRect`.</attr>
+    <attr name="centery">Gets or sets the vertical center position of the :class:`FRect`.</attr>
     <method name="clamp">
-      <call>FRect.clamp (FRect) -> FRect</call>
+      <call>clamp (FRect) -> FRect</call>
       <desc>
         Moves the rectangle inside another.
 
         Returns a new rectangle that is moved to be completely inside
-        the argument FRect. If the rectangle is too large to fit inside,
-        it is centered inside the argument FRect, but its size is not
+        the argument :class:`FRect`. If the rectangle is too large to fit inside,
+        it is centered inside the argument :class:`FRect`, but its size is not
         changed.
       </desc>
     </method>
     <method name="clamp_ip">
-      <call>FRect.clamp_ip (FRect) -> None</call>
+      <call>clamp_ip (FRect) -> None</call>
       <desc>
         Moves the rectangle inside another, in place.
 
       </desc>
     </method>
     <method name="clip">
-      <call>FRect.clip (FRect) -> FRect</call>
+      <call>clip (FRect) -> FRect</call>
       <desc>
         Crops a rectangle inside another.
 
         Returns a new rectangle that is cropped to be completely inside
-        the argument FRect. If the two rectangles do not overlap to begin
-        with, a FRect with 0 size is returned. Thus it returns the area, in
+        the argument :class:`FRect`. If the two rectangles do not overlap to begin
+        with, a :class:`FRect` with 0 size is returned. Thus it returns the area, in
         which both rects overlap.
       </desc>
     </method>
     <method name="collidedict">
-      <call>FRect.collidedict (dict) -> (key, value)</call>
+      <call>collidedict (dict) -> (key, value)</call>
       <desc>
         Test if one rectangle in a dictionary intersects.
 
         Returns the key and value of the first dictionary value that
-        collides with the FRect. If no collisions are found, None is
-        returned. They keys of the passed dict must be FRect objects.
+        collides with the :class:`FRect`. If no collisions are found, None is
+        returned. They keys of the passed dict must be :class:`FRect` objects.
       </desc>
     </method>
     <method name="collidedictall">
-      <call>FRect.collidedictall (dict) -> [(key, value), ...]</call>
+      <call>collidedictall (dict) -> [(key, value), ...]</call>
       <desc>
         Test if all rectangles in a dictionary intersect.
 
         Returns a list of all the key and value pairs that intersect
-        with the FRect. If no collisions are found an empty list is
-        returned. They keys of the passed dict must be FRect objects.
+        with the :class:`FRect`. If no collisions are found an empty list is
+        returned. They keys of the passed dict must be :class:`FRect` objects.
       </desc>
     </method>
     <method name="collidelist">
-      <call>FRect.collidelist (list) -> index</call>
+      <call>collidelist (list) -> index</call>
       <desc>
         Test if one rectangle in a list intersects.
 
       </desc>
     </method>
     <method name="collidelistall">
-      <call>FRect.collidelistall (list) -> [index, ...]</call>
+      <call>collidelistall (list) -> [index, ...]</call>
       <desc>
         Test if all rectangles in a list intersect.
 
         Returns a list of all the indices that contain rectangles that
-        collide with the FRect. If no intersecting rectangles are found,
+        collide with the :class:`FRect`. If no intersecting rectangles are found,
         an empty list is returned.
       </desc>
     </method>
     <method name="collidepoint">
-      <call>FRect.collidepoint (x, y) -> bool</call>
+      <call>collidepoint (x, y) -> bool</call>
       <desc>
         Test if a point is inside a rectangle.
 
       </desc>
     </method>
     <method name="colliderect">
-      <call>FRect.colliderect (FRect) -> bool</call>
+      <call>colliderect (FRect) -> bool</call>
       <desc>
         Test if two rectangles overlap.
 
       </desc>
     </method>
     <method name="contains">
-      <call>FRect.contains (FRect) -> bool</call>
+      <call>contains (FRect) -> bool</call>
       <desc>
         Test if one rectangle is inside another.
 
         Returns true when the argument rectangle is completely inside
-        the FRect.
+        the :class:`FRect`.
       </desc>
     </method>
     <method name="fit">
-      <call>FRect.fit (FRect) -> FRect</call>
+      <call>fit (FRect) -> FRect</call>
       <desc>
         Resize and move a rectangle with aspect ratio.
 
         Returns a new rectangle that is moved and resized to fit
-        another. The aspect ratio of the original FRect is preserved, so
+        another. The aspect ratio of the original :class:`FRect` is preserved, so
         the new rectangle may be smaller than the target in either width
         or height.
       </desc>
     </method>
     <method name="floor">
-      <call>FRect.floor () -> Rect</call>
+      <call>floor () -> Rect</call>
       <desc>
-        Creates a Rect from the specified FRect.
+        Creates a :class:`Rect` from the specified :class:`FRect`.
 
-        This creates a Rect using the largest integral values less than
-        or equal to the FRect floating point values.
+        This creates a :class:`Rect` using the largest integral values less than
+        or equal to the :class:`FRect` floating point values.
       </desc>
     </method>
-    <attr name="height">Gets or sets the height of the FRect.</attr>
+    <attr name="height">Gets or sets the height of the :class:`FRect`.</attr>
     <method name="inflate">
-      <call>FRect.inflate (x, y) -> FRect</call>
+      <call>inflate (x, y) -> FRect</call>
       <desc>
         Grow or shrink the rectangle size.
 
       </desc>
     </method>
     <method name="inflate_ip">
-      <call>FRect.inflate_ip (x, y) -> None</call>
+      <call>inflate_ip (x, y) -> None</call>
       <desc>
         Grow or shrink the rectangle size, in place.
 
         Same as FRect.inflate(x, y), but operates in place.
       </desc>
     </method>
-    <attr name="left">Gets or sets the left edge position of the FRect.</attr>
-    <attr name="midbottom">Gets or sets the mid bottom edge position of the FRect.</attr>
-    <attr name="midleft">Gets or sets the mid left edge position of the FRect.</attr>
-    <attr name="midright">Gets or sets the mid right edge position of the FRect.</attr>
-    <attr name="midtop">Gets or sets the mid top edge position of the FRect.</attr>
+    <attr name="left">Gets or sets the left edge position of the :class:`FRect`.</attr>
+    <attr name="midbottom">Gets or sets the mid bottom edge position of the :class:`FRect`.</attr>
+    <attr name="midleft">Gets or sets the mid left edge position of the :class:`FRect`.</attr>
+    <attr name="midright">Gets or sets the mid right edge position of the :class:`FRect`.</attr>
+    <attr name="midtop">Gets or sets the mid top edge position of the :class:`FRect`.</attr>
     <method name="move">
-      <call>FRect.move (x, y) -> FRect</call>
+      <call>move (x, y) -> FRect</call>
       <desc>
         Moves the rectangle.
 
       </desc>
     </method>
     <method name="move_ip">
-      <call>FRect.move_ip (x, y) -> None</call>
+      <call>move_ip (x, y) -> None</call>
       <desc>
         Moves the rectangle, in place.
 
         Same as FRect.move (x, y), but operates in place.
       </desc>
     </method>
-    <attr name="right">Gets or sets the right position of the FRect.</attr>
+    <attr name="right">Gets or sets the right position of the :class:`FRect`.</attr>
     <method name="round">
-      <call>FRect.round () -> Rect</call>
+      <call>round () -> Rect</call>
       <desc>
-        Creates a Rect from the specified FRect.
+        Creates a :class:`Rect` from the specified :class:`FRect`.
 
-        This creates a Rect using the FRect floating point values
+        This creates a :class:`Rect` using the :class:`FRect` floating point values
         rounded to the nearest integral value.
       </desc>
     </method>
-    <attr name="size">Gets or sets the width and height of the FRect as 2-value tuple.</attr>
-    <attr name="top">Gets or sets the top edge position of the FRect.</attr>
-    <attr name="topleft">Gets or sets the top left corner position of the FRect.</attr>
-    <attr name="topright">Gets or sets the top right corner position of the FRect.</attr>
+    <attr name="size">Gets or sets the width and height of the :class:`FRect` as 2-value tuple.</attr>
+    <attr name="top">Gets or sets the top edge position of the :class:`FRect`.</attr>
+    <attr name="topleft">Gets or sets the top left corner position of the :class:`FRect`.</attr>
+    <attr name="topright">Gets or sets the top right corner position of the :class:`FRect`.</attr>
     <method name="trunc">
-      <call>FRect.trunc () -> Rect</call>
+      <call>trunc () -> Rect</call>
       <desc>
-        Creates a Rect from the specified FRect.
+        Creates a :class:`Rect` from the specified :class:`FRect`.
 
-        This creates a Rect using truncated integral values from the
-        Frect floating point values.
+        This creates a :class:`Rect` using truncated integral values from the
+        :class:`FRect` floating point values.
       </desc>
     </method>
     <method name="union">
-      <call>FRect.union (FRect) -> FRect</call>
+      <call>union (FRect) -> FRect</call>
       <desc>
         Joins two rectangles into one.
 
         Returns a new rectangle that completely covers the area of the
-        two provided rectangles. There may be area inside the new FRect
+        two provided rectangles. There may be area inside the new :class:`FRect`
         that is not covered by the originals.
       </desc>
     </method>
     <method name="union_ip">
-      <call>FRect.union_ip (FRect) -> FRect</call>
+      <call>union_ip (FRect) -> FRect</call>
       <desc>
         Joins two rectangles into one, in place.
 
         Same as FRect.union(FRect), but operates in place.
       </desc>
     </method>
-    <attr name="width">Gets or sets the width of the FRect.</attr>
-    <attr name="x">Gets or sets the horizontal top left position of the FRect.</attr>
-    <attr name="y">Gets or sets the vertical top left position of the FRect.</attr>
+    <attr name="width">Gets or sets the width of the :class:`FRect`.</attr>
+    <attr name="x">Gets or sets the horizontal top left position of the :class:`FRect`.</attr>
+    <attr name="y">Gets or sets the vertical top left position of the :class:`FRect`.</attr>
   </class>
 
   <class name="Rect">
     <constructor>Rect (...) -> Rect</constructor>
     <desc>A class for storing rectangular coordinates.
 
-    A Rect is used to store and manipulate rectangular coordinates.  TODO</desc>
-    <attr name="bottom">Gets or sets the bottom edge position of the Rect.</attr>
-    <attr name="bottomleft">Gets or sets the bottom left corner position of the Rect.</attr>
-    <attr name="bottomright">Gets or sets the bottom right corner position of the Rect.</attr>
-    <attr name="center">Gets or sets the center position of the Rect.</attr>
-    <attr name="centerx">Gets or sets the horizontal center position of the Rect.</attr>
-    <attr name="centery">Gets or sets the vertical center position of the Rect.</attr>
+    A :class:`Rect` is used to store and manipulate rectangular coordinates.  TODO</desc>
+    <attr name="bottom">Gets or sets the bottom edge position of the :class:`Rect`.</attr>
+    <attr name="bottomleft">Gets or sets the bottom left corner position of the :class:`Rect`.</attr>
+    <attr name="bottomright">Gets or sets the bottom right corner position of the :class:`Rect`.</attr>
+    <attr name="center">Gets or sets the center position of the :class:`Rect`.</attr>
+    <attr name="centerx">Gets or sets the horizontal center position of the :class:`Rect`.</attr>
+    <attr name="centery">Gets or sets the vertical center position of the :class:`Rect`.</attr>
     <method name="clamp">
-      <call>Rect.clamp (Rect) -> Rect</call>
+      <call>clamp (Rect) -> Rect</call>
       <desc>
         Moves the rectangle inside another.
 
         Returns a new rectangle that is moved to be completely inside
-        the argument Rect. If the rectangle is too large to fit inside,
-        it is centered inside the argument Rect, but its size is not
+        the argument :class:`Rect`. If the rectangle is too large to fit inside,
+        it is centered inside the argument :class:`Rect`, but its size is not
         changed.
       </desc>
     </method>
     <method name="clamp_ip">
-      <call>Rect.clamp_ip (Rect) -> None</call>
+      <call>clamp_ip (Rect) -> None</call>
       <desc>
         Moves the rectangle inside another, in place.
 
       </desc>
     </method>
     <method name="clip">
-      <call>Rect.clip (Rect) -> Rect</call>
+      <call>clip (Rect) -> Rect</call>
       <desc>
         Crops a rectangle inside another.
 
         Returns a new rectangle that is cropped to be completely inside
-        the argument Rect. If the two rectangles do not overlap to begin
-        with, a Rect with 0 size is returned. Thus it returns the area, in
+        the argument :class:`Rect`. If the two rectangles do not overlap to begin
+        with, a :class:`Rect` with 0 size is returned. Thus it returns the area, in
         which both rects overlap.
       </desc>
     </method>
     <method name="collidedict">
-      <call>Rect.collidedict (dict) -> (key, value)</call>
+      <call>collidedict (dict) -> (key, value)</call>
       <desc>
         Test if one rectangle in a dictionary intersects.
 
         Returns the key and value of the first dictionary value that
-        collides with the Rect. If no collisions are found, None is
-        returned. They keys of the passed dict must be Rect objects.
+        collides with the :class:`Rect`. If no collisions are found, None is
+        returned. They keys of the passed dict must be :class:`Rect` objects.
       </desc>
     </method>
     <method name="collidedictall">
-      <call>Rect.collidedictall (dict) -> [(key, value), ...]</call>
+      <call>collidedictall (dict) -> [(key, value), ...]</call>
       <desc>
         Test if all rectangles in a dictionary intersect.
 
         Returns a list of all the key and value pairs that intersect
-        with the Rect. If no collisions are found an empty list is
-        returned. They keys of the passed dict must be Rect objects.
+        with the :class:`Rect`. If no collisions are found an empty list is
+        returned. They keys of the passed dict must be :class:`Rect` objects.
       </desc>
     </method>
     <method name="collidelist">
-      <call>Rect.collidelist (list) -> index</call>
+      <call>collidelist (list) -> index</call>
       <desc>
         Test if one rectangle in a list intersects.
 
       </desc>
     </method>
     <method name="collidelistall">
-      <call>Rect.collidelistall (list) -> [index, ...]</call>
+      <call>collidelistall (list) -> [index, ...]</call>
       <desc>
         Test if all rectangles in a list intersect.
 
         Returns a list of all the indices that contain rectangles that
-        collide with the Rect. If no intersecting rectangles are found,
+        collide with the :class:`Rect`. If no intersecting rectangles are found,
         an empty list is returned.
       </desc>
     </method>
     <method name="collidepoint">
-      <call>Rect.collidepoint (x, y) -> bool</call>
+      <call>collidepoint (x, y) -> bool</call>
       <desc>
         Test if a point is inside a rectangle.
 
       </desc>
     </method>
     <method name="colliderect">
-      <call>Rect.colliderect (Rect) -> bool</call>
+      <call>colliderect (Rect) -> bool</call>
       <desc>
         Test if two rectangles overlap.
 
       </desc>
     </method>
     <method name="contains">
-      <call>Rect.contains (Rect) -> bool</call>
+      <call>contains (Rect) -> bool</call>
       <desc>
         Test if one rectangle is inside another.
 
         Returns true when the argument rectangle is completely inside
-        the Rect.
+        the :class:`Rect`.
       </desc>
     </method>
     <method name="fit">
-      <call>Rect.fit (Rect) -> Rect</call>
+      <call>fit (Rect) -> Rect</call>
       <desc>
         Resize and move a rectangle with aspect ratio.
 
         Returns a new rectangle that is moved and resized to fit
-        another. The aspect ratio of the original Rect is preserved, so
+        another. The aspect ratio of the original :class:`Rect` is preserved, so
         the new rectangle may be smaller than the target in either width
         or height.
       </desc>
     </method>
-    <attr name="height">Gets or sets the height of the Rect.</attr>
+    <attr name="height">Gets or sets the height of the :class:`Rect`.</attr>
     <method name="inflate">
-      <call>Rect.inflate (x, y) -> Rect</call>
+      <call>inflate (x, y) -> Rect</call>
       <desc>
         Grow or shrink the rectangle size.
 
       </desc>
     </method>
     <method name="inflate_ip">
-      <call>Rect.inflate_ip (x, y) -> None</call>
+      <call>inflate_ip (x, y) -> None</call>
       <desc>
         Grow or shrink the rectangle size, in place.
 
         Same as Rect.inflate(x, y), but operates in place.
       </desc>
     </method>
-    <attr name="left">Gets or sets the left edge position of the Rect.</attr>
-    <attr name="midbottom">Gets or sets the mid bottom edge position of the Rect.</attr>
-    <attr name="midleft">Gets or sets the mid left edge position of the Rect.</attr>
-    <attr name="midright">Gets or sets the mid right edge position of the Rect.</attr>
-    <attr name="midtop">Gets or sets the mid top edge position of the Rect.</attr>
+    <attr name="left">Gets or sets the left edge position of the :class:`Rect`.</attr>
+    <attr name="midbottom">Gets or sets the mid bottom edge position of the :class:`Rect`.</attr>
+    <attr name="midleft">Gets or sets the mid left edge position of the :class:`Rect`.</attr>
+    <attr name="midright">Gets or sets the mid right edge position of the :class:`Rect`.</attr>
+    <attr name="midtop">Gets or sets the mid top edge position of the :class:`Rect`.</attr>
     <method name="move">
-      <call>Rect.move (x, y) -> Rect</call>
+      <call>move (x, y) -> Rect</call>
       <desc>
         Moves the rectangle.
 
       </desc>
     </method>
     <method name="move_ip">
-      <call>Rect.move_ip (x, y) -> None</call>
+      <call>move_ip (x, y) -> None</call>
       <desc>
         Moves the rectangle, in place.
 
         Same as Rect.move (x, y), but operates in place.
       </desc>
     </method>
-    <attr name="right">Gets or sets the right position of the Rect.</attr>
-    <attr name="size">Gets or sets the width and height of the Rect as 2-value tuple.</attr>
-    <attr name="top">Gets or sets the top edge position of the Rect.</attr>
-    <attr name="topleft">Gets or sets the top left corner position of the Rect.</attr>
-    <attr name="topright">Gets or sets the top right corner position of the Rect.</attr>
+    <attr name="right">Gets or sets the right position of the :class:`Rect`.</attr>
+    <attr name="size">Gets or sets the width and height of the :class:`Rect` as 2-value tuple.</attr>
+    <attr name="top">Gets or sets the top edge position of the :class:`Rect`.</attr>
+    <attr name="topleft">Gets or sets the top left corner position of the :class:`Rect`.</attr>
+    <attr name="topright">Gets or sets the top right corner position of the :class:`Rect`.</attr>
     <method name="union">
-      <call>Rect.union (Rect) -> Rect</call>
+      <call>union (Rect) -> Rect</call>
       <desc>
         Joins two rectangles into one.
 
         Returns a new rectangle that completely covers the area of the
-        two provided rectangles. There may be area inside the new Rect
+        two provided rectangles. There may be area inside the new :class:`Rect`
         that is not covered by the originals.
       </desc>
     </method>
     <method name="union_ip">
-      <call>Rect.union_ip (Rect) -> Rect</call>
+      <call>union_ip (Rect) -> Rect</call>
       <desc>
         Joins two rectangles into one, in place.
 
         Same as Rect.union(Rect), but operates in place.
       </desc>
     </method>
-    <attr name="width">Gets or sets the width of the Rect.</attr>
-    <attr name="x">Gets or sets the horizontal top left position of the Rect.</attr>
-    <attr name="y">Gets or sets the vertical top left position of the Rect.</attr>
+    <attr name="width">Gets or sets the width of the :class:`Rect`.</attr>
+    <attr name="x">Gets or sets the horizontal top left position of the :class:`Rect`.</attr>
+    <attr name="y">Gets or sets the vertical top left position of the :class:`Rect`.</attr>
   </class>
 
 </module>
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.mask">
+  <short>image masks for fast pixel-perfect overlap checks</short>
   <desc>
     A module for image masks, suitable for fast pixel-perfect collision
     detections.
 
   <class name="Mask">
     <constructor>Mask (width, height) -> Mask</constructor>
-    <desc>Creates a new Mask object with the specified width and height</desc>
+    <desc>Creates a new :class:`Mask` object with the specified width and height</desc>
     <attr name="angle">
       Gets the orientation of the pixels. Finds the approximate orientation of
       the pixels in the image from -90 to 90 degrees. This works best if
       performed on one connected component of pixels. It will return 0.0 on an
-      empty Mask.
+      empty :class:`Mask`.
     </attr>
     <attr name="centroid">
-      Gets the centroid, the center of pixel mass, of the pixels in a Mask.
-      Returns a coordinate tuple for the centroid of the Mask. if the Mask is
+      Gets the centroid, the center of pixel mass, of the pixels in a :class:`Mask`.
+      Returns a coordinate tuple for the centroid of the :class:`Mask`. if the :class:`Mask` is
       empty, it will return (0,0).
     </attr>
     <method name="clear">
-      <call>Mask.clear () -> None</call>
+      <call>clear () -> None</call>
       <desc>
-        Clears all bits in the Mask.
+        Clears all bits in the :class:`Mask`.
 
-        Resets the state of all bits in the Mask to 0.
+        Resets the state of all bits in the :class:`Mask` to 0.
       </desc>
     </method>
     <method name="connected_component">
-      <call>Mask.connected_component (x=None, y=None) -> Mask</call>
+      <call>connected_component (x=None, y=None) -> Mask</call>
       <desc>
-        Returns a Mask of a connected region of pixels.
+        Returns a :class:`Mask` of a connected region of pixels.
 
         This uses the SAUF algorithm to find a connected component in
-        the Mask. It checks 8 point connectivity. By default, it will
+        the :class:`Mask`. It checks 8 point connectivity. By default, it will
         return the largest connected component in the image. Optionally,
         a coordinate pair of a pixel can be specified, and the connected
         component containing it will be returned. In the event the pixel
-        at that location is not set, the returned Mask will be
-        empty. The Mask returned is the same size as the original Mask.
+        at that location is not set, the returned :class:`Mask` will be
+        empty. The :class:`Mask` returned is the same size as the original :class:`Mask`.
       </desc>
     </method>
     <method name="connected_components">
-      <call>Mask.connected_component (x=None, y=None) -> Mask</call>
+      <call>connected_component (x=None, y=None) -> Mask</call>
       <desc>
-        Returns a Mask of a connected region of pixels.
+        Returns a :class:`Mask` of a connected region of pixels.
 
         This uses the SAUF algorithm to find a connected component in
-        the Mask. It checks 8 point connectivity. By default, it will
+        the :class:`Mask`. It checks 8 point connectivity. By default, it will
         return the largest connected component in the image. Optionally,
         a coordinate pair of a pixel can be specified, and the connected
         component containing it will be returned. In the event the pixel
-        at that location is not set, the returned Mask will be
-        empty. The Mask returned is the same size as the original Mask.
+        at that location is not set, the returned :class:`Mask` will be
+        empty. The :class:`Mask` returned is the same size as the original :class:`Mask`.
       </desc>
     </method>
-    <attr name="count">Gets the amount of bits in the Mask.</attr>
+    <attr name="count">Gets the amount of bits in the :class:`Mask`.</attr>
     <method name="draw">
-      <call>Mask.draw (mask, x, y) -> None</call>
+      <call>draw (mask, x, y) -> None</call>
       <desc>
-        Draws the passed Mask onto the Mask.
+        Draws the passed :class:`Mask` onto the :class:`Mask`.
         
-        This performs a bitwise OR operation upon the calling Mask. The
+        This performs a bitwise OR operation upon the calling :class:`Mask`. The
         passed mask's start offset for the draw operation will be the x and
         y offset passed to the method.
       </desc>
     </method>
     <method name="erase">
-      <call>Mask.erase (mask, x, y) -> None</call>
+      <call>erase (mask, x, y) -> None</call>
       <desc>
-        Erases the passed Mask from the Mask.
+        Erases the passed :class:`Mask` from the :class:`Mask`.
 
-        This performs a bitwise NAND operation upon the calling Mask. The
+        This performs a bitwise NAND operation upon the calling :class:`Mask`. The
         passed mask's start offfset for the erase operation will be the x and
         y offset passed to the method.
       </desc>
     </method>
     <method name="fill">
-      <call>Mask.fill () -> None</call>
+      <call>fill () -> None</call>
       <desc>
-        Sets all bits to 1 within the Mask.
+        Sets all bits to 1 within the :class:`Mask`.
       </desc>
     </method>
     <method name="get_at">
-      <call>Mask.get_at (x, y) -> int</call>
+      <call>get_at (x, y) -> int</call>
       <desc>
         Gets the bit value at the desired location.
       </desc>
     </method>
     <method name="get_bounding_rects">
-      <call>Mask.get_bounding_rects () -> [Mask, Mask ...]</call>
+      <call>get_bounding_rects () -> [Mask, Mask ...]</call>
       <desc>
         Returns a list of bounding rects of regions of set pixels.
 
         rect is one for which each of the connected pixels is inside the rect.
       </desc>
     </method>
-    <attr name="height">Gets the height of the Mask.</attr>
+    <attr name="height">Gets the height of the :class:`Mask`.</attr>
     <method name="invert">
-      <call>Mask.invert () -> None</call>
+      <call>invert () -> None</call>
       <desc>
-        Inverts all bits in the Mask.
+        Inverts all bits in the :class:`Mask`.
       </desc>
     </method>
     <method name="outline">
       <desc>TODO</desc>
     </method>
     <method name="overlap">
-      <call>Mask.overlap (mask, x, y) -> int, int</call>
+      <call>overlap (mask, x, y) -> int, int</call>
       <desc>
         Returns nonzero if the masks overlap with the given offset.
 
       </desc>
     </method>
     <method name="overlap_area">
-      <call>Mask.overlap_area (mask, x, y) -> int</call>
+      <call>overlap_area (mask, x, y) -> int</call>
       <desc>
         Returns the number of overlapping bits of two Masks.
 
       </desc>
     </method>
     <method name="overlap_mask">
-      <call>Mask.overlap_mask (mask, x, y) -> Mask.</call>
+      <call>overlap_mask (mask, x, y) -> Mask.</call>
       <desc>
         Returns a mask with the overlap of two other masks. A bitwise AND.
       </desc>
     </method>
     <method name="scale">
-      <call>Mask.scale (width, height) -> Mask</call>
+      <call>scale (width, height) -> Mask</call>
       <desc>
-        Creates a new scaled Mask with the given width and height.
+        Creates a new scaled :class:`Mask` with the given width and height.
 
         The quality of the scaling may not be perfect for all circumstances,
         but it should be reasonable. If either w or h is 0 a clear 1x1 mask is
       </desc>
     </method>
     <method name="set_at">
-      <call>Mask.set_at (x, y) -> None</call>
+      <call>set_at (x, y) -> None</call>
       <desc>
         Sets the bit value at the desired location.
       </desc>
     </method>
-    <attr name="size">Gets the width and height of the Mask as tuple.</attr>
-    <attr name="width">Gets the width of the Mask</attr>
+    <attr name="size">Gets the width and height of the :class:`Mask` as tuple.</attr>
+    <attr name="width">Gets the width of the :class:`Mask`</attr>
   </class>
 
   <func name="from_surface">
     <call>from_surface (surface, threshold) -> Mask</call>
     <desc>
-      Returns a Mask from the given pygame2.sdl.video.Surface.
+      Returns a :class:`Mask` from the given pygame2.sdl.video.Surface.
 
       Makes the transparent parts of the Surface not set, and the opaque parts
       set. The alpha of each pixel is checked to see if it is greater than the

doc/src/physics.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.physics">
+  <short>2D physics system</short>
   <desc>None</desc>
 
   <class name="Body">

doc/src/sdlaudio.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.audio">
+  <short>SDL audio subsystem wrapper</short>
   <desc>Pygame SDL audio subsystem wrapper module.</desc>
 
   <func name="init">

doc/src/sdlbase.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.base">
+  <short>basic SDL wrapper module</short>
   <desc>Pygame SDL wrapper module</desc>
 
   <func name="get_compiled_version">
   <func name="get_error">
     <call>get_error () -> pygame2.Error</call>
     <desc>
-      Gets the last pygame2 error occured.
+      Gets the last :exc:`pygame2.base.Error` occured.
 
       SDL maintains an internal error message. This message will usually
-      be given to you when a pygame2.Error is raised. You will rarely
+      be given to you when a :exc:`pygame2.base.Error` is raised. You will rarely
       need to call this function.
     </desc>
   </func>

doc/src/sdlcdrom.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.cdrom">
+  <short>SDL CD-ROM management wrapper</short>
   <desc>
     The cdrom module manages the CD and DVD drives on a computer. It can
     also control the playback of audio cd's.

doc/src/sdlevent.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.event">
+  <short>SDL event wrapper</short>
   <desc>
     Pygame SDL event wrapper module. The event module manages the SDL
     related event system and allows one to receive, send and manipulate
       Creates a new event to be used in the event messaging system.
       
       The type can be one of the valid SDL event type constants. Each
-      event carries a certain set of atttributes, which are only
-      available for that event within the event object. Those are
+      event carries a certain set of attributes, which are only
+      available for that event within the event object.
       
-        * ACTIVEEVENT       state, gain
-        * KEYDOWN           state, scancode, sym, key, mod, unicode
-        * KEYUP             state, scancode, sym, key, mod, unicode
-        * MOUSEMOTION       state, x, y, xrel, yrel, pos, rel, buttons
-        * MOUSEBUTTONDOWN   state, x, y, pos, button
-        * MOUSEBUTTONUP     state, x, y, pos, button
-        * JOYAXISMOTION     which, joy, axis, value
-        * JOYBALLMOTION     which, joy, ball, xrel, yrel, rel
-        * JOYHATMOTION      which, joy, hat, value
-        * JOYBUTTONDOWN     which, joy, button, state
-        * JOYBUTTONUP       which, joy, button, state
-        * VIDEORESIZE       w, h, size
-        * VIDEOEXPOSE       [no attributes]
-        * QUIT              [no attributes]
+      +--------------------------+-------------------------------------------+
+      | Event type               | Attributes                                |
+      +==========================+===========================================+
+      | :const:`ACTIVEEVENT`     | `state`, `gain`                           |
+      +--------------------------+-------------------------------------------+
+      | :const:`KEYDOWN`         | `state`, `scancode`, `sym`, `key`, `mod`, |
+      |                          | `unicode`                                 |
+      +--------------------------+-------------------------------------------+
+      | :const:`KEYUP`           | `state`, `scancode`, `sym`, `key`, `mod`, |
+      |                          | `unicode`                                 |
+      +--------------------------+-------------------------------------------+
+      | :const:`MOUSEMOTION`     | `state`, `x`, `y`, `xrel`, `yrel`, `pos`, |
+      |                          | `rel`, `buttons`                          |
+      +--------------------------+-------------------------------------------+
+      | :const:`MOUSEBUTTONDOWN` | `state`, `x`, `y`, `pos`, `button`        |
+      +--------------------------+-------------------------------------------+
+      | :const:`MOUSEBUTTONUP`   | `state`, `x`, `y`, `pos`, `button`        |
+      +--------------------------+-------------------------------------------+
+      | :const:`JOYAXISMOTION`   | `which`, `joy`, `axis`, `value`           |
+      +--------------------------+-------------------------------------------+
+      | :const:`JOYBALLMOTION`   | `which`, `joy`, `ball`, `xrel`, `yrel`,   |
+      |                          | `rel`                                     |
+      +--------------------------+-------------------------------------------+
+      | :const:`JOYHATMOTION`    | `which`, `joy`, `hat`, `value`            |
+      +--------------------------+-------------------------------------------+
+      | :const:`JOYBUTTONDOWN`   | `which`, `joy`, `button`, `state`         |
+      +--------------------------+-------------------------------------------+
+      | :const:`JOYBUTTONUP`     | `which`, `joy`, `button`, `state`         |
+      +--------------------------+-------------------------------------------+
+      | :const:`VIDEORESIZE`     |  `w`, `h`, `size`                         | 
+      +--------------------------+-------------------------------------------+
+      | :const:`VIDEOEXPOSE`     | no attributes                             |
+      +--------------------------+-------------------------------------------+
+      | :const:`QUIT`            | no attributes                             |
+      +--------------------------+-------------------------------------------+
 
       Some events have special or system-dependent attributes.
       
-        * SYSWMEVENT        hwnd, msg, wparam, lparam [for Windows]
-        * SYSWMEVENT        event                     [for X11]
-        * SYSWMEVENT        [no attributes]           [for others]
+      +---------------------+-------------------------------------------------+
+      | Event type          | Attributes                                      |
+      +=====================+=================================================+
+      | :const:`SYSWMEVENT` | | `hwnd`, `msg`, `wparam`, `lparam` for Windows |
+      |                     | | `event`                           for X11     |
+      |                     | | no attributes                     for others  |
+      +---------------------+-------------------------------------------------+
       
-      For user-defiend events, there is the special USEREVENT type (and
+      For user-defiend events, there is the special :const:`USEREVENT` type (and
       above). User-defined events can carry their own type, which must
-      be in the range [USEREVENT, (NUMEVENTS - 1)]. If they are sent
-      from pygame code directly, they do not carry specific attributes,
+      be in the range [:const:`USEREVENT`, (:const:`NUMEVENTS` - 1)]. If they
+      are sent from pygame code directly, they do not carry specific attributes,
       just those given to them by the passed dictionary.
 
       If they come from another system (e.g. 3rd party library), they
       might carry the following attributes:
 
-        * USEREVENT         code, data1, data2
+      +--------------------+--------------------------+
+      | Event type         | Attributes               |
+      +====================+==========================+
+      | :const:`USEREVENT` | `code`, `data1`, `data2` |
+      +--------------------+--------------------------+
     </desc>
     <attr name="name">Gets the name of the Event.</attr>
     <attr name="type">Gets type id of the Event.</attr>
       Clears the event queue from certain event types. If no argument is
       passed, all current events are removed from the queue. Otherwise
       the argument can be a sequence or a bitmask combination of event
-      types to clear.
+      types to clear. 
     </desc>
   </func>
   <func name="get">
       Gets the current application state.
 
       Gets the current application state. This will be a bitmask
-      combination of the APPMOUSEFOCUS, APPINPUTFOCUS or APPACTIVE
-      masks, indicating whether the application currently is active and
-      has the mouse and keyboard input focus.
+      combination of the :const:`APPMOUSEFOCUS`, :const:`APPINPUTFOCUS` or
+      :const:`APPACTIVE` masks, indicating whether the application currently is
+      active and has the mouse and keyboard input focus.
     </desc>
   </func>
   <func name="get_blocked">
 
       This will block a single or multiple event types from being
       processed by the event system and thus will exactly behave like
-      state(type, IGNORE).
+      state(type, :const:`IGNORE`).
 
       In case other event types are already blocked, the block for them
       will be reset.
             # Any other event may pass.
             return True
       
-      In case the QUITEVENT is processed by the event filter, returning
+      In case the :const:`QUITEVENT` is processed by the event filter, returning
       True will cause the SDL window to be closed, otherwise, the window
       will remain open, if possible.
 
       Sets the processing state of an event type.
 
       This allows you to set the processing state of an event type.
-      If the state is set to IGNORE, events matching the type will be
+      If the state is set to :const:`IGNORE`, events matching the type will be
       automatically dropped from the event queue and will not be
       filtered. This will behave similar to set_blocked().
-      If the state is set to ENABLE, events matching the type will be
+      If the state is set to :const:`ENABLE`, events matching the type will be
       processed normally.
-      If the state iset set to QUERY, state() will return the current
-      processing state of the specified event type (ENABLE or IGNORE).
+      If the state iset set to :const:`QUERY`, state() will return the current
+      processing state of the specified event type (:const:`ENABLE` or
+      :const:`IGNORE`).
     </desc>
   </func>
   <func name="wait">

doc/src/sdlextbase.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlext.base">
+  <short>basic extensions for SDL modules</short>
   <desc>Extension module for the pygame2 SDL wrapper.</desc>
 
   <class name="PixelArray">

doc/src/sdlextdraw.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.sdlext.draw">
+  <short>extended SDL drawing methods</short>
   <desc>None</desc>
 
   <func name="aaline">

doc/src/sdlextfastevent.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlext.fastevent">
+  <short>fast SDL event handling module</short>
   <desc></desc>
 
   <class name="Event">

doc/src/sdlextnumericsurfarray.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.sdlext.numericsurfarray">
+  <short>SDL surface arrays using Numeric</short>
   <desc></desc>
 
   <func name="array2d">

doc/src/sdlextscrap.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlext.scrap">
+  <short>OS clipboard access for SDL</short>
   <desc></desc>
 
   <func name="contains">

doc/src/sdlexttransform.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.sdlext.transform">
+  <short>SDL surface transformation algorithms</short>
   <desc></desc>
 
   <func name="average_color">

doc/src/sdlgfxbase.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlgfx.base">
+  <short>basic SDL_gfx wrapper module</short>
   <desc></desc>
 
   <class name="FPSmanager">

doc/src/sdlgfxprimitives.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlgfx.primitives">
+  <short>SDL_gfx primitives drawing</short>
   <desc></desc>
 
   <func name="aacircle">

doc/src/sdlgfxrotozoom.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlgfx.rotozoom">
+  <short>SDL_gfx rotozoom methods</short>
   <desc></desc>
 
   <func name="rotate_90">

doc/src/sdlgl.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.gl">
+  <short>SDL OpenGL access wrapper module</short>
   <desc></desc>
 
   <func name="get_attribute">

doc/src/sdlimage.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
-<module name="pygame2.sdlimage">
+<module name="pygame2.sdl.image">
+  <short>SDL image I/O wrapper module</short>
   <desc>None</desc>
 
-  <func name="get_error">
+  <func name="load_bmp">
     <call></call>
     <desc></desc>
   </func>
-  <func name="load">
-    <call></call>
-    <desc></desc>
-  </func>
-  <func name="read_xpm_from_array">
+  <func name="save_bmp">
     <call></call>
     <desc></desc>
   </func>

doc/src/sdlimagebase.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.sdlimage.base">
-  <desc></desc>
+  <short>basic SDL_image wrapper module</short>
+  <desc>TODO</desc>
 
   <func name="get_error">
     <call></call>

doc/src/sdljoystick.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.joystick">
+  <short>SDL joystick I/O wrapper wrapper module</short>
   <desc></desc>
 
   <class name="Joystick">

doc/src/sdlkeyboard.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.keyboard">
+  <short>SDL keyboard I/O wrapper module</short>
   <desc></desc>
 
   <func name="enable_repeat">

doc/src/sdlmixerbase.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlmixer.base">
+  <short>basic SDL_mixer wrapper module</short>
   <desc></desc>
 
   <class name="Channel">

doc/src/sdlmixerchannel.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlmixer.channel">
+  <short>SDL_mixer sound channel handling</short>
   <desc></desc>
 
   <func name="allocate">

doc/src/sdlmixermusic.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.sdlmixer.music">
+  <short>SDL_mixer music playback</short>
   <desc></desc>
 
   <func name="fade_out">

doc/src/sdlmixernumericsndarray.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlmixer.numericsndarray">
+  <short>SDL_mixer chunk arrays using Numeric</short>
   <desc></desc>
 
   <func name="array">

doc/src/sdlmouse.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 ]>
 
 <module name="pygame2.sdl.mouse">
+  <short>SDL mouse I/O wrapper module</short>
   <desc></desc>
 
   <class name="Cursor">

doc/src/sdlrwops.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.rwops">
+  <short>SDL RWops wrapper module</short>
   <desc></desc>
 
 </module>

doc/src/sdltime.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.time">
+  <short>SDL time handling and measurement wrapper module</short>
   <desc></desc>
 
   <func name="add_timer">

doc/src/sdlttfbase.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdlttf.base">
+  <short>basic SDL_ttf wrapper module</short>
   <desc></desc>
 
   <class name="Font">

doc/src/sdlvideo.xml

 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE module [
-<!ELEMENT module (desc, (func|class)*)>
+<!ELEMENT module (short, desc, (func|class)*)>
 <!ATTLIST module name CDATA #REQUIRED>
+<!ELEMENT short (#PCDATA)>
 <!ELEMENT desc (#PCDATA)>
 <!ELEMENT call (#PCDATA)>
 <!ELEMENT func (call, desc)>
 <!ATTLIST method name CDATA #REQUIRED>
 ]>
 
+
 <module name="pygame2.sdl.video">
+  <short>SDL video display wrapper module.</short>
   <desc></desc>
 
   <class name="Overlay">