documentation updates

6 files changed, 168 insertions, 45 deletions

diff --git a/documentation/appendix.rst b/documentation/appendix.rst
index eaea2da..a8c83e3 100644
--- a/documentation/appendix.rst
+++ b/documentation/appendix.rst
@@ -20,49 +20,47 @@ LICENSE AGREEMENT
 ~~~~~~~~~~~~~~~~~
 
 1. This LICENSE AGREEMENT is between the copyright holder of this
-product, and the Individual or Organization ("Licensee") accessing
-and otherwise using this product in source or binary form and its
-associated documentation.
+   product, and the Individual or Organization ("Licensee") accessing and
+   otherwise using this product in source or binary form and its associated
+   documentation.
 
 2. Subject to the terms and conditions of this License Agreement,
-the copyright holder hereby grants Licensee a nonexclusive,
-royalty-free, world-wide license to reproduce, analyze, test,
-perform and/or display publicly, prepare derivative works, distribute,
-and otherwise use this product alone or in any derivative version,
-provided, however, that copyright holders License Agreement and
-copyright holders notice of copyright are retained in this product
-alone or in any derivative version prepared by Licensee.
+   the copyright holder hereby grants Licensee a nonexclusive, royalty-free,
+   world-wide license to reproduce, analyze, test, perform and/or display
+   publicly, prepare derivative works, distribute, and otherwise use this
+   product alone or in any derivative version, provided, however, that
+   copyright holders License Agreement and copyright holders notice of
+   copyright are retained in this product alone or in any derivative version
+   prepared by Licensee.
 
 3. In the event Licensee prepares a derivative work that is based on
-or incorporates this product or any part thereof, and wants to make
-the derivative work available to others as provided herein, then
-Licensee hereby agrees to include in any such work a brief summary of
-the changes made to this product.
+   or incorporates this product or any part thereof, and wants to make the
+   derivative work available to others as provided herein, then Licensee hereby
+   agrees to include in any such work a brief summary of the changes made to
+   this product.
 
 4. The copyright holder is making this product available to Licensee on
-an "AS IS" basis. THE COPYRIGHT HOLDER MAKES NO REPRESENTATIONS OR
-WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION,
-THE COPYRIGHT HOLDER MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
-WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR
-THAT THE USE OF THIS PRODUCT WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
+   an "AS IS" basis. THE COPYRIGHT HOLDER MAKES NO REPRESENTATIONS OR
+   WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, THE
+   COPYRIGHT HOLDER MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF
+   MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
+   THIS PRODUCT WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
 
 5. THE COPYRIGHT HOLDER SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER
-USERS OF THIS PRODUCT FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL
-DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE
-USING THIS PRODUCT, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE
-POSSIBILITY THEREOF.
+   USERS OF THIS PRODUCT FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES
+   OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING THIS
+   PRODUCT, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY
+   THEREOF.
 
 6. This License Agreement will automatically terminate upon a material
-breach of its terms and conditions.
+   breach of its terms and conditions.
 
 7. Nothing in this License Agreement shall be deemed to create any
-relationship of agency, partnership, or joint venture between the
-copyright holder and Licensee. This License Agreement does not grant
-permission to use trademarks or trade names from the copyright holder
-in a trademark sense to endorse or promote products or services of
-Licensee, or any third party.
+   relationship of agency, partnership, or joint venture between the copyright
+   holder and Licensee. This License Agreement does not grant permission to use
+   trademarks or trade names from the copyright holder in a trademark sense to
+   endorse or promote products or services of Licensee, or any third party.
 
 8. By copying, installing or otherwise using this product, Licensee
-agrees to be bound by the terms and conditions of this License
-Agreement.
+   agrees to be bound by the terms and conditions of this License Agreement.
 
diff --git a/documentation/examples.rst b/documentation/examples.rst
new file mode 100644
index 0000000..a50b655
--- /dev/null
+++ b/documentation/examples.rst
@@ -0,0 +1,113 @@
+==========
+ Examples
+==========
+
+Miniterm
+========
+This is a console application that provides a small terminal application.
+miniterm itself does not implement any terminal features such as VT102
+compatibility. However it inherits these features from the terminal it is run.
+For example on GNU/Linux running from an xterm it will support the escape
+sequences of the xterm. On Windows the typical console window is dumb and does
+not support any escapes. When ANSI.sys is loaded it supports some escapes.
+
+Command line options can be given so that binary data including escapes for
+terminals are escaped or output as hex.
+
+miniterm supports some control functions. Typing ``CTRL+T CTRL+H`` when it is
+running shows the help text.
+
+miniterm.py_
+    The miniterm program.
+
+setup-miniterm-py2exe.py_
+    This is a py2exe setup script for Windows. It can be used to create a
+    standalone ``miniterm.exe``.
+
+.. _miniterm.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/miniterm.py
+.. _setup-miniterm-py2exe.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup-miniterm-py2exe.py
+
+
+TCP/IP - serial bridge
+======================
+This program opens a TCP/IP port. When a connection is made to that port (e.g.
+with telnet) it forwards all data to the serial port and vice versa.
+
+The serial port settings are set on the command line when starting the program.
+There is no possibility to change settings from remote.
+
+tcp_serial_redirect.py_
+    Main program.
+
+.. _tcp_serial_redirect.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/tcp_serial_redirect.py
+
+
+wxPython examples
+=================
+A simple terminal application for wxPython and a flexible serial port
+configuration dialog are shown here.
+
+wxTerminal.py_
+    A simple terminal application. Note that the length of the buffer is
+    limited by wx and it may suddenly stop displaying new input.
+
+wxTerminal.wxg_
+    A wxGlade design file for the terminal application.
+
+wxSerialConfigDialog.py_
+    A flexible serial port configuration dialog.
+
+wxSerialConfigDialog.wxg_
+    The wxGlade design file for the configuration dialog.
+
+setup_demo.py_
+    A py2exe setup script to package the terminal application.
+
+.. _wxTerminal.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.py
+.. _wxTerminal.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxTerminal.wxg
+.. _wxSerialConfigDialog.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.py
+.. _wxSerialConfigDialog.wxg: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/wxSerialConfigDialog.wxg
+.. _setup_demo.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/setup_demo.py
+
+
+Wrapper class
+=============
+This example provides a subclass based on ``Serial`` that has an alternative
+implementation of ``readline()``
+
+enhancedserial.py_
+    A class with alternative ``readline()`` implementation.
+
+.. _enhancedserial.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/enhancedserial.py
+
+
+Finding serial ports
+====================
+scan.py_
+    A simple loop that probes serial ports by number.
+
+scanwin32.py_
+    A Windows only version that returns a list of serial ports with information
+    from the registry.
+
+.. _scan.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scan.py
+.. _scanwin32.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanwin32.py
+
+
+Unit tests
+==========
+The project uses a number of unit test to verify the functionality. They all
+need a loop back connector. The scripts itself contain more information.
+
+test.py_
+    Basic tests.
+
+test_high_load.py_
+    Tests involving sending a lot of data.
+
+test_advanced.py_
+    Test more advanced features.
+
+.. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test.py
+.. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_high_load.py
+.. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_advanced.py
diff --git a/documentation/index.rst b/documentation/index.rst
index 9c600e2..8019123 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -13,6 +13,7 @@ Contents:
 
     pyserial
     shortintro
