Update documentation for termios module; do not refer to the TERMIOS module

for constant definitions.

Add a deprecation to the TERMIOS module.

Doc/lib/libtermios.tex

@@ -19,9 +19,10 @@ All functions in this module take a file descriptor \var{fd} as their
 first argument.  This must be an integer file descriptor, such as
 returned by \code{sys.stdin.fileno()}.
 
-This module should be used in conjunction with the
+This module also defines all the constants needed to work with the
-\refmodule[TERMIOSuppercase]{TERMIOS}\refstmodindex{TERMIOS} module,
+functions provided here; these have the same name as their
-which defines the relevant symbolic constants (see the next section).
+counterparts in C.  Please refer to your system documentation for more
+information on using these terminal control interfaces.
 
 The module defines the following functions:
 
@@ -30,11 +31,11 @@ Return a list containing the tty attributes for file descriptor
 \var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag},
 \var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where
 \var{cc} is a list of the tty special characters (each a string of
-length 1, except the items with indices \constant{TERMIOS.VMIN} and
+length 1, except the items with indices \constant{VMIN} and
-\constant{TERMIOS.VTIME}, which are integers when these fields are
+\constant{VTIME}, which are integers when these fields are
 defined).  The interpretation of the flags and the speeds as well as
 the indexing in the \var{cc} array must be done using the symbolic
-constants defined in the \refmodule[TERMIOSuppercase]{TERMIOS}
+constants defined in the \module{termios}
 module.
 \end{funcdesc}
 
@@ -42,10 +43,10 @@ module.
 Set the tty attributes for file descriptor \var{fd} from the
 \var{attributes}, which is a list like the one returned by
 \function{tcgetattr()}.  The \var{when} argument determines when the
-attributes are changed: \constant{TERMIOS.TCSANOW} to change
+attributes are changed: \constant{TCSANOW} to change immediately,
-immediately, \constant{TERMIOS.TCSADRAIN} to change after transmitting
+\constant{TCSADRAIN} to change after transmitting all queued output,
-all queued output, or \constant{TERMIOS.TCSAFLUSH} to change after
+or \constant{TCSAFLUSH} to change after transmitting all queued
-transmitting all queued output and discarding all queued input.
+output and discarding all queued input.
 \end{funcdesc}
 
 \begin{funcdesc}{tcsendbreak}{fd, duration}
@@ -61,23 +62,20 @@ transmitted.
 
 \begin{funcdesc}{tcflush}{fd, queue}
 Discard queued data on file descriptor \var{fd}.  The \var{queue}
-selector specifies which queue: \constant{TERMIOS.TCIFLUSH} for the
+selector specifies which queue: \constant{TCIFLUSH} for the input
-input queue, \constant{TERMIOS.TCOFLUSH} for the output queue, or
+queue, \constant{TCOFLUSH} for the output queue, or
-\constant{TERMIOS.TCIOFLUSH} for both queues.
+\constant{TCIOFLUSH} for both queues.
 \end{funcdesc}
 
 \begin{funcdesc}{tcflow}{fd, action}
 Suspend or resume input or output on file descriptor \var{fd}.  The
-\var{action} argument can be \constant{TERMIOS.TCOOFF} to suspend
+\var{action} argument can be \constant{TCOOFF} to suspend output,
-output, \constant{TERMIOS.TCOON} to restart output,
+\constant{TCOON} to restart output, \constant{TCIOFF} to suspend
-\constant{TERMIOS.TCIOFF} to suspend input, or
+input, or \constant{TCION} to restart input.
-\constant{TERMIOS.TCION} to restart input. 
 \end{funcdesc}
 
 
 \begin{seealso}
-  \seemodule[TERMIOSuppercase]{TERMIOS}{Constants for use with
-                                        \module{termios}.}
   \seemodule{tty}{Convenience functions for common terminal control
                   operations.}
 \end{seealso}
@@ -93,16 +91,16 @@ old tty attributes are restored exactly no matter what happens:
 
 \begin{verbatim}
 def getpass(prompt = "Password: "):
-    import termios, TERMIOS, sys
+    import termios, sys
     fd = sys.stdin.fileno()
     old = termios.tcgetattr(fd)
     new = termios.tcgetattr(fd)
-    new[3] = new[3] & ~TERMIOS.ECHO          # lflags
+    new[3] = new[3] & ~termios.ECHO          # lflags
     try:
-        termios.tcsetattr(fd, TERMIOS.TCSADRAIN, new)
+        termios.tcsetattr(fd, termios.TCSADRAIN, new)
         passwd = raw_input(prompt)
     finally:
-        termios.tcsetattr(fd, TERMIOS.TCSADRAIN, old)
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)
     return passwd
 \end{verbatim}
 
@@ -119,11 +117,10 @@ def getpass(prompt = "Password: "):
 \indexii{\POSIX{}}{I/O control}
 \indexii{tty}{I/O control}
 
-This module defines the symbolic constants required to use the
+\deprecated{2.1}{Import needed constants from \refmodule{termios}
-\refmodule{termios}\refbimodindex{termios} module (see the previous 
+                 instead.}
-section).  See the \POSIX{} or \UNIX{} manual pages (or the source)
-for a list of those constants.
 
-Note: this module resides in a system-dependent subdirectory of the
+This module defines the symbolic constants required to use the
-Python library directory.  You may have to generate it for your
+\refmodule{termios}\refbimodindex{termios} module (see the previous
-particular system using the script \file{Tools/scripts/h2py.py}.
+section).  See the \POSIX{} or \UNIX{} manual pages for a list of
+those constants.