Rewrote the section on sys.exit(), documenting other argument types

than integers and recommending sys.exit("message").
(I see this as Python's answer to Perls ``die "message";''.)

1 files changed, 18 insertions, 6 deletions

diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index eadd978..76b54a3 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -98,12 +98,24 @@ A string giving the name of the executable binary for the Python
 interpreter, on systems where this makes sense.
 \end{datadesc}
 
-\begin{funcdesc}{exit}{n}
-  Exit from Python with numeric exit status \var{n}.  This is
-  implemented by raising the \exception{SystemExit} exception, so cleanup
-  actions specified by finally clauses of \keyword{try} statements
-  are honored, and it is possible to catch the exit attempt at an outer
-  level.
+\begin{funcdesc}{exit}{\optional{arg}}
+Exit from Python.  This is implemented by raising the
+\exception{SystemExit} exception, so cleanup actions specified by
+finally clauses of \keyword{try} statements are honored, and it is
+possible to intercept the exit attempt at an outer level.  The
+optional argument \var{arg} can be an integer giving the exit status
+(defaulting to zero), or another type of object.  If it is an integer,
+zero is considered ``successful termination'' and any nonzero value is
+considered ``abnormal termination'' by shells and the like.  Most
+systems require it to be in the range 0-127, and produce undefined
+results otherwise.  Some systems have a convention for assigning
+specific meanings to specific exit codes, but these are generally
+underdeveloped; Unix programs generally use 2 for command line syntax
+errors and 1 for all other kind of errors.  If another type of object
+is passed, \code{None} is equivalent to passing zero, and any other
+object is printed to \code{sys.stderr} and results in an exit code of
+1.  In particular, \code{sys.exit("some error message")} is a quick
+way to exit a program when an error occurs.
 \end{funcdesc}
 
 \begin{datadesc}{exitfunc}