+    examples
     pyserial_api
     pyparallel
     appendix
diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst
index 258ef51..fcc3fd0 100644
--- a/documentation/pyserial.rst
+++ b/documentation/pyserial.rst
@@ -93,10 +93,11 @@ Windows
 
 References
 ==========
-* Python: http://www.python.org/|http://www.python.org
+* Python: http://www.python.org/
 * pywin32: http://sourceforge.net/projects/pywin32/ (previously known as win32all)
-* Jython: http://www.jython.org/|http://www.jython.org
-* Java@IBM http://www-106.ibm.com/developerworks/java/jdk/ (JavaComm links are on the download page for the respective platform jdk)
+* Jython: http://www.jython.org/
+* Java@IBM http://www-106.ibm.com/developerworks/java/jdk/ (JavaComm links are
+  on the download page for the respective platform jdk)
 * Java@SUN http://java.sun.com/products/
 * IronPython: http://www.codeplex.com/IronPython
 * setuptools: http://peak.telecommunity.com/DevCenter/setuptools
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index 7c5ea1d..fa67b89 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -35,25 +35,22 @@ Classes
             Set a read timeout value.
 
         :param xonxoff:
-
             Enable software flow control.
 
         :param rtscts:
-
             Enable hardware (RTS/CTS) flow control.
 
         :param interCharTimeout:
-
             Inter-character timeout, None to disable.
 
     The port is immediately opened on object creation, when a port is given. It
     is not opened when port is None.
 
-    Possible values for :param:`timeout`::
+    Possible values for the parameter ``timeout``::
 
-            timeout=None    # wait forever
-            timeout=0       # non-blocking mode (return immediately on read)
-            timeout=x       # set timeout to x seconds (float allowed)
+            timeout = None  # wait forever
+            timeout = 0     # non-blocking mode (return immediately on read)
+            timeout = x     # set timeout to x seconds (float allowed)
 
 
     .. method:: open()
@@ -80,7 +77,7 @@ Classes
 
     .. method:: write(s)
 
-        Write the string :param:`s` to the port.
+        Write the string `s` to the port.
 
     .. method:: flush(self):
 
@@ -134,7 +131,7 @@ Classes
     .. attribute:: portstr
 
         Device name (Read Only). This is always the device name even if the
-        port was opened by a numeber.
+        port was opened by a number.
 
     .. attribute:: BAUDRATES
 
@@ -196,18 +193,21 @@ Classes
     .. method:: nonblocking()
 
         :platform: Unix
+
         Configure the device for nonblocking operations. This can be useful if
         the port is used with ``select``.
 
     .. method:: fileno()
 
         :platform: Unix
+
         Return file descriptor number.
 
 
     .. method:: setXON(level=True)
 
         :platform: Windows
+
         Set software flow control state.
 
 
diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst
index 5e117ca..048f94d 100644
--- a/documentation/shortintro.rst
+++ b/documentation/shortintro.rst
@@ -2,6 +2,9 @@
  Short introduction
 ====================
 
+Opening serial ports
+====================
+
 Open port 0 at "9600,8,N,1", no timeout::
 
     >>> import serial
@@ -25,6 +28,9 @@ Open second port at "38400,8,E,1", non blocking HW handshaking::
     >>> s = ser.read(100)       # read up to one hundred bytes
     ...                         # or as much is in the buffer
 
+Configuring ports later
+=======================
+
 Get a Serial instance and configure/open it later::
 
     >>> ser = serial.Serial()
@@ -39,9 +45,13 @@ Get a Serial instance and configure/open it later::
     >>> ser.isOpen()
     False
 
+Readline
+========
 Be carefully when using "readline". Do specify a timeout when opening the
 serial port otherwise it could block forever if no newline character is
 received. Also note that "readlines" only works with a timeout. "readlines"
 depends on having a timeout and interprets that as EOF (end of file). It raises
-an exception if the port is not opened correctly.  Do also have a look at the
-example files in the examples directory in the source distribution or online.
+an exception if the port is not opened correctly.
+
+Do also have a look at the example files in the examples directory in the
+source distribution or online.