doc update: reorganize chapters/files

5 files changed, 397 insertions, 378 deletions

diff --git a/documentation/examples.rst b/documentation/examples.rst
index 5c51ef6..1114a18 100644
--- a/documentation/examples.rst
+++ b/documentation/examples.rst
@@ -4,107 +4,11 @@
  Examples
 ==========
 
-.. _miniterm:
 
 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 may inherit 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.
-
-Miniterm supports :rfc:`2217` remote serial ports and raw sockets using :ref:`URLs`
-such as ``rfc2217:://<host>:<port>`` respectively ``socket://<host>:<port>`` as
-*port* argument when invoking.
-
-Command line options ``python -m serial.tools.miniterm -h``::
-
-    usage: miniterm.py [-h] [--parity {N,E,O,S,M}] [--rtscts] [--xonxoff]
-                       [--rts RTS] [--dtr DTR] [-e] [--encoding CODEC] [-f NAME]
-                       [--eol {CR,LF,CRLF}] [--raw] [--exit-char NUM]
-                       [--menu-char NUM] [-q] [--develop]
-                       [port] [baudrate]
-
-    Miniterm - A simple terminal program for the serial port.
-
-    positional arguments:
-      port                  serial port name
-      baudrate              set baud rate, default: 9600
-
-    optional arguments:
-      -h, --help            show this help message and exit
-
-    port settings:
-      --parity {N,E,O,S,M}  set parity, one of {N E O S M}, default: N
-      --rtscts              enable RTS/CTS flow control (default off)
-      --xonxoff             enable software flow control (default off)
-      --rts RTS             set initial RTS line state (possible values: 0, 1)
-      --dtr DTR             set initial DTR line state (possible values: 0, 1)
-
-    data handling:
-      -e, --echo            enable local echo (default off)
-      --encoding CODEC      set the encoding for the serial port (e.g. hexlify,
-                            Latin1, UTF-8), default: UTF-8
-      -f NAME, --filter NAME
-                            add text transformation
-      --eol {CR,LF,CRLF}    end of line mode
-      --raw                 Do no apply any encodings/transformations
-
-    hotkeys:
-      --exit-char NUM       Unicode of special character that is used to exit the
-                            application, default: 29
-      --menu-char NUM       Unicode code of special character that is used to
-                            control miniterm (menu), default: 20
-
-    diagnostics:
-      -q, --quiet           suppress non-error messages
-      --develop             show Python traceback on error
-
-
-Miniterm supports some control functions. Typing :kbd:`Ctrl+T Ctrl+H` when it is
-running shows the help text::
-
-    --- pySerial (3.0a) - 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 itself to remote
-    ---    Ctrl+I  Show info
-    ---    Ctrl+U  Upload file (prompt will be shown)
-    ---    Ctrl+A  encoding
-    ---    Ctrl+F  edit filters
-    --- Toggles:
-    ---    Ctrl+R  RTS   Ctrl+D  DTR   Ctrl+B  BREAK
-    ---    Ctrl+E  echo  Ctrl+L  EOL
-    ---
-    --- Port settings (Ctrl+T followed by the following):
-    ---    p          change port
-    ---    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
-
-.. versionchanged:: 2.5
-    Added :kbd:`Ctrl+T` menu and added support for opening URLs.
-.. versionchanged:: 2.6
-    File moved from the examples to :mod:`serial.tools.miniterm`.
-.. versionchanged:: 3.0
-    Apply encoding on serial port, convert to Unicode for console.
-    Added new filters, default to stripping terminal control sequences.
+Miniterm is now available as module instead of example.
+see :ref:`miniterm` for details.
 
 miniterm.py_
     The miniterm program.
diff --git a/documentation/index.rst b/documentation/index.rst
index 9a258fe..e1699f5 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -25,8 +25,10 @@ Contents:
 
     pyserial
     shortintro
-    examples
     pyserial_api
+    tools
+    url_handlers
+    examples
     appendix
 
 Indices and tables
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index 85dd53a..005eeda 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -47,10 +47,10 @@ Native ports
         :param bool dsrdtr:
             Enable hardware (DSR/DTR) flow control.
 
-        :param float write_timeout
+        :param float write_timeout:
             Set a write timeout value.
 
