- move documentation so that distutils sees it

- update CHANGES.txt
- install miniterm.py as script
- version 2.5-rc1

git-svn-id: http://svn.code.sf.net/p/pyserial/code/trunk/pyserial@263 f19166aa-fa4f-0410-85c2-fa1106f25c8a

10 files changed, 1524 insertions, 0 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
new file mode 100644
index 0000000..8384360
--- /dev/null
+++ b/documentation/Makefile
@@ -0,0 +1,88 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf _build/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+	@echo
+	@echo "Build finished. The HTML pages are in _build/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in _build/dirhtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in _build/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in _build/qthelp, like this:"
+	@echo "# qcollectiongenerator _build/qthelp/pySerial.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile _build/qthelp/pySerial.qhc"
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in _build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+	@echo
+	@echo "The overview file is in _build/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in _build/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in _build/doctest/output.txt."
diff --git a/documentation/appendix.rst b/documentation/appendix.rst
new file mode 100644
index 0000000..001c6e5
--- /dev/null
+++ b/documentation/appendix.rst
@@ -0,0 +1,68 @@
+==========
+ Appendix
+==========
+
+Related software
+================
+
+com0com - http://com0com.sourceforge.net/
+    Provides virtual serial ports for Windows.
+
+
+License
+=======
+
+Copyright (C) 2001-2009 Chris Liechti <cliechti(at)gmx.net>;
+All Rights Reserved.
+
+This is the Python license. In short, you can use this product in commercial
+and non-commercial applications, modify it, redistribute it.  A notification to
+the author when you use and/or modify it is welcome.
+
+
+**TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING THIS SOFTWARE**
+
+*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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+6. This License Agreement will automatically terminate upon a material 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.
+
+8. By copying, installing or otherwise using this product, Licensee agrees to
+   be bound by the terms and conditions of this License Agreement.
+
diff --git a/documentation/conf.py b/documentation/conf.py
new file mode 100644
index 0000000..7420982
--- /dev/null
+++ b/documentation/conf.py
@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+#
+# pySerial documentation build configuration file, created by
+# sphinx-quickstart on Tue Jul 21 00:27:45 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'pySerial'
+copyright = u'2009, Chris Liechti'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2.5'
+# The full version, including alpha/beta/rc tags.
+release = '2.5 preview'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = 'pyserial.png'
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pySerialdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'pySerial.tex', u'pySerial Documentation',
+   u'Chris Liechti', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+latex_logo = 'pyserial.png'
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
diff --git a/documentation/examples.rst b/documentation/examples.rst
new file mode 100644
index 0000000..283f2d6
--- /dev/null
+++ b/documentation/examples.rst
@@ -0,0 +1,282 @@
+==========
+ 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.
+
+miniterm::
+
+    --- Miniterm on /dev/ttyS0: 9600,8,N,1 ---
+    --- Quit: Ctrl+]  |  Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
+
+Command line options can be given so that binary data including escapes for
+terminals are escaped or output as hex.
+
+Command line options ``miniterm.py -h``::
+
+    Usage: miniterm.py [options] [port [baudrate]]
+
+    Miniterm - A simple terminal program for the serial port.
+
+    Options:
+      -h, --help            show this help message and exit
+      -p PORT, --port=PORT  port, a number (default 0) or a device name
+                            (deprecated option)
+      -b BAUDRATE, --baud=BAUDRATE
+                            set baud rate, default 9600
+      --parity=PARITY       set parity, one of [N, E, O, S, M], default=N
+      -e, --echo            enable local echo (default off)
+      --rtscts              enable RTS/CTS flow control (default off)
+      --xonxoff             enable software flow control (default off)
+      --cr                  do not send CR+LF, send CR only
+      --lf                  do not send CR+LF, send LF only
+      -D, --debug           debug received data (escape non-printable chars)
+                            --debug can be given multiple times: 0: just print
+                            what is received 1: escape non-printable characters,
+                            do newlines as unusual 2: escape non-printable
+                            characters, newlines too 3: hex dump everything
+      --rts=RTS_STATE       set initial RTS line state (possible values: 0, 1)
+      --dtr=DTR_STATE       set initial DTR line state (possible values: 0, 1)
+      -q, --quiet           suppress non error messages
+      --exit-char=EXIT_CHAR
+                            ASCII code of special character that is used to exit
+                            the application
+      --menu-char=MENU_CHAR
+                            ASCII code of special character that is used to
+                            control miniterm (menu)
+
+
+miniterm supports some control functions. Typing :kbd:`Control+t Control+h` when it is
+running shows the help text::
+
+    --- pySerial - miniterm - help
+    ---
+    --- Ctrl+]   Exit program
+    --- Ctrl+T   Menu escape key, followed by:
+    --- Menu keys:
+    ---       Ctrl+T   Send the menu character itself to remote
+    ---       Ctrl+]   Send the exit character to remote
+    ---       Ctrl+I   Show info
+    ---       Ctrl+U   Upload file (prompt will be shown)
+    --- Toggles:
+    ---       Ctrl+R  RTS          Ctrl+E  local echo
+    ---       Ctrl+D  DTR          Ctrl+B  BREAK
+    ---       Ctrl+L  line feed    Ctrl+A  Cycle repr mode
+    ---
+    --- Port settings (Ctrl+T followed by the following):
+    --- 7 8           set data bits
+    --- n e o s m     change parity (None, Even, Odd, Space, Mark)
+    --- 1 2 3         set stop bits (1, 2, 1.5)
+    --- b             change baud rate
+    --- x X           disable/enable software flow control
+    --- r R           disable/enable hardware flow control
+
+
+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.
+::
+
+    Usage: tcp_serial_redirect.py [options] [port [baudrate]]
+
+    Simple Serial to Network (TCP/IP) redirector.
+
+    Options:
+      -h, --help            show this help message and exit
+      -q, --quiet           suppress non error messages
+      --spy                 peek at the communication and print all data to the
+                            console
+
+      Serial Port:
+        Serial port settings
+
+        -p PORT, --port=PORT
+                            port, a number (default 0) or a device name
+        -b BAUDRATE, --baud=BAUDRATE
+                            set baud rate, default: 9600
+        --parity=PARITY     set parity, one of [N, E, O], default=N
+        --rtscts            enable RTS/CTS flow control (default off)
+        --xonxoff           enable software flow control (default off)
+        --rts=RTS_STATE     set initial RTS line state (possible values: 0, 1)
+        --dtr=DTR_STATE     set initial DTR line state (possible values: 0, 1)
+
+      Network settings:
+        Network configuration.
+
+        -P LOCAL_PORT, --localport=LOCAL_PORT
+                            local TCP port
+
+      Newline Settings:
+        Convert newlines between network and serial port. Conversion is
+        normally disabled and can be enabled by --convert.
+
+        -c, --convert       enable newline conversion (default off)
+        --net-nl=NET_NEWLINE
+                            type of newlines that are expected on the network
+                            (default: LF)
+        --ser-nl=SER_NEWLINE
+                            type of newlines that are expected on the serial port
+                            (default: CR+LF)
+
+    NOTE: no security measures are implemented. Anyone can remotely connect to
+    this service over the network.  Only one connection at once is supported. When
+    the connection is terminated it waits for the next connect.
+
+
+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
+
+
+Multi-port TCP/IP - serial bridge
+=================================
+This example implements a TCP/IP to serial port service that works with
+multiple ports at once. It uses select, no threads, and runs on POSIX systems
+only.
+
+- Check existence of ``/tty/USB0...9``.
+- Ports are periodically checked using ``os.path.exists``.
+- Send Zeroconfig announcements when port appears or disappears (uses
+  python-avahi and dbus).
+- Single process for all ports (not per port).
+- All published services are kept in a dictionary that maps device->publisher
+  object.
+- A delay of 5 seconds slows down the poll loop to a reasonable period.
+- The script implements a daemon that logs to the syslog, unless specified
+  otherwise on the command line.
+
+
+Requirements
+------------
+- python (>2.4)
+- python-avahi
+- python-dbus
+- python-serial
+
+
+Installation
+------------
+- Copy the script ``port_publisher.py`` to ``/usr/local/bin``.
+- Copy the script ``port_publisher.sh`` to ``/etc/init.d``.
+- Add links to the runlevels using ``update-rc.d port_publisher.sh defaults 99``
+- Thats it :-) the service will be started on next reboot. Alternatively run
+  ``invoke-rc.d port_publisher.sh start`` as root.
+
+
+port_publisher.py_
+    Multi-port TCP/IP-serial converter for POSIX environments.
+
+port_publisher.sh_
+    Example init.d script.
+
+.. _port_publisher.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/port_publisher.py
+.. _port_publisher.sh: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/port_publisher.sh
+
+
+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_
+test_high_load.py_
+    Tests involving sending a lot of data.
+    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.
+
+scanlinux.py_
+    A Linux only version looking at the entries in ``/dev``. It works best with
+    on systems with devfs or udev that only create those entries that represent
+    devices. On older installations a lot of pre-created device files are found
+    and an additional open check should be added to ensure that the device is
+    real.
+
+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
+.. _scanlinux.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanlinux.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_advanced.py_
+    Test more advanced features.
+
+test_high_load.py_
+    Tests involving sending a lot of data.
+
+test_iolib.py_
+    Tests involving the :mod:`io` library. Only available for Python 2.6 and
+    newer.
+
+.. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test.py
+.. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_advanced.py
+.. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_high_load.py
+.. _test_iolib.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/test_iolib.py
diff --git a/documentation/index.rst b/documentation/index.rst
new file mode 100644
index 0000000..96a78b5
--- /dev/null
+++ b/documentation/index.rst
@@ -0,0 +1,29 @@
+.. pySerial documentation master file
+
+Welcome to pySerial's documentation
+===================================
+
+This module encapsulates the access for the serial port. It provides backends
+for Python running on Windows, Linux, BSD (possibly any POSIX compliant
+system), Jython and IronPython (.NET and Mono). The module named "serial"
+automatically selects the appropriate backend.
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+    pyserial
+    shortintro
+    examples
+    pyserial_api
+    pyparallel
+    appendix
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/documentation/pyparallel.rst b/documentation/pyparallel.rst
new file mode 100644
index 0000000..00c0b95
--- /dev/null
+++ b/documentation/pyparallel.rst
@@ -0,0 +1,165 @@
+============
+ pyParallel
+============
+
+.. note:: This module is in development (since years ;-)
+
+Overview
+========
+This module encapsulates the access for the parallel port. It provides backends
+for Python running on Windows and Linux. Other platforms are possible too but
+not yet integrated.
+
+This module is still under development. But it may be useful for developers.
+
+Copyright (C) 2001-2003 Chris Liechti <cliechti(at)gmx.net>
+
+Here is the `project page on SourceForge`_ and here is the `SVN repository`_.
+
+.. _`project page on SourceForge`: http://sourceforge.net/projects/pyserial/
+.. _`SVN repository`: http://sourceforge.net/svn/?group_id=46487
+
+
+Features
+--------
+* same class based interface on all supported platforms
+* port numbering starts at zero, no need to know the port name in the user program
+* port string (device name) can be specified if access through numbering is inappropriate
+
+
+Requirements
+------------
+* Python 2.2 or newer
+* "Java Communications" (JavaComm) extension for Java/Jython
+
+
+Installation
+------------
+Extract files from the archive, open a shell/console in that directory and let
+Distutils do the rest: ``python setup.py install``
+
+The files get installed in the "Lib/site-packages" directory in newer Python versions.
+
+The windows version needs a compiled extension and the giveio.sys driver for
+Windows NT/2k/XP. The extension module can be compiled with Distutils with
+either MSVC or GCC/mingw32.
+
+It is released under a free software license, see LICENSE.txt for more details.
+
+
+Short introduction
+==================
+::
+
+    >>> import parallel
+    >>> p = parallel.Parallel()     # open LPT1
+    >>> p.setData(0x55)
+
+
+Examples
+--------
+Please look in the SVN Repository. There is an example directory where you can
+find a simple terminal and more.
+http://pyserial.svn.sourceforge.net/viewvc/pyserial/trunk/pyparallel/examples/
+
+
+API
+===
+
+.. module:: parallel
+
+.. class:: Parallel
+
+    .. method:: __init__(port)
+
+        Open given parallel port.
+
+    .. method:: setData(value)
+
+        Apply the given byte to the data pins of the parallel port.
+
+    .. method:: setDataStrobe(level)
+
+        Set the "data strobe" line to the given state.
+
+    .. method:: setAutoFeed(level)
+
+        Set "auto feed" line to given state.
+
+    .. method:: setInitOut(level)
+
+        Set "initialize" line to given state.
+
+    .. method: setSelect(level)
+
+        Set "select" line to given state.
+
+    .. method:getInError()
+
+        Set "Error" line to given state.
+
+    .. method:: getInSelected()
+
+        Read level of "select" line.
+
+    .. method:: getInPaperOut()
+
+        Read level of "paper out" line.
+
+    .. method:: getInAcknowledge()
+
+        Read level of "Acknowledge" line.
+
+    .. method: getInBusy()
+
+        Read level of "busy" line.
+
+
+.. module:: parallel.parallelutil
+
+.. class:: BitaccessMeta
+
+    This mix-in class adds a few properties that allow easier bit access to the
+    data lines. (D0 .. D7) e.g. p.D0 refers to the first bit of the data
+    lines.
+
+.. class:: VirtualParallelPort
+
+    This class provides a virtual parallel port implementation, useful
+    for tests and simulations without real hardware.
+
+
+Notes
+=====
+
+Linux
+-----
+1. The :manpage:`lp(4)` module must be unloaded, ``rmmod lp``. ``lp`` claims
+   exclusive access to the port and other programs won't be able to use it.
+
+2. The :manpage:`ppdev(4)` module needs to be loaded, ``modprobe ppdev``. When
+   ``udev`` is in use, (default with 2.6 kernels) this will create a
+   ``/dev/parport0``.
+
+3. The user needs to have write permissions to ``/dev/parport0``. Many
+   distributions have an ``lp`` group that owns the device; the simplest is to
+   add the user account to this group. Simply changing permissions on the
+   device is not the best strategy as they will be reverted to their defaults
+   next time the driver is loaded.
+
+
+Windows
+-------
+The giveio driver must be installed as the module needs direct access to the
+hardware. This also means that USB parallel port adapters won't be supported.
+
+
+Misc
+====
+References
+----------
+* Python: http://www.python.org/
+* 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/
diff --git a/documentation/pyserial.png b/documentation/pyserial.png
new file mode 100644
index 0000000..7fd45f4
--- /dev/null
+++ b/documentation/pyserial.png
diff --git a/documentation/pyserial.rst b/documentation/pyserial.rst
new file mode 100644
index 0000000..2db8c21
--- /dev/null
+++ b/documentation/pyserial.rst
@@ -0,0 +1,110 @@
+==========
+ pySerial
+==========
+
+Overview
+========
+This module encapsulates the access for the serial port. It provides backends
+for Python running on Windows, Linux, BSD (possibly any POSIX compliant
+system), Jython and IronPython (.NET and Mono). The module named "serial"
+automatically selects the appropriate backend.
+
+It is released under a free software license, see LICENSE_ for more
+details.
+
+Copyright (C) 2001-2009 Chris Liechti <cliechti(at)gmx.net>
+
+The `project page on SourceForge`_ and here is the `SVN repository`_ and the
+`Download Page`_.
+
+The homepage is at http://pyserial.sf.net.
+
+.. _LICENSE: appendix.html#license
+.. _`project page on SourceForge`: http://sourceforge.net/projects/pyserial/
+.. _`SVN repository`: http://sourceforge.net/svn/?group_id=46487
+.. _`Download Page`: http://sourceforge.net/project/showfiles.php?group_id=46487
+
+
+Features
+========
+* Same class based interface on all supported platforms.
+* Access to the port settings through Python properties.
+* Support for different byte sizes, stop bits, parity and flow control with
+  RTS/CTS and/or Xon/Xoff.
+* Working with or without receive timeout.
+* File like API with "read" and "write" ("readline" etc. also supported).
+* The files in this package are 100% pure Python.
+* The port is set up for binary transmission. No NULL byte stripping, CR-LF
+  translation etc. (which are many times enabled for POSIX.) This makes this
+  module universally useful.
+* Compatible with :mod:`io` library (Python 2.6+)
+
+
+Requirements
+============
+* Python 2.3 or newer, including Python 3.x
+* ctypes extensions on Windows (is in standard library since Python 2.5+)
+* "Java Communications" (JavaComm) or compatible extension for Java/Jython
+
+
+Installation
+============
+
+pyserial
+--------
+This installs a package that can be used from Python (``import serial``).
+
+To install the module for all users on the system, administrator rights (root)
+is required..
+
+From source (tar.gz or checkout)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+http://pypi.python.org/pypi/pyserial
+Unpack the archive, enter the ``pyserial-x.y`` directory and run::
+
+    python setup.py install
+
+Setuptools/PyPI
+~~~~~~~~~~~~~~~
+Alternatively it can be installed from PyPI, either manually downloading the
+files and installing as described above or using::
+
+    easy_install -U pyserial
+
+Packages
+~~~~~~~~
+There are also packaged versions for some Linux distributions and Windows:
+
+Debian/Ubuntu
+    A package is available under the name "python-serial".
+
+Windows
+    There is also a Windows installer for end users. It is located in the
+    PyPi_.  Developers may be interested to get the source archive, because it
+    contains examples and the readme.
+
+.. _PyPi: http://pypi.python.org/pypi/pyserial
+
+
+References
+==========
+* Python: http://www.python.org/
+* 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
+
+
+Older Versions
+==============
+Older versions are still available on the `Download Page`_. pySerial 1.21 is
+compatible with Python 2.0 on Windows, Linux and several un*x like systems,
+MacOSX and Jython.
+
+On windows releases older than 2.5 will depend on pywin32_ (previously known as
+win32all)
+
+.. _`Download Page`: http://sourceforge.net/project/showfiles.php?group_id=46487
+.. _pywin32: http://pypi.python.org/pypi/pywin32
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
new file mode 100644
index 0000000..9833254
--- /dev/null
+++ b/documentation/pyserial_api.rst
@@ -0,0 +1,531 @@
+==============
+ pySerial API
+==============
+
+.. module:: serial
+
+Classes
+=======
+
+.. class:: Serial
+
+    .. method:: __init__(port=None, baudrate=9600, bytesize=EIGHTBITS, parity=PARITY_NONE, stopbits=STOPBITS_ONE, timeout=None, xonxoff=0, rtscts=0, interCharTimeout=None)
+
+        :param port:
+            Device name or port number number or :const:`None`.
+
+        :param baudrate:
+            Baud rate such as 9600 or 115200 etc.
+
+        :param bytesize:
+            Number of data bits. Possible values:
+            :const:`FIVEBITS`, :const:`SIXBITS`, :const:`SEVENBITS`,
+            :const:`EIGHTBITS`
+
+        :param parity:
+            Enable parity checking. Possible values:
+            :const:`PARITY_NONE` :const:`PARITY_EVEN` :const:`PARITY_ODD`
+            :const:`PARITY_MARK` :const:`PARITY_SPACE`
+
+        :param stopbits:
+            Number of stop bits. Possible values:
+            :const:`STOPBITS_ONE` :const:`STOPBITS_ONE_POINT_FIVE`
+            :const:`STOPBITS_TWO`
+
+        :param timeout:
+            Set a read timeout value.
+
+        :param xonxoff:
+            Enable software flow control.
+
+        :param rtscts:
+            Enable hardware (RTS/CTS) flow control.
+
+        :param interCharTimeout:
+            Inter-character timeout, :const:`None` to disable (default).
+
+        :exception ValueError:
+            Will be raised when parameter are out of range, e.g. baud rate, data bits.
+
+        :exception SerialException:
+            In case the device can not be found or can not be configured.
+
+
+        The port is immediately opened on object creation, when a *port* is
+        given. It is not opened when *port* is :const:`None` and a successive call
+        to :meth:`open` will be needed.
+
+        Possible values for the parameter *port*:
+
+        - Number: number of device, numbering starts at zero.
+        - Device name: depending on operating system. e.g. ``/dev/ttyUSB0``
+          on GNU/Linux or ``COM3`` on Windows.
+
+        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)
+
+
+    .. method:: open()
+
+        Open port.
+
+    .. method:: close()
+
+        Close port immediately.
+
+
+    The following methods may raise :exc:`ValueError` when applied to a closed
+    port.
+
+    .. method:: read(size=1)
+
+        :param size: Number of bytes to read.
+        :return: Bytes read from the port.
+
+        Read *size* bytes from the serial port. If a timeout is set it may
+        return less characters as requested. With no timeout it will block
+        until the requested number of bytes is read.
+
+        .. versionchanged:: 2.5
+            Returns an instance of :class:`bytes` when available (Python 2.6
+            and newer) and :class:`str` otherwiese.
+
+    .. method:: write(data)
+
+        :param data: Data to send.
+        :return: Number of bytes written.
+        :exception SerialTimeoutException:
+            In case a write timeout is configured for the port and the time is
+            exceeded.
+
+        Write the string *data* to the port.
+
+        .. versionchanged:: 2.5
+            Accepts instances of :class:`bytes` and :class:`bytearray` when
+            available (Python 2.6 and newer) and :class:`str` otherwiese.
+
+    .. method:: inWaiting()
+
+        Return the number of chars in the receive buffer.
+
+    .. method:: flush()
+
+        Flush of file like objects. In this case, wait until all data is
+        written.
+
+    .. method:: flushInput()
+
+        Flush input buffer, discarding all it's contents.
+
+    .. method:: flushOutput()
+
+        Clear output buffer, aborting the current output and
+        discarding all that is in the buffer.
+
+    .. method:: sendBreak(duration=0.25)
+
+        :param duration: Time (float) to activate the BREAK condition.
+
+        Send break condition. Timed, returns to idle state after given
+        duration.
+
+    .. method:: setBreak(level=True)
+
+        :param level: when true activate BREAK condition, else disable.
+
+        Set break: Controls TXD. When active, no transmitting is possible.
+
+    .. method:: setRTS(level=True)
+
+        :param level: Set control line to logic level.
+
+        Set RTS line to specified logic level.
+
+    .. method:: setDTR(level=True)
+
+        :param level: Set control line to logic level.
+
+        Set DTR line to specified logic level.
+
+    .. method:: getCTS()
+
+        :return: Current state (boolean)
+
+        Return the state of the CTS line.
+
+    .. method:: getDSR()
+
+        :return: Current state (boolean)
+
+        Return the state of the DSR line.
+
+    .. method:: getRI()
+
+        :return: Current state (boolean)
+
+        Return the state of the RI line.
+
+    .. method:: getCD()
+
+        :return: Current state (boolean)
+
+        Return the state of the CD line
+
+    Read-only attributes:
+
+    .. attribute:: name
+
+        Device name. This is always the device name even if the
+        port was opened by a number. (Read Only).
+
+        .. versionadded:: 2.5
+
+    .. attribute:: portstr
+
+        :deprecated: use :attr:`name` instead
+
+    .. attribute:: BAUDRATES
+
+        A list of valid baud rates. The list may be incomplete such that higher
+        baud rates may be supported by the device and that values in between the
+        standard baud rates are supported. (Read Only).
+
+    .. attribute:: BYTESIZES
+
+        A list of valid byte sizes for the device (Read Only).
+
+    .. attribute:: PARITIES
+
+        A list of valid parities for the device (Read Only).
+
+    .. attribute:: STOPBITS
+
+        A list of valid stop bit widths for the device (Read Only).
+
+
+    New values can be assigned to the following attributes, the port will be
+    reconfigured, even if it's opened at that time:
+
+    .. attribute:: port
+
+        Port name/number as set by the user.
+
+    .. attribute:: baudrate
+
+        Current baud rate setting.
+
+    .. attribute:: bytesize
+
+        Byte size in bits.
+
+    .. attribute:: parity
+
+        Parity setting.
+
+    .. attribute:: stopbits
+
+        Stop bit with.
+
+    .. attribute:: timeout
+
+        Timeout setting (seconds, float).
+
+    .. attribute:: xonxoff
+
+        If Xon/Xoff flow control is enabled.
+
+    .. attribute:: rtscts
+
+        If hardware flow control is enabled.
+
+    Platform specific methods.
+
+    .. warning:: Programs using the following methods are not portable to other platforms!
+
+    .. 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.
+
+        Return file descriptor number for the port that is opened by this object.
+
+    .. method:: setXON(level=True)
+
+        :platform: Windows
+        :param level: Set flow control state.
+
+        Set software flow control state.
+
+
+.. class:: SerialBase
+
+    The following attributes are implemented as properties. They work with open
+    and closed ports.
+
+    .. attribute:: port
+
+        Read or write port. When the port is already open, it will be closed
+        and reopened with the new setting.
+
+    .. attribute:: baudrate
+
+        Read or write current baud rate setting.
+
+    .. attribute:: bytesize
+
+        Read or write current data byte size setting.
+
+    .. attribute:: parity
+
+        Read or write current parity setting.
+
+    .. attribute:: stopbits
+
+        Read or write current stop bit width setting.
+
+    .. attribute:: timeout
+
+        Read or write current read timeout setting.
+
+    .. attribute:: writeTimeout
+
+        Read or write current write timeout setting.
+
+    .. attribute:: xonxoff
+
+        Read or write current software flow control rate setting.
+
+    .. attribute:: rtscts
+
+        Read or write current hardware flow control setting.
+
+    .. attribute:: dsrdtr
+
+        Read or write current hardware flow control setting.
+
+    .. attribute:: interCharTimeout
+
+        Read or write current inter character timeout setting.
+
+    The following constants are also provided:
+
+    .. attribute:: BAUDRATES
+
+        A tuple of standard baud rate values. The actual device may support more
+        or less...
+
+    .. attribute:: BYTESIZES
+
+        A tuple of supported byte size values.
+
+    .. attribute:: PARITIES
+
+        A tuple of supported parity settings.
+
+    .. attribute:: STOPBITS
+
+        A tuple of supported stop bit settings.
+
+    .. method:: readline(size=None, eol='\\n')
+
+        :param size: Max number of bytes to read, ``None`` -> no limit.
+        :param eol: The end of line character.
+
+        Read a line which is terminated with end-of-line (*eol*) character
+        (``\\n`` by default) or until timeout.
+
+    .. method:: readlines(sizehint=None, eol='\\n')
+
+        :param size: Ignored parameter.
+        :param eol: The end of line character.
+
+        Read a list of lines, until timeout. *sizehint* is ignored and only
+        present for API compatibility with built-in File objects.
+
+    .. method:: xreadlines(sizehint=None)
+
+        Just calls :meth:`readlines` - here for compatibility.
+
+    For compatibility with the :mod:`io` library are the following methods.
+
+    .. method:: readable()
+
+        :return: True
+        .. versionadded:: 2.5
+
+    .. method:: writable()
+
+        :return: True
+        .. versionadded:: 2.5
+
+    .. method:: seekable()
+
+        :return: False
+        .. versionadded:: 2.5
+
+    .. method:: readinto(b)
+
+        :param b: bytearray or array instace
+        :return: Number of byte read
+
+        Read up to len(b) bytes into bytearray b and return the number of bytes read.
+
+        .. versionadded:: 2.5
+
+ 
+.. note::
+
+    For systems that provide the :mod:`io` library (Python 2.6 and newer), the
+    class :class:`Serial` will derrive from :class:`io.RawIOBase`. For all
+    others from :class:`FileLike`.
+
+.. class:: FileLike
+
+    An abstract file like class. It is used as base class for :class:`Serial`.
+
+    This class implements :meth:`readline` and :meth:`readlines` based on read
+    and :meth:`writelines` based on write.  This class is used to provide the
+    above functions for to Serial port objects.
+
+    Note that when the serial port was opened with no timeout that
+    :meth:`readline` blocks until it sees a newline (or the specified size is
+    reached) and that :meth:`readlines` would never return and therefore
+    refuses to work (it raises an exception in this case)!
+
+    .. method:: writelines(sequence)
+
+        Write a list of strings to the port.
+
+
+    The following three methods are overridden in :class:`Serial`.
+
+    .. method:: flush()
+
+        Flush of file like objects. It's a no-op in this class, may be overridden.
+
+    .. method:: read()
+
+        Raises NotImplementedError, needs to be overridden by subclass.
+
+    .. method:: write(data)
+
+        Raises NotImplementedError, needs to be overridden by subclass.
+
+    The following functions are implemented for compatibility with other
+    file-like objects, however serial ports are not seekable.
+
+
+    .. method:: seek(pos, whence=0)
+
+        :exception IOError: always, as method is not supported on serial port
+
+        .. versionadded:: 2.5
+
+    .. method:: tell()
+
+        :exception IOError: always, as method is not supported on serial port
+
+        .. versionadded:: 2.5
+
+    .. method:: truncate(self, n=None)
+
+        :exception IOError: always, as method is not supported on serial port
+
+        .. versionadded:: 2.5
+
+    .. method:: isatty()
+
+        :exception IOError: always, as method is not supported on serial port
+
+        .. versionadded:: 2.5
+
+    To be able to use the file like object as iterator for e.g. 
+    ``for line in Serial(0): ...`` usage:
+
+    .. method:: next()
+
+        Return the next line by calling :meth:`readline`.
+
+    .. method:: __iter__()
+
+        Returns self.
+
+
+
+Exceptions
+==========
+
+.. exception:: SerialException
+
+    Base class for serial port exceptions.
+
+    .. versionchanged:: 2.5
+        Now derrives from :exc:`IOError` instead of :exc:`Exception`
+
+.. exception:: SerialTimeoutException
+
+    Exception that is raised on write timeouts.
+
+
+Constants
+=========
+
+Parity
+------
+.. data:: PARITY_NONE
+.. data:: PARITY_EVEN
+.. data:: PARITY_ODD
+.. data:: PARITY_MARK
+.. data:: PARITY_SPACE
+
+Stop bits
+---------
+.. data:: STOPBITS_ONE
+.. data:: STOPBITS_ONE_POINT_FIVE
+.. data:: STOPBITS_TWO
+
+Byte size
+---------
+.. data:: FIVEBITS
+.. data:: SIXBITS
+.. data:: SEVENBITS
+.. data:: EIGHTBITS
+
+Others
+-------
+Default control characters (instnces of :class:`bytes` for Python 3.0+) for
+software flow control:
+
+.. data:: XON
+.. data:: XOFF
+
+Module version:
+
+.. data:: VERSION
+
+    A string indicating the pySerial version, such as ``2.5``.
+
+Functions:
+
+.. function:: device(number)
+
+    :param number: Port number.
+    :return: String containing device name.
+    :deprecated: Use device names directly.
+
+    Convert a port number to a platform dependent device name. Unfortunately
+    this does not work well for all platforms; e.g. some may miss USB-Serial
+    converters and enumerate only internal serial ports.
+
+    The conversion may be made off-line, that is, there is no guarantee that
+    the returned device name really exists on the system.
diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst
new file mode 100644
index 0000000..048f94d
--- /dev/null
+++ b/documentation/shortintro.rst
@@ -0,0 +1,57 @@
+====================
+ Short introduction
+====================
+
+Opening serial ports
+====================
+
+Open port 0 at "9600,8,N,1", no timeout::
+
+    >>> import serial
+    >>> ser = serial.Serial(0)  # open first serial port
+    >>> print ser.portstr       # check which port was really used
+    >>> ser.write("hello")      # write a string
+    >>> ser.close()             # close port
+
+Open named port at "19200,8,N,1", 1s timeout::
+
+    >>> ser = serial.Serial('/dev/ttyS1', 19200, timeout=1)
+    >>> x = ser.read()          # read one byte
+    >>> s = ser.read(10)        # read up to ten bytes (timeout)
+    >>> line = ser.readline()   # read a '\n' terminated line
+    >>> ser.close()
+
+Open second port at "38400,8,E,1", non blocking HW handshaking::
+
+    >>> ser = serial.Serial(1, 38400, timeout=0,
+    ...                     parity=serial.PARITY_EVEN, rtscts=1)
+    >>> 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()
+    >>> ser.baudrate = 19200
+    >>> ser.port = 0
+    >>> ser
+    Serial<id=0xa81c10, open=False>(port='COM1', baudrate=19200, bytesize=8, parity='N', stopbits=1, timeout=None, xonxoff=0, rtscts=0)
+    >>> ser.open()
+    >>> ser.isOpen()
+    True
+    >>> ser.close()
+    >>> 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.