shorten README.txt to avoid duplication.

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

1 files changed, 25 insertions, 264 deletions

diff --git a/README.txt b/README.txt
index 60793a4..7767da3 100644
--- a/README.txt
+++ b/README.txt
@@ -1,277 +1,38 @@
-========
-pySerial
+==========
+ pySerial
+==========
+
+Overview
 ========
 This module encapsulates the access for the serial port. It provides backends
-for standard Python running on Windows, Linux, BSD (possibly any POSIX
-compliant system), Jython and IronPython. The module named "serial"
+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.txt for more
-details.
+- Project Homepage: http://pyserial.sourceforge.net
+- 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
 
-Project Homepage: http://pyserial.sourceforge.net
-(C) 2001-2008 Chris Liechti <cliechti@gmx.net>
+BSD license, (C) 2001-2009 Chris Liechti <cliechti@gmx.net>
 
 
-Features
---------
-- same class based interface on all supported platforms
-- access to the port settings trough Python 2.2 properties 
-- port numbering starts at zero, no need to know the platform dependant port
-  name in the user program
-- port name can be specified if access through numbering is inappropriate
-- support for different byte sizes, stopbits, parity and flow control
-  with RTS/CTS and/or Xon/Xoff
-- working with or without receive timeout, blocking or non-blocking
-- file like API with "read" and "write" ("readline" etc. also supported)
-- The files in this package are 100% pure Python.
-  They depend on non standard but common packages on Windows (win32all) and
-  Jython (JavaComm). POSIX (Linux, BSD) uses only modules from the standard
-  Python distribution)
-- 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.
+Documentation
+=============
+For API documentation, usage and examples see files in the "documentation"
+directory.  The ".rst" files can be read in any text editor or being converted to
+HTML or PDF using Sphinx. An online HTML version is at
+http://pyserial.sourceforge.net.
 
 
-Requirements
-------------
-- Python 2.2 or newer
-- win32all extensions on Windows
-- "Java Communications" (JavaComm) extension for Java/Jython
+Examples
+========
+Examples and unit tests are in the directory "examples".
 
 
 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.