-        :param float inter_byte_timeout
+        :param float inter_byte_timeout:
             Inter-character timeout, :const:`None` to disable (default).
 
         :exception ValueError:
@@ -890,17 +890,6 @@ Module functions and attributes
 
 .. 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.
-
     .. versionchanged:: 3.0 removed, use ``serial.tools.list_ports`` instead
 
 
@@ -913,7 +902,7 @@ Module functions and attributes
     Get a native or a :rfc:`2217` implementation of the Serial class, depending
     on port/url. This factory function is useful when an application wants
     to support both, local ports and remote ports. There is also support
-    for other types, see :ref:`URL <URLs>` section below.
+    for other types, see :ref:`URL <URLs>` section.
 
     The port is not opened when a keyword parameter called *do_not_open* is
     given and true, by default it is opened.
@@ -967,190 +956,15 @@ Module functions and attributes
     .. versionadded:: 3.0
 
 
-.. _URLs:
-
-URLs
-----
-The function :func:`serial_for_url` accepts the following types of URLs:
-
-- ``rfc2217://<host>:<port>[?<option>[&<option>...]]``
-- ``socket://<host>:<port>[?logging={debug|info|warning|error}]``
-- ``loop://[?logging={debug|info|warning|error}]``
-- ``hwgrep://<regexp>``
-- ``spy://port[?option[=value][&option[=value]]]``
-
-.. versionchanged:: 3.0 Options are specified with ``?`` and ``&`` instead of ``/``
-
-Device names are also supported, e.g.:
-
-- ``/dev/ttyUSB0`` (Linux)
-- ``COM3`` (Windows)
-
-Future releases of pySerial might add more types. Since pySerial 2.6 it is also
-possible for the user to add protocol handlers using
-:attr:`protocol_handler_packages`.
-
-``rfc2217://``
-    Used to connect to :rfc:`2217` compatible servers. All serial port
-    functions are supported. Implemented by :class:`rfc2217.Serial`.
-
-    Supported options in the URL are:
-
-    - ``ign_set_control`` does not wait for acknowledges to SET_CONTROL. This
-      option can be used for non compliant servers (i.e. when getting an
-      ``remote rejected value for option 'control'`` error when connecting).
-
-    - ``poll_modem``: The client issues NOTIFY_MODEMSTATE requests when status
-      lines are read (CTS/DTR/RI/CD). Without this option it relies on the server
-      sending the notifications automatically (that's what the RFC suggests and
-      most servers do). Enable this option when :attr:`cts` does not work as
-      expected, i.e. for servers that do not send notifications.
-
-    - ``timeout=<value>``: Change network timeout (default 3 seconds). This is
-      useful when the server takes a little more time to send its answers. The
-      timeout applies to the initial Telnet / :rfc:`2271` negotiation as well
-      as changing port settings or control line change commands.
-
-    - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
-      useful for end users). It uses the logging module and a logger called
-      ``pySerial.rfc2217`` so that the application can setup up logging
-      handlers etc. It will call :meth:`logging.basicConfig` which initializes
-      for output on ``sys.stderr`` (if no logging was set up already).
-
-``socket://``
-    The purpose of this connection type is that applications using pySerial can
-    connect to TCP/IP to serial port converters that do not support :rfc:`2217`.
-
-    Uses a TCP/IP socket. All serial port settings, control and status lines
-    are ignored. Only data is transmitted and received.
-
-    Supported options in the URL are:
-
-    - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
-      useful for end users). It uses the logging module and a logger called
-      ``pySerial.socket`` so that the application can setup up logging handlers
-      etc. It will call :meth:`logging.basicConfig` which initializes for
-      output on ``sys.stderr`` (if no logging was set up already).
-
-``loop://``
-    The least useful type. It simulates a loop back connection
-    (``RX<->TX``  ``RTS<->CTS``  ``DTR<->DSR``). It could be used to test
-    applications or run the unit tests.
-
-    Supported options in the URL are:
-
-    - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
-      useful for end users). It uses the logging module and a logger called
-      ``pySerial.loop`` so that the application can setup up logging handlers
-      etc. It will call :meth:`logging.basicConfig` which initializes for
-      output on ``sys.stderr`` (if no logging was set up already).
-
-``hwgrep://``
-    This type uses :mod:`serial.tools.list_ports` to obtain a list of ports and
-    searches the list for matches by a regexp (see :py:mod:`re`) that follows
-    the slashes.
-
-    Depending on the capabilities of the list_ports module on the system, it is
-    possible to search for the description or hardware ID of a device, e.g. USB
-    VID:PID or texts.
-
-    Unfortunately, on some systems list_ports only lists a subset of the port
-    names with no additional information. Currently, on Windows and Linux and
-    OSX it should find additional information.
-
-``spy://``
-    Wrapping the native serial port, this protocol makes it possible to
-    intercept the data received and transmitted as well as the access to the
-    control lines, break and flush commands.
-
-    Supported options in the URL are:
-
-    - ``file=FILENAME`` output to given file or device instead of stderr
-    - ``color`` enable ANSI escape sequences to colorize output
-    - ``raw`` output the read and written data directly (default is to create a
-      hex dump). In this mode, no control line and other commands are logged.
-    - ``all`` also show ``in_waiting`` and empty ``read()`` calls (hidden by
-      default because of high traffic).
-
-    Example::
-
-        import serial
-
-        with serial.serial_for_url('spy:///dev/ttyUSB0?file=test.txt', timeout=1) as s:
-            s.dtr = False
-            s.write('hello world')
-            s.read(20)
-            s.dtr = True
-            s.write(serial.to_bytes(range(256)))
-            s.read(400)
-            s.send_break()
-
-        with open('test.txt') as f:
-            print(f.read())
-
-    Outputs::
-
-        000000.002 Q-RX reset_input_buffer
-        000000.002 DTR  inactive
-        000000.002 TX   0000  68 65 6C 6C 6F 20 77 6F  72 6C 64                 hello world     
-        000001.015 RX   0000  68 65 6C 6C 6F 20 77 6F  72 6C 64                 hello world     
-        000001.015 DTR  active
-        000001.015 TX   0000  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F  ................
-        000001.015 TX   0010  10 11 12 13 14 15 16 17  18 19 1A 1B 1C 1D 1E 1F  ................
-        000001.015 TX   0020  20 21 22 23 24 25 26 27  28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
-        000001.015 TX   0030  30 31 32 33 34 35 36 37  38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
-        000001.015 TX   0040  40 41 42 43 44 45 46 47  48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
-        000001.016 TX   0050  50 51 52 53 54 55 56 57  58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
-        000001.016 TX   0060  60 61 62 63 64 65 66 67  68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
-        000001.016 TX   0070  70 71 72 73 74 75 76 77  78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
-        000001.016 TX   0080  80 81 82 83 84 85 86 87  88 89 8A 8B 8C 8D 8E 8F  ................
-        000001.016 TX   0090  90 91 92 93 94 95 96 97  98 99 9A 9B 9C 9D 9E 9F  ................
-        000001.016 TX   00A0  A0 A1 A2 A3 A4 A5 A6 A7  A8 A9 AA AB AC AD AE AF  ................
-        000001.016 TX   00B0  B0 B1 B2 B3 B4 B5 B6 B7  B8 B9 BA BB BC BD BE BF  ................
-        000001.016 TX   00C0  C0 C1 C2 C3 C4 C5 C6 C7  C8 C9 CA CB CC CD CE CF  ................
-        000001.016 TX   00D0  D0 D1 D2 D3 D4 D5 D6 D7  D8 D9 DA DB DC DD DE DF  ................
-        000001.016 TX   00E0  E0 E1 E2 E3 E4 E5 E6 E7  E8 E9 EA EB EC ED EE EF  ................
-        000001.016 TX   00F0  F0 F1 F2 F3 F4 F5 F6 F7  F8 F9 FA FB FC FD FE FF  ................
-        000002.284 RX   0000  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F  ................
-        000002.284 RX   0010  10 11 12 13 14 15 16 17  18 19 1A 1B 1C 1D 1E 1F  ................
-        000002.284 RX   0020  20 21 22 23 24 25 26 27  28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
-        000002.284 RX   0030  30 31 32 33 34 35 36 37  38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
-        000002.284 RX   0040  40 41 42 43 44 45 46 47  48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
-        000002.284 RX   0050  50 51 52 53 54 55 56 57  58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
-        000002.284 RX   0060  60 61 62 63 64 65 66 67  68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
-        000002.284 RX   0070  70 71 72 73 74 75 76 77  78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
-        000002.284 RX   0080  80 81 82 83 84 85 86 87  88 89 8A 8B 8C 8D 8E 8F  ................
-        000002.284 RX   0090  90 91 92 93 94 95 96 97  98 99 9A 9B 9C 9D 9E 9F  ................
-        000002.284 RX   00A0  A0 A1 A2 A3 A4 A5 A6 A7  A8 A9 AA AB AC AD AE AF  ................
-        000002.284 RX   00B0  B0 B1 B2 B3 B4 B5 B6 B7  B8 B9 BA BB BC BD BE BF  ................
-        000002.284 RX   00C0  C0 C1 C2 C3 C4 C5 C6 C7  C8 C9 CA CB CC CD CE CF  ................
-        000002.284 RX   00D0  D0 D1 D2 D3 D4 D5 D6 D7  D8 D9 DA DB DC DD DE DF  ................
-        000002.284 RX   00E0  E0 E1 E2 E3 E4 E5 E6 E7  E8 E9 EA EB EC ED EE EF  ................
-        000002.284 RX   00F0  F0 F1 F2 F3 F4 F5 F6 F7  F8 F9 FA FB FC FD FE FF  ................
-        000002.284 BRK  send_break 0.25
-
-    .. versionadded:: 3.0
-
-
-
-Examples:
-
-- ``rfc2217://localhost:7000``
-- ``rfc2217://localhost:7000?poll_modem``
-- ``rfc2217://localhost:7000?ign_set_control&timeout=5.5``
-- ``socket://localhost:7777``
-- ``loop://?logging=debug``
-- ``hwgrep://0451:f432`` (USB VID:PID)
-- ``spy://COM54?file=log.txt``
-
-
 asyncio
 =======
 
