Last night's scribbles:

- Revise abstract based on Guido's comments from way back.
- Point out that LaTeX is a structured system & we're using it that
  way.
- Add a small section on marking up code examples.

diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index e95f1557ca945c678c83710c1374ffb44ca8cf74..62fc11d665c7955c0cfd673449f0b1d35fe1add6 100644 (file)
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -26,8 +26,9 @@ The Python language documentation has a substantial body of
 documentation, much of it contributed by various authors.  The markup
 used for the Python documentation is based on \LaTeX{} and requires a
 significant set of macros written specifically for documenting Python.
-Maintaining the documentation requires substantial effort, in part
-because selecting the correct markup to use is not always easy.
+This document describes the macros introduced to support Python
+documentation and how they should be used to support a wide range of
+output formats.
 
 This document describes the document classes and special markup used
 in the Python documentation.  Authors may use this guide, in
@@ -148,6 +149,13 @@ distribution, to create or maintain whole documents or sections.
   syntax, to provide authors enough information to author documents
   productively without having to become ``\TeX{}nicians.''
 
+  Perhaps the most important concept to keep in mind while marking up
+  Python documentation is the while \TeX{} is unstructured, \LaTeX{} was
+  designed as a layer on top of \TeX{} which specifically supports 
+  structured markup.  The Python-specific markup is intended to extend
+  the structure provided by standard \LaTeX{} document classes to
+  support additional information specific to Python.
+
   \LaTeX{} documents contain two parts: the preamble and the body.
   The preamble is used to specify certain metadata about the document
   itself, such as the title, the list of authors, the date, and the
@@ -306,6 +314,30 @@ distribution, to create or maintain whole documents or sections.
     \end{envdesc}
 
 
+  \subsection{Showing Code Examples}
+
+    Examples of Python source code or interactive sessions are
+    represented as \env{verbatim} environments.  This environment
+    is a standard part of \LaTeX{}.  It is important to only use
+    spaces for indentation in code examples since \TeX{} drops tabs
+    instead of converting them to spaces.
+
+    Representing an interactive session requires including the prompts
+    and output along with the Python code.  No special markup is
+    required for interactive sessions.
+
+    Within the \env{verbatim} environment, characters special to
+    \LaTeX{} do not need to be specially marked in any way.  The entire
+    example will be presented in a monospaced font; no attempt at
+    ``pretty-printing'' is made, as the environment must work for
+    non-Python code and non-code displays.
+
+    The Python Documentation Special Interest Group has discussed a
+    number of approaches to creating pretty-printed code displays and
+    interactive sessions; see the Doc-SIG area on the Python Web site
+    for more information on this topic.
+
+
   \subsection{Inline Markup}
 
     The macros described in this section are used to mark just about