-
-There is also a Windows installer, but for developers it may be interesting
-to get the source archive anyway, because it contains examples and the readme.
-
-Do also have a look at the example files in the examples directory in the
-source distribution or online in CVS repository.
-
-
-Serial to USB adapters
-----------------------
-Such adapters are reported to work under Mac OSX and Windows. They are
-mapped to a normal COM port under Windows, but on Mac OSX and other platforms
-they have special device names.
-
-Mac OSX: "/dev/[cu|tty].USA<adaptername><USB-part>P<serial-port>.1"
-    e.g. "/dev/cu.USA19QW11P1.1"
-
-Linux: "/dev/usb/ttyUSB[n]" or "/dev/ttyUSB[n]"
-    first for for RedHat, second form for Debian.
-    e.g. "/dev/usb/ttyUSB0"
-
-Either use these names for the serial ports or create a link to the common device
-names like "ln -s /dev/cu.USA19QW11P1.1 /dev/cuaa0" or "ln -s /dev/usb/ttyUSB0
-/dev/ttyS4" etc.
-
-But be aware that the (USB) device file disappears as soon as you unplug the USB
-adapter.
-
-
-Short introduction
-------------------
-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 realy 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
-
-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
-
-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.
-
-
-Parameters for the Serial class::
-
-    ser = serial.Serial(
-        port=None,              # number of device, numbering starts at
-                                # zero. if everything fails, the user
-                                # can specify a device string, note
-                                # that this isn't portable anymore
-                                # if no port is specified an unconfigured
-                                # an closed serial port object is created
-        baudrate=9600,          # baudrate
-        bytesize=EIGHTBITS,     # number of databits
-        parity=PARITY_NONE,     # enable parity checking
-        stopbits=STOPBITS_ONE,  # number of stopbits
-        timeout=None,           # set a timeout value, None to wait forever
-        xonxoff=0,              # enable software flow control
-        rtscts=0,               # enable RTS/CTS flow control
-        writeTimeout=None,      # set a timeout for writes
-    )
-
-The port is immediately opened on object creation, if a port is given.
-It is not opened if port is None.
-
-Options for read timeout::
-
-    timeout=None            #wait forever
-    timeout=0               #non-blocking mode (return immediately on read)
-    timeout=x               #set timeout to x seconds (float allowed)
-
-Options for write timeout::
-
-    writeTimeout=x          #will rise a SerialTimeoutException if the data
-                            #cannot be sent in x seconds
-
-
-Methods of Serial instances::
-
-    open()                  # open port
-    close()                 # close port immediately
-    setBaudrate(baudrate)   # change baud rate on an open port
-    inWaiting()             # return the number of chars in the receive buffer
-    read(size=1)            # read "size" characters
-    write(s)                # write the string s to the port
-    flushInput()            # flush input buffer, discarding all it's contents
-    flushOutput()           # flush output buffer, abort output
-    sendBreak()             # send break condition
-    setRTS(level=1)         # set RTS line to specified logic level
-    setDTR(level=1)         # set DTR line to specified logic level
-    getCTS()                # return the state of the CTS line
-    getDSR()                # return the state of the DSR line
-    getRI()                 # return the state of the RI line
-    getCD()                 # return the state of the CD line
-
-
-Read only Attributes of Serial instances::
-
-    portstr                 # device name
-    BAUDRATES               # list of valid baud rates
-    BYTESIZES               # list of valid byte sizes
-    PARITIES                # list of valid parities
-    STOPBITS                # list of valid stop bit widths
-
-New values can be assigned to the following attributes, the port
-will be reconfigured, even if it's opened at that time (port will be 
-closed and reopened to apply the changes)::
-
-    port                    # port name/number as set by the user
-    baudrate                # current baud rate setting
-    bytesize                # byte size in bits
-    parity                  # parity setting
-    stopbits                # stop bit with (1,2)
-    timeout                 # read timeout setting
-    xonxoff                 # if Xon/Xoff flow control is enabled
-    rtscts                  # if hardware flow control is enabled
-    writeTimeout            # write timeout setting
-
-These attributes also have corresponding getX and setXX methods.
-
-
-Exceptions that can be raised::
-
-    serial.SerialException
-
-
-Constants
-
-parity::
-
-    serial.PARITY_NONE
-    serial.PARITY_EVEN
-    serial.PARITY_ODD
-    
-stopbits::
-
-    serial.STOPBITS_ONE
-    serial.STOPBITS_TWO
-    
-bytesize::
-
-    serial.FIVEBITS
-    serial.SIXBITS
-    serial.SEVENBITS
-    serial.EIGHTBITS
-
-Xon/Xoff characters::
-
-    serial.XON
-    serial.XOFF
-
-Iterator interface
-~~~~~~~~~~~~~~~~~~
-It is possible to iterate over lines coming from a serial port::
-
-    >>> ser = serial.Serial(0, timeout=10)
-    >>> for line in ser:
-    ...     print line
-
-The use is somewhat restricted tough, as many protocols on the wire require
-that commands are sent and answers are read and this one only reads lines.
-
-
-Tips & Tricks
--------------
-- Some protocols need CR LF ("\r\n") as line terminator, not just LF ("\n").
-  Telephone modems with the AT command set are an example of this behaviour.
-
-- Scanning for available serial ports is possible with more or less success on
-  some platforms. Look at the tools from Roger Binns:
-  http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/bitpim/comscan/
-
-- When packaging a project with py2exe, it will likely print a warning about
-  missing modules 'javax.comm'. This warning is uncritical as the module is
-  used in the Jython implementation that is not used but packaged.
-
-  It can be avoided with::
-
-    setup(...
-        options = {'py2exe': {'excludes': ['javax.comm']}})
-
-  See also setup_demo.py in the examples.
-
-
-References
-----------
-- Python: http://www.python.org
-- Jython: http://www.jython.org
-- win32all: http://starship.python.net/crew/mhammond/
-  and http://www.activestate.com/Products/ActivePython/win32all.html
-- 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
+============
+Detailed information can be found in "documentation/pyserial.rst".
 
+The usual setup.py for Python libraries is used for the source distribution.
+Windows installers are also available (see download link above).