+.. module:: serial.aio
+
 .. warning:: This implementation is currently in an experimental state. Use
     at your own risk.
 
-Experimental asyncio support is available for Python 3.4 and newer. The
+Experimental asyncio support is available for Python 3.4 and newer. The module
 :mod:`serial.aio` provides a :class:`asyncio.Transport`:
 ``SerialTransport``.
 
@@ -1173,7 +987,7 @@ Example::
         def connection_made(self, transport):
             self.transport = transport
             print('port opened', transport)
-            transport.serial.setRTS(0)
+            transport.serial.rts = False
             transport.write(b'hello world\n')
 
         def data_received(self, data):
@@ -1185,93 +999,8 @@ Example::
             asyncio.get_event_loop().stop()
 
     loop = asyncio.get_event_loop()
-    coro = create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
+    coro = serial.aio.create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
     loop.run_until_complete(coro)
     loop.run_forever()
     loop.close()
 
-
-Tools
-=====
-
-serial.tools.list_ports
------------------------
-.. module:: serial.tools.list_ports
-.. versionadded:: 2.6
-
-This module can be executed to get a list of ports (``python -m
-serial.tools.list_ports``). It also contains the following functions.
-
-
-.. function:: comports()
-
-    :return: an iterable.
-
-    The function returns an iterable that yields tuples of three strings:
-
-    - port name as it can be passed to :class:`serial.Serial` or
-      :func:`serial.serial_for_url`
-    - description in human readable form
-    - sort of hardware ID. E.g. may contain VID:PID of USB-serial adapters.
-
-    Items are returned in no particular order. It may make sense to sort the
-    items. Also note that the reported strings are different across platforms
-    and operating systems, even for the same device.
-
-    .. note:: Support is limited to a number of operating systems. On some
-              systems description and hardware ID will not be available
-              (``None``).
-
-    :platform: Posix (/dev files)
-    :platform: Linux (/dev files, sysfs and lsusb)
-    :platform: OSX (iokit)
-    :platform: Windows (setupapi, registry)
-
-
-.. function:: grep(regexp)
-
-    :param regexp: regular expression (see stdlib :mod:`re`)
-    :return: filtered sequence, see :func:`comports`.
-
-    Search for ports using a regular expression. Port name, description and
-    hardware ID are searched (case insensitive). The function returns an
-    iterable that contains the same tuples that :func:`comport` generates but
-    only those that match the regexp.
-
-
-Command line usage
-
-Help for ``python -m serial.tools.list_ports``::
-
-    usage: list_ports.py [-h] [-v] [-q] [-n N] [regexp]
-
-    Serial port enumeration
-
-    positional arguments:
-      regexp         only show ports that match this regex
-
-    optional arguments:
-      -h, --help     show this help message and exit
-      -v, --verbose  show more messages
-      -q, --quiet    suppress all messages
-      -n N           only output the N-th entry
-
-Examples:
-
-- List all ports with details::
-
-    python -m serial.tools.list_ports -v
-
-- List the 2nd port matching a USB VID:PID pattern::
-
-    python -m serial.tools.list_ports 1234:5678 -q -n 2
-
-
-serial.tools.miniterm
----------------------
-.. module:: serial.tools.miniterm
-.. versionadded:: 2.6
-
-Miniterm is now available as module instead of example.
-see :ref:`miniterm` for details.
-
diff --git a/documentation/tools.rst b/documentation/tools.rst
new file mode 100644
index 0000000..962c98b
--- /dev/null
+++ b/documentation/tools.rst
@@ -0,0 +1,184 @@
+=======
+ Tools
+=======
+
+.. module:: serial
+
+serial.tools.list_ports
+=======================
+.. module:: serial.tools.list_ports
+
+This module can be executed to get a list of ports (``python -m
+serial.tools.list_ports``). It also contains the following functions.
+
+
+.. function:: comports()
+
+    :return: an iterable.
+
+    The function returns an iterable that yields tuples of three strings:
+
+    - port name as it can be passed to :class:`serial.Serial` or
+      :func:`serial.serial_for_url`
+    - description in human readable form
+    - sort of hardware ID. E.g. may contain VID:PID of USB-serial adapters.
+
+    Items are returned in no particular order. It may make sense to sort the
+    items. Also note that the reported strings are different across platforms
+    and operating systems, even for the same device.
+
+    .. note:: Support is limited to a number of operating systems. On some
+              systems description and hardware ID will not be available
+              (``None``).
+
+    :platform: Posix (/dev files)
+    :platform: Linux (/dev files, sysfs and lsusb)
+    :platform: OSX (iokit)
+    :platform: Windows (setupapi, registry)
+
+
+.. function:: grep(regexp)
+
+    :param regexp: regular expression (see stdlib :mod:`re`)
+    :return: filtered sequence, see :func:`comports`.
+
+    Search for ports using a regular expression. Port name, description and
+    hardware ID are searched (case insensitive). The function returns an
+    iterable that contains the same tuples that :func:`comport` generates but
+    only those that match the regexp.
+
+
+Command line usage
+
+Help for ``python -m serial.tools.list_ports``::
+
+    usage: list_ports.py [-h] [-v] [-q] [-n N] [regexp]
+
+    Serial port enumeration
+
+    positional arguments:
+      regexp         only show ports that match this regex
+
+    optional arguments:
+      -h, --help     show this help message and exit
+      -v, --verbose  show more messages
+      -q, --quiet    suppress all messages
+      -n N           only output the N-th entry
+
+Examples:
+
+- List all ports with details::
+
+    python -m serial.tools.list_ports -v
+
+- List the 2nd port matching a USB VID:PID pattern::
+
+    python -m serial.tools.list_ports 1234:5678 -q -n 2
+
+.. versionadded:: 2.6
+
+
+.. _miniterm:
+
+serial.tools.miniterm
+=====================
+.. module:: serial.tools.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 may inherit 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.
+
+Miniterm supports :rfc:`2217` remote serial ports and raw sockets using :ref:`URLs`
+such as ``rfc2217:://<host>:<port>`` respectively ``socket://<host>:<port>`` as
+*port* argument when invoking.
+
+Command line options ``python -m serial.tools.miniterm -h``::
+
+    usage: miniterm.py [-h] [--parity {N,E,O,S,M}] [--rtscts] [--xonxoff]
+                       [--rts RTS] [--dtr DTR] [-e] [--encoding CODEC] [-f NAME]
+                       [--eol {CR,LF,CRLF}] [--raw] [--exit-char NUM]
+                       [--menu-char NUM] [-q] [--develop]
+                       [port] [baudrate]
+
+    Miniterm - A simple terminal program for the serial port.
+
+    positional arguments:
+      port                  serial port name
+      baudrate              set baud rate, default: 9600
+
+    optional arguments:
+      -h, --help            show this help message and exit
+
+    port settings:
+      --parity {N,E,O,S,M}  set parity, one of {N E O S M}, default: N
+      --rtscts              enable RTS/CTS flow control (default off)
+      --xonxoff             enable software flow control (default off)
+      --rts RTS             set initial RTS line state (possible values: 0, 1)
+      --dtr DTR             set initial DTR line state (possible values: 0, 1)
+
+    data handling:
+      -e, --echo            enable local echo (default off)
+      --encoding CODEC      set the encoding for the serial port (e.g. hexlify,
+                            Latin1, UTF-8), default: UTF-8
+      -f NAME, --filter NAME
+                            add text transformation
+      --eol {CR,LF,CRLF}    end of line mode
+      --raw                 Do no apply any encodings/transformations
+
+    hotkeys:
+      --exit-char NUM       Unicode of special character that is used to exit the
+                            application, default: 29
+      --menu-char NUM       Unicode code of special character that is used to
+                            control miniterm (menu), default: 20
+
+    diagnostics:
+      -q, --quiet           suppress non-error messages
+      --develop             show Python traceback on error
+
+
+Miniterm supports some control functions. Typing :kbd:`Ctrl+T Ctrl+H` when it is
+running shows the help text::
+
+    --- pySerial (3.0a) - 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 itself to remote
+    ---    Ctrl+I  Show info
+    ---    Ctrl+U  Upload file (prompt will be shown)
+    ---    Ctrl+A  encoding
+    ---    Ctrl+F  edit filters
+    --- Toggles:
+    ---    Ctrl+R  RTS   Ctrl+D  DTR   Ctrl+B  BREAK
+    ---    Ctrl+E  echo  Ctrl+L  EOL
+    ---
+    --- Port settings (Ctrl+T followed by the following):
+    ---    p          change port
+    ---    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
+
+.. versionchanged:: 2.5
+    Added :kbd:`Ctrl+T` menu and added support for opening URLs.
+.. versionchanged:: 2.6
+    File moved from the examples to :mod:`serial.tools.miniterm`.
+.. versionchanged:: 3.0
+    Apply encoding on serial port, convert to Unicode for console.
+    Added new filters, default to stripping terminal control sequences.
+
diff --git a/documentation/url_handlers.rst b/documentation/url_handlers.rst
new file mode 100644
index 0000000..9814f24
--- /dev/null
+++ b/documentation/url_handlers.rst
@@ -0,0 +1,200 @@
+==============
+ URL Handlers
+==============
+
+.. module:: serial
+
+.. _URLs:
+
+Overview
+========
+The function :func:`serial_for_url` accepts the following types of URLs:
+
+- ``rfc2217://<host>:<port>[?<option>[&<option>...]]``
+- ``socket://<host>:<port>[?logging={debug|info|warning|error}]``
+- ``loop://[?logging={debug|info|warning|error}]``
+- ``hwgrep://<regexp>``
+- ``spy://port[?option[=value][&option[=value]]]``
+
+.. versionchanged:: 3.0 Options are specified with ``?`` and ``&`` instead of ``/``
+
+Device names are also supported, e.g.:
+
+- ``/dev/ttyUSB0`` (Linux)
+- ``COM3`` (Windows)
+
+Future releases of pySerial might add more types. Since pySerial 2.6 it is also
+possible for the user to add protocol handlers using
+:attr:`protocol_handler_packages`.
+
+
+``rfc2217://``
+==============
+Used to connect to :rfc:`2217` compatible servers. All serial port
+functions are supported. Implemented by :class:`rfc2217.Serial`.
+
+Supported options in the URL are:
+
+- ``ign_set_control`` does not wait for acknowledges to SET_CONTROL. This
+  option can be used for non compliant servers (i.e. when getting an
+  ``remote rejected value for option 'control'`` error when connecting).
+
+- ``poll_modem``: The client issues NOTIFY_MODEMSTATE requests when status
+  lines are read (CTS/DTR/RI/CD). Without this option it relies on the server
+  sending the notifications automatically (that's what the RFC suggests and
+  most servers do). Enable this option when :attr:`cts` does not work as
+  expected, i.e. for servers that do not send notifications.
+
+- ``timeout=<value>``: Change network timeout (default 3 seconds). This is
+  useful when the server takes a little more time to send its answers. The
+  timeout applies to the initial Telnet / :rfc:`2271` negotiation as well
+  as changing port settings or control line change commands.
+
+- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
+  useful for end users). It uses the logging module and a logger called
+  ``pySerial.rfc2217`` so that the application can setup up logging
+  handlers etc. It will call :meth:`logging.basicConfig` which initializes
+  for output on ``sys.stderr`` (if no logging was set up already).
+
+.. warning:: The connection is not encrypted and no authentication is
+             supported! Only use it in trusted environments.
+
+
+``socket://``
+=============
+The purpose of this connection type is that applications using pySerial can
+connect to TCP/IP to serial port converters that do not support :rfc:`2217`.
+
+Uses a TCP/IP socket. All serial port settings, control and status lines
+are ignored. Only data is transmitted and received.
+
+Supported options in the URL are:
+
+- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
+  useful for end users). It uses the logging module and a logger called
+  ``pySerial.socket`` so that the application can setup up logging handlers
+  etc. It will call :meth:`logging.basicConfig` which initializes for
+  output on ``sys.stderr`` (if no logging was set up already).
+
+.. warning:: The connection is not encrypted and no authentication is
+             supported! Only use it in trusted environments.
+
+
+``loop://``
+===========
+The least useful type. It simulates a loop back connection
+(``RX<->TX``  ``RTS<->CTS``  ``DTR<->DSR``). It could be used to test
+applications or run the unit tests.
+
+Supported options in the URL are:
+
+- ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
+  useful for end users). It uses the logging module and a logger called
+  ``pySerial.loop`` so that the application can setup up logging handlers
+  etc. It will call :meth:`logging.basicConfig` which initializes for
+  output on ``sys.stderr`` (if no logging was set up already).
+
+
+``hwgrep://``
+=============
+This type uses :mod:`serial.tools.list_ports` to obtain a list of ports and
+searches the list for matches by a regexp (see :py:mod:`re`) that follows
+the slashes.
+
+Depending on the capabilities of the list_ports module on the system, it is
+possible to search for the description or hardware ID of a device, e.g. USB
+VID:PID or texts.
+
+Unfortunately, on some systems list_ports only lists a subset of the port
+names with no additional information. Currently, on Windows and Linux and
+OSX it should find additional information.
+
+
+``spy://``
+==========
+Wrapping the native serial port, this protocol makes it possible to
+intercept the data received and transmitted as well as the access to the
+control lines, break and flush commands. It is mainly used to debug
+applications.
+
+Supported options in the URL are:
+
+- ``file=FILENAME`` output to given file or device instead of stderr
+- ``color`` enable ANSI escape sequences to colorize output
+- ``raw`` output the read and written data directly (default is to create a
+  hex dump). In this mode, no control line and other commands are logged.
+- ``all`` also show ``in_waiting`` and empty ``read()`` calls (hidden by
+  default because of high traffic).
+
+Example::
+
+    import serial
+
+    with serial.serial_for_url('spy:///dev/ttyUSB0?file=test.txt', timeout=1) as s:
+        s.dtr = False
+        s.write('hello world')
+        s.read(20)
+        s.dtr = True
+        s.write(serial.to_bytes(range(256)))
+        s.read(400)
+        s.send_break()
+
+    with open('test.txt') as f:
+        print(f.read())
+
+Outputs::
+
+    000000.002 Q-RX reset_input_buffer
+    000000.002 DTR  inactive
+    000000.002 TX   0000  68 65 6C 6C 6F 20 77 6F  72 6C 64                 hello world     
+    000001.015 RX   0000  68 65 6C 6C 6F 20 77 6F  72 6C 64                 hello world     
+    000001.015 DTR  active
+    000001.015 TX   0000  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F  ................
+    000001.015 TX   0010  10 11 12 13 14 15 16 17  18 19 1A 1B 1C 1D 1E 1F  ................
+    000001.015 TX   0020  20 21 22 23 24 25 26 27  28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
+    000001.015 TX   0030  30 31 32 33 34 35 36 37  38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
+    000001.015 TX   0040  40 41 42 43 44 45 46 47  48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
+    000001.016 TX   0050  50 51 52 53 54 55 56 57  58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
+    000001.016 TX   0060  60 61 62 63 64 65 66 67  68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
+    000001.016 TX   0070  70 71 72 73 74 75 76 77  78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
+    000001.016 TX   0080  80 81 82 83 84 85 86 87  88 89 8A 8B 8C 8D 8E 8F  ................
+    000001.016 TX   0090  90 91 92 93 94 95 96 97  98 99 9A 9B 9C 9D 9E 9F  ................
+    000001.016 TX   00A0  A0 A1 A2 A3 A4 A5 A6 A7  A8 A9 AA AB AC AD AE AF  ................
+    000001.016 TX   00B0  B0 B1 B2 B3 B4 B5 B6 B7  B8 B9 BA BB BC BD BE BF  ................
+    000001.016 TX   00C0  C0 C1 C2 C3 C4 C5 C6 C7  C8 C9 CA CB CC CD CE CF  ................
+    000001.016 TX   00D0  D0 D1 D2 D3 D4 D5 D6 D7  D8 D9 DA DB DC DD DE DF  ................
+    000001.016 TX   00E0  E0 E1 E2 E3 E4 E5 E6 E7  E8 E9 EA EB EC ED EE EF  ................
+    000001.016 TX   00F0  F0 F1 F2 F3 F4 F5 F6 F7  F8 F9 FA FB FC FD FE FF  ................
+    000002.284 RX   0000  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F  ................
+    000002.284 RX   0010  10 11 12 13 14 15 16 17  18 19 1A 1B 1C 1D 1E 1F  ................
+    000002.284 RX   0020  20 21 22 23 24 25 26 27  28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
+    000002.284 RX   0030  30 31 32 33 34 35 36 37  38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
+    000002.284 RX   0040  40 41 42 43 44 45 46 47  48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
+    000002.284 RX   0050  50 51 52 53 54 55 56 57  58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
+    000002.284 RX   0060  60 61 62 63 64 65 66 67  68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
+    000002.284 RX   0070  70 71 72 73 74 75 76 77  78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
+    000002.284 RX   0080  80 81 82 83 84 85 86 87  88 89 8A 8B 8C 8D 8E 8F  ................
+    000002.284 RX   0090  90 91 92 93 94 95 96 97  98 99 9A 9B 9C 9D 9E 9F  ................
+    000002.284 RX   00A0  A0 A1 A2 A3 A4 A5 A6 A7  A8 A9 AA AB AC AD AE AF  ................
+    000002.284 RX   00B0  B0 B1 B2 B3 B4 B5 B6 B7  B8 B9 BA BB BC BD BE BF  ................
+    000002.284 RX   00C0  C0 C1 C2 C3 C4 C5 C6 C7  C8 C9 CA CB CC CD CE CF  ................
+    000002.284 RX   00D0  D0 D1 D2 D3 D4 D5 D6 D7  D8 D9 DA DB DC DD DE DF  ................
+    000002.284 RX   00E0  E0 E1 E2 E3 E4 E5 E6 E7  E8 E9 EA EB EC ED EE EF  ................
+    000002.284 RX   00F0  F0 F1 F2 F3 F4 F5 F6 F7  F8 F9 FA FB FC FD FE FF  ................
+    000002.284 BRK  send_break 0.25
+
+.. versionadded:: 3.0
+
+
+Examples
+========
+
+- ``rfc2217://localhost:7000``
+- ``rfc2217://localhost:7000?poll_modem``
+- ``rfc2217://localhost:7000?ign_set_control&timeout=5.5``
+- ``socket://localhost:7777``
+- ``loop://?logging=debug``
+- ``hwgrep://0451:f432`` (USB VID:PID)
+- ``spy://COM54?file=log.txt``
+
+