summaryrefslogtreecommitdiffstats
path: root/Doc/doc
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>1999-06-11 14:25:45 (GMT)
committerFred Drake <fdrake@acm.org>1999-06-11 14:25:45 (GMT)
commit5eb992beed03c7b159046214c22a3391ac220059 (patch)
tree6bc6cf26afb19da70d5f77a535ae8d51dc3462ce /Doc/doc
parent18df5d479c087b6b4af4af356ead6ac84b2855ca (diff)
downloadcpython-5eb992beed03c7b159046214c22a3391ac220059.zip
cpython-5eb992beed03c7b159046214c22a3391ac220059.tar.gz
cpython-5eb992beed03c7b159046214c22a3391ac220059.tar.bz2
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.
Diffstat (limited to 'Doc/doc')
-rw-r--r--Doc/doc/doc.tex36
1 files changed, 34 insertions, 2 deletions
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 @@ 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