- general markup cleanup

- rearrange so two small sections become one; this avoids an extra
  page in the HTML format

Doc/lib/libshlex.tex

@@ -12,32 +12,24 @@
 
 The \class{shlex} class makes it easy to write lexical analyzers for
 simple syntaxes resembling that of the \UNIX{} shell.  This will often
-be useful for writing minilanguages, (e.g. in run control files for
-Python applications) or for parsing quoted strings.
-
-\begin{seealso}
-  \seemodule{ConfigParser}{Parser for configuration files similar to the
-                           Windows \file{.ini} files.}
-\end{seealso}
-
-
-\subsection{Module Contents}
+be useful for writing minilanguages, (for example, in run control
+files for Python applications) or for parsing quoted strings.
 
 The \module{shlex} module defines the following functions:
 
-\begin{funcdesc}{split}{s\optional{, comments=\code{False}}}
+\begin{funcdesc}{split}{s\optional{, comments}}
 Split the string \var{s} using shell-like syntax. If \var{comments} is
-\code{False}, the parsing of comments in the given string will be
-disabled (setting the \member{commenters} member of the \class{shlex}
-instance to the empty string). This function operates in \POSIX{} mode.
+\constant{False} (the default), the parsing of comments in the given
+string will be disabled (setting the \member{commenters} member of the
+\class{shlex} instance to the empty string).  This function operates
+in \POSIX{} mode.
 \versionadded{2.3}
 \end{funcdesc}
 
-The \module{shlex} module defines the following classes:
+The \module{shlex} module defines the following class:
 
-\begin{classdesc}{shlex}{\optional{instream=\code{sys.stdin}\optional{,
-			 infile=\code{None}\optional{,
-			 posix=\code{False}}}}}
+\begin{classdesc}{shlex}{\optional{instream\optional{,
+			 infile\optional{, posix}}}}
 A \class{shlex} instance or subclass instance is a lexical analyzer
 object.  The initialization argument, if present, specifies where to
 read characters from. It must be a file-/stream-like object with
@@ -51,9 +43,15 @@ was introduced in Python 2.3, and defines the operational mode.  When
 \var{posix} is not true (default), the \class{shlex} instance will
 operate in compatibility mode.  When operating in \POSIX{} mode,
 \class{shlex} will try to be as close as possible to the \POSIX{} shell
-parsing rules.  See~\ref{shlex-objects}.
+parsing rules.  See section~\ref{shlex-objects}.
 \end{classdesc}
 
+\begin{seealso}
+  \seemodule{ConfigParser}{Parser for configuration files similar to the
+                           Windows \file{.ini} files.}
+\end{seealso}
+
+
 \subsection{shlex Objects \label{shlex-objects}}
 
 A \class{shlex} instance has the following methods:
@@ -85,7 +83,7 @@ an open file-like object.
 Normally, this method first strips any quotes off the argument.  If
 the result is an absolute pathname, or there was no previous source
 request in effect, or the previous source was a stream
-(e.g. \code{sys.stdin}), the result is left alone.  Otherwise, if the
+(such as \code{sys.stdin}), the result is left alone.  Otherwise, if the
 result is a relative pathname, the directory part of the name of the
 file immediately before it on the source inclusion stack is prepended
 (this behavior is like the way the C preprocessor handles
@@ -268,7 +266,7 @@ following parsing rules.
       retain its special meaning only when followed by the quote in use,
       or the escape character itself. Otherwise the escape character
       will be considered a normal character.
-\item EOF is signaled with a \code{None} value;
+\item EOF is signaled with a \constant{None} value;
 \item Quoted empty strings (\code{''}) are allowed;
 \end{itemize}