really scream out that people should use the file objects instead of
file descriptor operations for normal applications
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index c96a990..211d194 100644
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -399,11 +399,13 @@
Close file descriptor \var{fd}.
Availability: Macintosh, \UNIX, Windows.
-Note: this function is intended for low-level I/O and must be applied
+\begin{notice}
+This function is intended for low-level I/O and must be applied
to a file descriptor as returned by \function{open()} or
\function{pipe()}. To close a ``file object'' returned by the
built-in function \function{open()} or by \function{popen()} or
\function{fdopen()}, use its \method{close()} method.
+\end{notice}
\end{funcdesc}
\begin{funcdesc}{dup}{fd}
@@ -498,10 +500,12 @@
documentation; flag constants (like \constant{O_RDONLY} and
\constant{O_WRONLY}) are defined in this module too (see below).
-Note: this function is intended for low-level I/O. For normal usage,
+\begin{notice}
+This function is intended for low-level I/O. For normal usage,
use the built-in function \function{open()}, which returns a ``file
object'' with \method{read()} and \method{write()} methods (and many
more).
+\end{notice}
\end{funcdesc}
\begin{funcdesc}{openpty}{}
@@ -525,12 +529,14 @@
returned.
Availability: Macintosh, \UNIX, Windows.
-Note: this function is intended for low-level I/O and must be applied
+\begin{notice}
+This function is intended for low-level I/O and must be applied
to a file descriptor as returned by \function{open()} or
\function{pipe()}. To read a ``file object'' returned by the
built-in function \function{open()} or by \function{popen()} or
\function{fdopen()}, or \code{sys.stdin}, use its
\method{read()} or \method{readline()} methods.
+\end{notice}
\end{funcdesc}
\begin{funcdesc}{tcgetpgrp}{fd}
@@ -558,12 +564,14 @@
Return the number of bytes actually written.
Availability: Macintosh, \UNIX, Windows.
-Note: this function is intended for low-level I/O and must be applied
+\begin{notice}
+This function is intended for low-level I/O and must be applied
to a file descriptor as returned by \function{open()} or
\function{pipe()}. To write a ``file object'' returned by the
built-in function \function{open()} or by \function{popen()} or
\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
its \method{write()} method.
+\end{notice}
\end{funcdesc}
@@ -874,10 +882,12 @@
directories needed to make the new pathname good is attempted first.
After the rename, directories corresponding to rightmost path segments
of the old name will be pruned away using \function{removedirs()}.
-
-Note: this function can fail with the new directory structure made if
-you lack permissions needed to remove the leaf directory or file.
\versionadded{1.5.2}
+
+\begin{notice}
+This function can fail with the new directory structure made if
+you lack permissions needed to remove the leaf directory or file.
+\end{notice}
\end{funcdesc}
\begin{funcdesc}{rmdir}{path}
@@ -1228,9 +1238,11 @@
handlers, flushing stdio buffers, etc.
Availability: \UNIX, Windows.
-Note: the standard way to exit is \code{sys.exit(\var{n})}.
+\begin{notice}
+The standard way to exit is \code{sys.exit(\var{n})}.
\function{_exit()} should normally only be used in the child process
after a \function{fork()}.
+\end{notice}
\end{funcdesc}
The following exit codes are a defined, and can be used with