Release 0.4: tagging released revisiondocutils-0.4

git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.4@4268 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 0 insertions, 618 deletions

diff --git a/sandbox/edloper/docpy/asyncore.rst b/sandbox/edloper/docpy/asyncore.rst
deleted file mode 100644
index 2eda1647c..000000000
--- a/sandbox/edloper/docpy/asyncore.rst
+++ /dev/null
@@ -1,295 +0,0 @@
-==========
- asyncore
-==========
-
------------------------------
- Asynchronous socket handler
------------------------------
-
-Literal block::
-  Synopsis: A base class for developing asynchronous socket
-            handling services.
-  Type: module builtin
-  Module-Author: Sam Rushing <rushing@nightmare.com>
-  Author: Christopher Petrilli <petrilli@amber.org>
-  Author: Steve Holden <sholden@holdenweb.com>
-
-.. Type: ... builtin, standard, various others: any specific usages required?
-..
-.. Heavily adapted from original documentation by Sam Rushing.
-..
-..  ............................................
-..   This is the (first) RFC822-reader strawman
-..  ............................................
-..    Presumes a custom reader appropriate to docpy
-..    RFC822 continuation IS allowed (see Synopsis)
-..    Needtocheck: RFC822-readers and multiple entities?  (Author lines)
-..    Dunno about implication of \section in the original
-..    Dunno about comments (#?);  "Credit: Sam Rushing?"
-..    Note in passing: names of new roles and directives made similar to
-..      the existing docpy macros on purpose (for existing corpus & community)
-..    		    
-..    Markups needed, used, and existing in rst:
-..      *emphasis*
-..
-..    Markups needed, used, and modified by this strawman:
-..      ``code``
-..    
-..    Roles needed below by this strawman:
-..      :cfunction:``
-..      :module:``
-..      :refmodule:``
-..      :class:``
-..      :function:``
-..      :var:``
-..	:label:``
-..    
-..    Directives needed below by this strawman:
-..      .. funcdesc::
-..		need to parse for optional argumnents shown as [...]
-..      .. classdesc::
-..      .. datadesc::
-..
-..    TBS - formals, e.g., funcdesc - several alternatives proposed
-..              below (see funcdesc) in this draft 
-..          the one shown first seems on track for consensus 04.3.20
-..              (the directive will parse brackets, etc. - easier to use!)
-
-This module provides the basic infrastructure for writing asynchronous 
-socket service clients and servers.
-
-There are only two ways to have a program on a single processor do 
-"more than one thing at a time." Multi-threaded programming is the 
-simplest and most popular way to do it, but there is another very 
-different technique, that lets you have nearly all the advantages of 
-multi-threading, without actually using multiple threads.  It's really 
-only practical if your program is largely I/O bound.  If your program 
-is processor bound, then pre-emptive scheduled threads are probably what 
-you really need. Network servers are rarely processor bound, however.
-
-If your operating system supports the :cfunction:`select()` system call 
-in its I/O library (and nearly all do), then you can use it to juggle 
-multiple communication channels at once; doing other work while your 
-I/O is taking place in the "background."  Although this strategy can 
-seem strange and complex, especially at first, it is in many ways 
-easier to understand and control than multi-threaded programming.  
-The :module:`asyncore` module solves many of the difficult problems for 
-you, making the task of building sophisticated high-performance 
-network servers and clients a snap. For "conversational" applications
-and protocols the companion  :refmodule:`asynchat` module is invaluable.
-
-The basic idea behind both modules is to create one or more network
-*channels*, instances of class :class:`asyncore.dispatcher` and
-:class:`asynchat.async_chat`. Creating the channels adds them to a global
-map, used by the :function:`loop()` function if you do not provide it
-with your own :var:`map`.
-
-Once the initial channel(s) is(are) created, calling the :function:`loop()`
-function activates channel service, which continues until the last
-channel (including any that have been added to the map during asynchronous
-service) is closed.
-
-.. funcdesc:: loop([timeout [, use_poll [, map]]])
-
-    Enter a polling loop that only terminates after all open channels
-    have been closed.  All arguments are optional.  The :var:`timeout`
-    argument sets the timeout parameter for the appropriate
-    :function:`select()` or :function:`poll()` call, measured in seconds;
-    the default is 30 seconds.  The :var:`use_poll` parameter, if true,
-    indicates that :function:`poll()` should be used in preference to
-    :function:`select()` (the default is ``False``).  The :var:`map` parameter
-    is a dictionary whose items are the channels to watch.  As channels
-    are closed they are deleted from their map.  If :var:`map` is
-    omitted, a global map is used (this map is updated by the default
-    class :method:`__init__()`
-    -- make sure you extend, rather than override, :method:`__init__()`
-    if you want to retain this behavior).
-
-    Channels (instances of :class:`asyncore.dispatcher`, :class:`asynchat.async_chat`
-    and subclasses thereof) can freely be mixed in the map.
-    
-.. classdesc:: dispatcher()
-
-    The :class:`dispatcher` class is a thin wrapper around a low-level socket object.
-    To make it more useful, it has a few methods for event-handling  which are called
-    from the asynchronous loop.  
-    Otherwise, it can be treated as a normal non-blocking socket object.
-
-    Two class attributes can be modified, to improve performance,
-    or possibly even to conserve memory.
-
-    .. datadesc:: ac_in_buffer_size
-
-        The asynchronous input buffer size (default ``4096``).
-
-    .. datadesc:: ac_out_buffer_size
-
-        The asynchronous output buffer size (default ``4096``).
-
-    The firing of low-level events at certain times or in certain connection
-    states tells the asynchronous loop that certain higher-level events have
-    taken place. For example, if we have asked for a socket to connect to
-    another host, we know that the connection has been made when the socket
-    becomes writable for the first time (at this point you know that you may
-    write to it with the expectation of success). The implied higher-level
-    events are:
-  
-    =====================       ===============================================
-    ``Event``                   Description
-    ---------------------       -----------------------------------------------
-    ``handle_connect()``        Implied by the first write event
-    ``handle_close()``          Implied by a read event with no data available
-    ``handle_accept()``         Implied by a read event on a listening socket
-    =====================       ===============================================
-
-  
-    During asynchronous processing, each mapped channel's :method:`readable()`
-    and :method:`writable()` methods are used to determine whether the channel's
-    socket should be added to the list of channels :cfunction:`select()`\ ed or
-    :cfunction:`poll()`\ ed for read and write events.
-
-Thus, the set of channel events is larger than the basic socket events.
-The full set of methods that can be overridden in your subclass follows:
-
-.. methoddesc:: handle_read()
-
-    Called when the asynchronous loop detects that a :method:`read()`
-    call on the channel's socket will succeed.
-
-.. methoddesc:: handle_write()
-
-    Called when the asynchronous loop detects that a writable socket
-    can be written.  
-    Often this method will implement the necessary buffering for 
-    performance.  For example::
-
-
-        def handle_write(self):
-            sent = self.send(self.buffer)
-            self.buffer = self.buffer[sent:]
-
-.. methoddesc:: handle_expt()
-
-  Called when there is out of band (OOB) data for a socket 
-  connection.  This will almost never happen, as OOB is 
-  tenuously supported and rarely used.
-
-.. methoddesc:: handle_connect()
-
-  Called when the active opener's socket actually makes a connection.
-  Might send a "welcome" banner, or initiate a protocol
-  negotiation with the remote endpoint, for example.
-
-.. methoddesc:: handle_close()
-
-  Called when the socket is closed.
-
-.. methoddesc:: handle_error()
-
-  Called when an exception is raised and not otherwise handled.  The default
-  version prints a condensed traceback.
-
-.. methoddesc:: handle_accept()
-
-  Called on listening channels (passive openers) when a  
-  connection can be established with a new remote endpoint that
-  has issued a :method:`connect()` call for the local endpoint.
-
-.. methoddesc:: readable()
-
-  Called each time around the asynchronous loop to determine whether a
-  channel's socket should be added to the list on which read events can
-  occur.  The default method simply returns ``True``, 
-  indicating that by default, all channels will be interested in
-  read events.
-
-.. methoddesc:: writable()
-
-  Called each time around the asynchronous loop to determine whether a
-  channel's socket should be added to the list on which write events can
-  occur.  The default method simply returns ``True``, 
-  indicating that by default, all channels will be interested in
-  write events.
-
-In addition, each channel delegates or extends many of the socket methods.
-Most of these are nearly identical to their socket partners.
-
-.. methoddesc:: create_socket(family, type)
-
-  This is identical to the creation of a normal socket, and 
-  will use the same options for creation.  Refer to the
-  :refmodule:`socket` documentation for information on creating
-  sockets.
-
-.. methoddesc:: connect(address)
-
-  As with the normal socket object, :var:`address` is a 
-  tuple with the first element the host to connect to, and the 
-  second the port number.
-
-.. methoddesc:: send(data)
-
-  Send :var:`data` to the remote end-point of the socket.
-
-.. methoddesc:: recv(buffer_size)
-
-  Read at most :var:`buffer_size` bytes from the socket's remote end-point.
-  An empty string implies that the channel has been closed from the other
-  end.
-
-.. methoddesc:: listen(backlog)
-
-  Listen for connections made to the socket.  The :var:`backlog`
-  argument specifies the maximum number of queued connections
-  and should be at least 1; the maximum value is
-  system-dependent (usually 5).
-
-.. methoddesc:: bind(address)
-
-  Bind the socket to :var:`address`.  The socket must not already
-  be bound.  (The format of :var:`address` depends on the address
-  family --- see above.)
-
-.. methoddesc:: accept()
-
-  Accept a connection.  The socket must be bound to an address
-  and listening for connections.  The return value is a pair
-  ``(conn , address)`` where :var:`conn` is a
-  *new* socket object usable to send and receive data on
-  the connection, and :var:`address` is the address bound to the
-  socket on the other end of the connection.
-
-.. methoddesc:: close()
-
-  Close the socket.  All future operations on the socket object
-  will fail.  The remote end-point will receive no more data (after
-  queued data is flushed).  Sockets are automatically closed
-  when they are garbage-collected.
-
-
-asyncore Example basic HTTP client :label:`asyncore-example`
-------------------------------------------------------------
-As a basic example, below is a very basic HTTP client that uses the 
-:class:`dispatcher` class to implement its socket handling::
-
-	class http_client(asyncore.dispatcher):
-	    def __init__(self, host,path):
-		asyncore.dispatcher.__init__(self)
-		self.path = path
-		self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
-		self.connect( (host, 80) )
-		self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % self.path
-
-	    def handle_connect(self):
-		pass
-
-	    def handle_read(self):
-		data = self.recv(8192)
-		print data
-
-	    def writable(self):
-		return (len(self.buffer) > 0)
-
-	    def handle_write(self):
-		sent = self.send(self.buffer)
-		self.buffer = self.buffer[sent:]
diff --git a/sandbox/edloper/docpy/docpy.py b/sandbox/edloper/docpy/docpy.py
deleted file mode 100755
index 450a9b735..000000000
--- a/sandbox/edloper/docpy/docpy.py
+++ /dev/null
@@ -1,323 +0,0 @@
-#!/usr/bin/env python
-
-# Author: David Goodger
-# Contact: goodger@users.sourceforge.net
-# Revision: $Revision$
-# Date: $Date$
-# Copyright: This module has been placed in the public domain.
-
-"""
-:todo: role-labeled inline text
-:todo: generate output (subclass LaTeXTransformer)
-:todo later: macros (susbtitution refs)
-"""
-from docutils import nodes
-from docutils.parsers.rst import directives
-from docutils.parsers.rst.directives import admonitions
-from docutils.parsers.rst import states
-from docutils.writers import latex2e
-import re, tokenize
-
-######################################################################
-# New nodes
-######################################################################
-
-class funcdesc(nodes.Admonition, nodes.Element): pass
-class classdesc(nodes.Admonition, nodes.Element): pass
-class methoddesc(nodes.Admonition, nodes.Element): pass
-class datadesc(nodes.Admonition, nodes.Element): pass
-class desc_name(nodes.Part, nodes.Inline, nodes.TextElement): pass
-
-# We might use pynodes instead.
-class func_signature(nodes.Part, nodes.Inline, nodes.TextElement): pass
-class func_name(nodes.Part, nodes.Inline, nodes.TextElement): pass
-class func_parameterlist(nodes.Part, nodes.Inline, nodes.TextElement): pass
-class func_parameter(nodes.Part, nodes.Inline, nodes.TextElement): pass
-class func_optional(nodes.Part, nodes.Inline, nodes.TextElement): pass
-
-# These are the inline things.
-class docpy_function(nodes.Inline, nodes.TextElement): pass
-class docpy_manpage(nodes.Inline, nodes.TextElement): pass
-class docpy_regexp(nodes.Inline, nodes.TextElement): pass
-class docpy_file(nodes.Inline, nodes.TextElement): pass
-class docpy_label(nodes.Inline, nodes.TextElement): pass
-class docpy_class(nodes.Inline, nodes.TextElement): pass
-class docpy_method(nodes.Inline, nodes.TextElement): pass
-class docpy_cfunction(nodes.Inline, nodes.TextElement): pass
-class docpy_refmodule(nodes.Inline, nodes.TextElement): pass
-class docpy_module(nodes.Inline, nodes.TextElement): pass
-class docpy_var(nodes.Inline, nodes.TextElement): pass
-inline_docpy_elements = { # Maps roles to entitites
-    'function':docpy_function,
-    'manpage':docpy_manpage,
-    'regexp':docpy_regexp,
-    'file':docpy_file,
-    'label': docpy_label,
-    'class': docpy_class,
-    'method': docpy_method,
-    'cfunction': docpy_cfunction,
-    'refmodule': docpy_refmodule,
-    'module': docpy_module,
-    'var': docpy_var,
-    }
-
-for (role, element) in inline_docpy_elements.items():
-    states.register_inliner_role(role, element)
-
-
-######################################################################
-# Directives
-######################################################################
-
-# Transform a python signature into RST.                  
-def parse_signature(s):
-    """
-    A straw-man implementation. (Might be sufficient)
-    """
-    s = s.strip()
-    m = re.match(r'^(\w+)\s*\((.*)\)$', s)
-    if m is None: raise ValueError(`s`)
-    name, arglist = m.groups()
-
-    sig = func_signature(s,'')
-
-    sig.append(func_name(name,name))
-    sig.append(func_parameterlist())
-
-    stack = [sig[-1]]
-    for token in re.split(r'(\*{0,2}\w+|[\[\],])', arglist):
-        #print `token`, stack
-        if token == '[':
-            opt = func_optional()
-            stack[-1].append(opt)
-            stack.append(opt)
-        elif token == ']':
-            stack.pop()
-        elif token == ',':
-            pass
-        elif re.match(r'^\s*$', token):
-            pass
-        elif re.match(r'^\*{0,2}\w+$', token):
-            stack[-1].append(func_parameter(token,token))
-        else:
-            raise ValueError(s)
-    if len(stack) != 1: raise ValueError(s)
-    return sig
-
-def funcdesc_directive(name, arguments, options, content, lineno,
-                           content_offset, block_text, state, state_machine):
-    rv = admonitions.make_admonition(funcdesc, name, [], options, content,
-                                     lineno, content_offset, block_text,
-                                     state, state_machine)
-    rv[0].insert(0, parse_signature(arguments[0]))
-    return rv
-funcdesc_directive.content = 1
-funcdesc_directive.arguments = (1,0,1) # 1 required arg with spaces.
-
-def methoddesc_directive(name, arguments, options, content, lineno,
-                           content_offset, block_text, state, state_machine):
-    rv = admonitions.make_admonition(methoddesc, name, [], options, content,
-                                     lineno, content_offset, block_text,
-                                     state, state_machine)
-    rv[0].insert(0, parse_signature(arguments[0]))
-    return rv
-methoddesc_directive.content = 1
-methoddesc_directive.arguments = (1,0,1) # 1 required arg with spaces.
-
-def classdesc_directive(name, arguments, options, content, lineno,
-                           content_offset, block_text, state, state_machine):
-    rv = admonitions.make_admonition(classdesc, name, [], options, content,
-                                     lineno, content_offset, block_text,
-                                     state, state_machine)
-    rv[0].insert(0, parse_signature(arguments[0]))
-    return rv
-classdesc_directive.content = 1
-classdesc_directive.arguments = (1,0,1) # 1 required arg with spaces.
-
-def datadesc_directive(name, arguments, options, content, lineno,
-                           content_offset, block_text, state, state_machine):
-    rv = admonitions.make_admonition(datadesc, name, [], options, content,
-                                     lineno, content_offset, block_text,
-                                     state, state_machine)
-    rv[0].insert(0, desc_name(arguments[0], arguments[0]))
-    return rv
-datadesc_directive.content = 1
-datadesc_directive.arguments = (1,0,1) # 1 required arg with spaces.
-
-# Register the directives
-directives.register_directive('funcdesc', funcdesc_directive)
-directives.register_directive('methoddesc', methoddesc_directive)
-directives.register_directive('classdesc', classdesc_directive)
-directives.register_directive('datadesc', datadesc_directive)
-
-######################################################################
-# Writer
-######################################################################
-
-class DocpyWriter(latex2e.Writer):
-    def translate(self):
-        visitor = DocpyTranslator(self.document)
-        self.document.walkabout(visitor)
-        self.output = visitor.astext()
-        self.head_prefix = visitor.head_prefix
-        self.head = visitor.head
-        self.body_prefix = visitor.body_prefix
-        self.body = visitor.body
-        self.body_suffix = visitor.body_suffix
-
-class DocpyTranslator(latex2e.LaTeXTranslator):
-    """
-    Incompatibilities:
-      - latex docs uses \subsection, we generate \subsection*
-        (e.g., \subsection{asyncore Exampe ...})
-      - we generate header & footer info that we don't need
-      - we don't handle RFC822 stuff & generate a top-level \section
-      - in a function signature, we escape underscores but latex docs
-        don't.  e.g., funcdesc (line 46 of asyncore).
-      - in role-labeled text, we escape underscore but latex docs
-        don't.
-      - table rendering is completely different.
-    """
-
-    def __init__(self, *args):
-        latex2e.LaTeXTranslator.__init__(self, *args)
-        self.section_level = 1
-        self.first_paramter_visited = 0
-        
-    
-    #------------------------------------------------------------
-    # Directives
-    #------------------------------------------------------------
-    def visit_funcdesc(self, node):
-        self.body.append('\n'+r'\begin{funcdesc}')
-    def depart_funcdesc(self, node):
-        self.body.append(r'\end{funcdesc}'+'\n')
-
-    def visit_methoddesc(self, node):
-        self.body.append('\n'+r'\begin{methoddesc}')
-    def depart_methoddesc(self, node):
-        self.body.append(r'\end{methoddesc}'+'\n')
-
-    def visit_classdesc(self, node):
-        self.body.append('\n'+r'\begin{classdesc}')
-    def depart_classdesc(self, node):
-        self.body.append(r'\end{classdesc}'+'\n')
-
-    def visit_datadesc(self, node):
-        self.body.append('\n'+r'\begin{datadesc}')
-    def depart_datadesc(self, node):
-        self.body.append(r'\end{datadesc}'+'\n')
-
-    def visit_desc_name(self, node):
-        self.body.append('{')
-    def depart_desc_name(self, node):
-        self.body.append('}')
-    
-    def visit_func_name(self, node):
-        self.body.append('{')
-    def depart_func_name(self, node):
-        self.body.append('}')
-    
-    def visit_func_signature(self, node): pass
-    def depart_func_signature(self, node): pass
-    
-    def visit_func_parameterlist(self, node):
-        self.body.append('{')
-        self.first_parameter_visited = 0
-    def depart_func_parameterlist(self, node):
-        self.body.append('}')
-
-    def visit_func_parameter(self, node):
-        if self.first_parameter_visited:
-            self.body.append(', ')
-        self.first_parameter_visited = 1
-    def depart_func_parameter(self, node): pass
-
-    def visit_func_optional(self, node):
-        self.body.append(r'\optional{')
-        if self.first_paramter_visited:
-            self.body.append(',')
-    def depart_func_optional(self, node):
-        self.body.append('}')
-        
-
-    #------------------------------------------------------------
-    # Inline Roles
-    #------------------------------------------------------------
-    def visit_docpy_function(self, node):
-        self.body.append(r'\function{')
-    def depart_docpy_function(self, node):
-        self.body.append(r'}')
-
-    def visit_docpy_manpage(self, node):
-        self.body.append(r'\manpage{')
-    def depart_docpy_manpage(self, node):
-        self.body.append(r'}')
-
-    def visit_docpy_regexp(self, node):
-        self.body.append(r'\regexp{')
-    def depart_docpy_regexp(self, node):
-        self.body.append(r'}')
-
-    def visit_docpy_file(self, node):
-        self.body.append(r'\file{')
-    def depart_docpy_file(self, node):
-        self.body.append(r'}')
-        
-    def visit_docpy_label(self, node):
-        self.body.append(r'\label{')
-    def depart_docpy_label(self, node):
-        self.body.append(r'}')
-        
-    def visit_docpy_class(self, node):
-        self.body.append(r'\class{')
-    def depart_docpy_class(self, node):
-        self.body.append(r'}')
-        
-    def visit_docpy_method(self, node):
-        self.body.append(r'\method{')
-    def depart_docpy_method(self, node):
-        self.body.append(r'}')
-        
-    def visit_docpy_cfunction(self, node):
-        self.body.append(r'\cfunction{')
-    def depart_docpy_cfunction(self, node):
-        self.body.append(r'}')
-        
-    def visit_docpy_refmodule(self, node):
-        self.body.append(r'\refmodule{')
-    def depart_docpy_refmodule(self, node):
-        self.body.append(r'}')
-        
-    def visit_docpy_module(self, node):
-        self.body.append(r'\module{')
-    def depart_docpy_module(self, node):
-        self.body.append(r'}')
-        
-    def visit_docpy_var(self, node):
-        self.body.append(r'\var{')
-    def depart_docpy_var(self, node):
-        self.body.append(r'}')
-        
-    #------------------------------------------------------------
-    # Etc.
-    #------------------------------------------------------------
-    def visit_literal(self, node):
-        self.literal = 1
-        self.body.append('\\code{')
-
-######################################################################
-# Front-end code
-######################################################################
-if __name__ == '__main__':
-    import locale
-    try:
-        locale.setlocale(locale.LC_ALL, '')
-    except:
-        pass
-
-    from docutils.core import publish_cmdline, default_description
-    description = default_description
-    publish_cmdline(writer=DocpyWriter(), description=description)
-    #publish_cmdline(writer_name='pseudoxml', description=description)
-