really scream out that people should use the file objects instead of

file descriptor operations for normal applications

Doc/lib/libos.tex

@@ -399,11 +399,13 @@ using file descriptors.
 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 @@ For a description of the flag and mode values, see the C run-time
 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 @@ referred to by \var{fd} has been reached, an empty string is
 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 @@ Write the string \var{str} to file descriptor \var{fd}.
 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 @@ Works like \function{rename()}, except creation of any intermediate
 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()}.
+\versionadded{1.5.2}
 
-Note: this function can fail with the new directory structure made if
+\begin{notice}
+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}
+\end{notice}
 \end{funcdesc}
 
 \begin{funcdesc}{rmdir}{path}
@@ -1228,9 +1238,11 @@ Exit to the system with status \var{n}, without calling cleanup
 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