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 e95f155..62fc11d 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -26,8 +26,9 @@
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 @@
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 @@
\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