diff options
| -rw-r--r-- | Doc/doc/doc.tex | 36 |
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 |