doc update

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

2 files changed, 38 insertions, 32 deletions

diff --git a/documentation/appendix.rst b/documentation/appendix.rst
index 6c43981..2c3a549 100644
--- a/documentation/appendix.rst
+++ b/documentation/appendix.rst
@@ -34,36 +34,9 @@ Test your setup.
     though).
 
 
-URL handlers
-============
-``serial_for_url`` can be used to access "virtual" serial ports identified by
-an URL scheme. E.g. for the RFC 2217, ``rfc2217:://``.
-
-Custom URL handlers can be added in the ``serial.urlhandler`` directory.
-Modules must be named ``protocol_xxx.py`` where ``xxx`` is the part that is
-used in the URL (``xxx://``).
-
-This is possible starting from pySerial V2.6.
-
-
-py2exe
-======
-py2exe and similar packaging programs scan the sources for import statements
-and create a list of modules that they package. pySerial may create two issues
-with that:
-
-- implementations for other modules are found. On Windows, it's safe to exclude
-  'serialposix', 'serialjava' and 'serialcli' as these are not used.
-
-- ``serial_for_url`` does a dynamic lookup of protocol handlers at runtime.
-  If this function is used, the desired handlers have to be included manually
-  (e.g. 'serial.urlhandler.protocol_socket',
-  'serial.urlhandler.protocol_rfc2217', etc.)
-
-
 FAQ
 ===
-Example works in miniterm but not in script.
+Example works in :ref:`miniterm` but not in script.
     The RTS and DTR lines are switched when the port is opened. This may cause
     some processing or reset on the connected device. In such a cases an
     immediately following call to :meth:`write` may not be received by the
@@ -73,6 +46,32 @@ Example works in miniterm but not in script.
     recommended in this situation. E.g. a ``time.sleep(1)``
 
 
+Application works when .py file is run, but fails when packaged (py2exe etc.)
+    py2exe and similar packaging programs scan the sources for import
+    statements and create a list of modules that they package. pySerial may
+    create two issues with that:
+
+    - implementations for other modules are found. On Windows, it's safe to
+      exclude 'serialposix', 'serialjava' and 'serialcli' as these are not
+      used.
+
+    - :func:`serial.serial_for_url` does a dynamic lookup of protocol handlers
+      at runtime.  If this function is used, the desired handlers have to be
+      included manually (e.g. 'serial.urlhandler.protocol_socket',
+      'serial.urlhandler.protocol_rfc2217', etc.). This can be done either with
+      the "includes" option in ``setup.py`` or by a dummy import in one of the
+      packaged modules.
+
+User supplied URL handlers
+    :func:`serial.serial_for_url` can be used to access "virtual" serial ports
+    identified by an :ref:`URL <URLs>` scheme. E.g. for the :rfc:`2217`:
+    ``rfc2217:://``.
+
+    Custom :ref:`URL <URLs>` handlers can be added by extending the module
+    search path in :data:`serial.protocol_handler_packages`. This is possible
+    starting from pySerial V2.6.
+
+
 Related software
 ================
 
@@ -83,7 +82,7 @@ com0com - http://com0com.sourceforge.net/
 License
 =======
 
-Copyright (C) 2001-2010 Chris Liechti <cliechti(at)gmx.net>;
+Copyright (C) 2001-2011 Chris Liechti <cliechti(at)gmx.net>;
 All Rights Reserved.
 
 This is the Python license. In short, you can use this product in commercial
diff --git a/documentation/examples.rst b/documentation/examples.rst
index fcffad6..9260d7b 100644
--- a/documentation/examples.rst
+++ b/documentation/examples.rst
@@ -23,7 +23,7 @@ miniterm::
 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 URLs
+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.
 
@@ -61,7 +61,7 @@ Command line options ``python -m serial.tools.miniterm -h``::
                             control miniterm (menu)
 
 
-miniterm supports some control functions. Typing :kbd:`Control+t Control+h` when it is
+miniterm supports some control functions. Typing :kbd:`Ctrl+T Ctrl+H` when it is
 running shows the help text::
 
     --- pySerial - miniterm - help
@@ -79,6 +79,7 @@ running shows the help text::
     ---       Ctrl+L  line feed    Ctrl+A  Cycle repr mode
     ---
     --- 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)
@@ -87,7 +88,9 @@ running shows the help text::
     --- r R           disable/enable hardware flow control
 
 .. versionchanged:: 2.5
-    Added :kbd:`Control+t` menu and added support for opening URLs.
+    Added :kbd:`Ctrl+T` menu and added support for opening URLs.
+.. versionchanged:: 2.6
+    File moved from the examples to :mod:`serial.tools.miniterm`.
 
 miniterm.py_
     The miniterm program.
@@ -347,9 +350,13 @@ test_iolib.py_
     Tests involving the :mod:`io` library. Only available for Python 2.6 and
     newer.
 
+test_url.py_
+    Tests involving the :ref:`URL <URLs>` feature.
+
 .. _run_all_tests.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/run_all_tests.py
 .. _test.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test.py
 .. _test_advanced.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_advanced.py
 .. _test_high_load.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_high_load.py
 .. _test_readline.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_readline.py
 .. _test_iolib.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_iolib.py
+.. _test_url.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/test/test_url.py