Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 1 | \documentclass{howto} |
| 2 | \usepackage{ltxmarkup} |
| 3 | |
| 4 | \title{Documenting Python} |
| 5 | |
| 6 | \input{boilerplate} |
| 7 | |
Fred Drake | c7c9a64 | 1999-04-28 18:24:02 +0000 | [diff] [blame] | 8 | % Now override the stuff that includes author information; |
| 9 | % Guido did *not* write this one! |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 10 | |
| 11 | \author{Fred L. Drake, Jr.} |
| 12 | \authoraddress{ |
| 13 | Corporation for National Research Initiatives (CNRI) \\ |
| 14 | 1895 Preston White Drive, Reston, Va 20191, USA \\ |
| 15 | E-mail: \email{fdrake@acm.org} |
| 16 | } |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 17 | |
| 18 | |
| 19 | \begin{document} |
| 20 | |
| 21 | \maketitle |
| 22 | |
| 23 | \begin{abstract} |
| 24 | \noindent |
| 25 | The Python language documentation has a substantial body of |
| 26 | documentation, much of it contributed by various authors. The markup |
| 27 | used for the Python documentation is based on \LaTeX{} and requires a |
| 28 | significant set of macros written specifically for documenting Python. |
Fred Drake | 5eb992b | 1999-06-11 14:25:45 +0000 | [diff] [blame] | 29 | This document describes the macros introduced to support Python |
| 30 | documentation and how they should be used to support a wide range of |
| 31 | output formats. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 32 | |
| 33 | This document describes the document classes and special markup used |
| 34 | in the Python documentation. Authors may use this guide, in |
| 35 | conjunction with the template files provided with the |
| 36 | distribution, to create or maintain whole documents or sections. |
| 37 | \end{abstract} |
| 38 | |
| 39 | \tableofcontents |
| 40 | |
| 41 | |
| 42 | \section{Introduction} |
| 43 | |
| 44 | Python's documentation has long been considered to be good for a |
| 45 | free programming language. There are a number of reasons for this, |
| 46 | the most important being the early commitment of Python's creator, |
| 47 | Guido van Rossum, to providing documentation on the language and its |
| 48 | libraries, and the continuing involvement of the user community in |
| 49 | providing assistance for creating and maintaining documentation. |
| 50 | |
| 51 | The involvement of the community takes many forms, from authoring to |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 52 | bug reports to just plain complaining when the documentation could |
| 53 | be more complete or easier to use. All of these forms of input from |
| 54 | the community have proved useful during the time I've been involved |
| 55 | in maintaining the documentation. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 56 | |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 57 | This document is aimed at authors and potential authors of |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 58 | documentation for Python. More specifically, it is for people |
| 59 | contributing to the standard documentation and developing additional |
| 60 | documents using the same tools as the standard documents. This |
| 61 | guide will be less useful for authors using the Python documentation |
| 62 | tools for topics other than Python, and less useful still for |
| 63 | authors not using the tools at all. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 64 | |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 65 | The material in this guide is intended to assist authors using the |
| 66 | Python documentation tools. It includes information on the source |
| 67 | distribution of the standard documentation, a discussion of the |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 68 | document types, reference material on the markup defined in the |
| 69 | document classes, a list of the external tools needed for processing |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 70 | documents, and reference material on the tools provided with the |
| 71 | documentation resources. At the end, there is also a section |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 72 | discussing future directions for the Python documentation and where |
| 73 | to turn for more information. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 74 | |
| 75 | \section{Directory Structure} |
| 76 | |
| 77 | The source distribution for the standard Python documentation |
| 78 | contains a large number of directories. While third-party documents |
| 79 | do not need to be placed into this structure or need to be placed |
| 80 | within a similar structure, it can be helpful to know where to look |
| 81 | for examples and tools when developing new documents using the |
| 82 | Python documentation tools. This section describes this directory |
| 83 | structure. |
| 84 | |
| 85 | The documentation sources are usually placed within the Python |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 86 | source distribution as the top-level directory \file{Doc/}, but |
| 87 | are not dependent on the Python source distribution in any way. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 88 | |
| 89 | The \file{Doc/} directory contains a few files and several |
| 90 | subdirectories. The files are mostly self-explanatory, including a |
| 91 | \file{README} and a \file{Makefile}. The directories fall into |
| 92 | three categories: |
| 93 | |
| 94 | \begin{definitions} |
| 95 | \term{Document Sources} |
| 96 | The \LaTeX{} sources for each document are placed in a |
| 97 | separate directory. These directories are given short, |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 98 | three-character names: |
| 99 | |
| 100 | \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Document Title} |
Fred Drake | 698d520 | 1999-11-10 15:54:57 +0000 | [diff] [blame^] | 101 | \lineii{api/}{\citetitle[../api/api.html]{The Python/C API}} |
| 102 | \lineii{doc/}{\citetitle[../doc/doc.html]{Documenting Python}} |
| 103 | \lineii{ext/}{\citetitle[../ext/ext.html]{Extending and Embedding the Python Interpreter}} |
| 104 | \lineii{lib/}{\citetitle[../lib/lib.html]{Python Library Reference}} |
| 105 | \lineii{mac/}{\citetitle[../mac/mac.html]{Macintosh Module Reference}} |
| 106 | \lineii{ref/}{\citetitle[../ref/ref.html]{Python Reference Manual}} |
| 107 | \lineii{tut/}{\citetitle[../tut/tut.html]{Python Tutorial}} |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 108 | \end{tableii} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 109 | |
| 110 | \term{Format-Specific Output} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 111 | Most output formats have a directory which contains a |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 112 | \file{Makefile} which controls the generation of that format |
| 113 | and provides storage for the formatted documents. The only |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 114 | variations within this category are the Portable Document |
| 115 | Format (PDF) and PostScript versions are placed in the |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 116 | directories \file{paper-a4/} and \file{paper-letter/} (this |
| 117 | causes all the temporary files created by \LaTeX{} to be kept |
| 118 | in the same place for each paper size, where they can be more |
| 119 | easily ignored). |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 120 | |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 121 | \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Output Formats} |
| 122 | \lineii{html/}{HTML output} |
| 123 | \lineii{info/}{GNU info output} |
| 124 | \lineii{paper-a4/}{PDF and PostScript, A4 paper} |
| 125 | \lineii{paper-letter/}{PDF and PostScript, US-Letter paper} |
| 126 | \end{tableii} |
| 127 | |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 128 | \term{Supplemental Files} |
| 129 | Some additional directories are used to store supplemental |
| 130 | files used for the various processes. Directories are |
| 131 | included for the shared \LaTeX{} document classes, the |
| 132 | \LaTeX2HTML support, template files for various document |
| 133 | components, and the scripts used to perform various steps in |
| 134 | the formatting processes. |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 135 | |
| 136 | \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Contents} |
| 137 | \lineii{perl/}{Support for \LaTeX2HTML processing} |
| 138 | \lineii{templates/}{Example files for source documents} |
| 139 | \lineii{texinputs/}{Style implementation for \LaTeX} |
| 140 | \lineii{tools/}{Custom processing scripts} |
| 141 | \end{tableii} |
| 142 | |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 143 | \end{definitions} |
| 144 | |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 145 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 146 | \section{\LaTeX{} Primer \label{latex-primer}} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 147 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 148 | This section is a brief introduction to \LaTeX{} concepts and |
| 149 | syntax, to provide authors enough information to author documents |
| 150 | productively without having to become ``\TeX{}nicians.'' |
| 151 | |
Fred Drake | 5eb992b | 1999-06-11 14:25:45 +0000 | [diff] [blame] | 152 | Perhaps the most important concept to keep in mind while marking up |
| 153 | Python documentation is the while \TeX{} is unstructured, \LaTeX{} was |
| 154 | designed as a layer on top of \TeX{} which specifically supports |
| 155 | structured markup. The Python-specific markup is intended to extend |
| 156 | the structure provided by standard \LaTeX{} document classes to |
| 157 | support additional information specific to Python. |
| 158 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 159 | \LaTeX{} documents contain two parts: the preamble and the body. |
| 160 | The preamble is used to specify certain metadata about the document |
| 161 | itself, such as the title, the list of authors, the date, and the |
| 162 | \emph{class} the document belongs to. Additional information used |
| 163 | to control index generation and the use of bibliographic databases |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 164 | can also be placed in the preamble. For most authors, the preamble |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 165 | can be most easily created by copying it from an existing document |
| 166 | and modifying a few key pieces of information. |
| 167 | |
| 168 | The \dfn{class} of a document is used to place a document within a |
| 169 | broad category of documents and set some fundamental formatting |
| 170 | properties. For Python documentation, two classes are used: the |
| 171 | \code{manual} class and the \code{howto} class. These classes also |
| 172 | define the additional markup used to document Python concepts and |
| 173 | structures. Specific information about these classes is provided in |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 174 | section \ref{classes}, ``Document Classes,'' below. The first thing |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 175 | in the preamble is the declaration of the document's class. |
| 176 | |
| 177 | After the class declaration, a number of \emph{macros} are used to |
| 178 | provide further information about the document and setup any |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 179 | additional markup that is needed. No output is generated from the |
| 180 | preamble; it is an error to include free text in the preamble |
| 181 | because it would cause output. |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 182 | |
| 183 | The document body follows the preamble. This contains all the |
| 184 | printed components of the document marked up structurally. |
| 185 | |
| 186 | XXX This section will discuss what the markup looks like, and |
| 187 | explain the difference between an environment and a macro. |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 188 | |
| 189 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 190 | \section{Document Classes \label{classes}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 191 | |
| 192 | Two \LaTeX{} document classes are defined specifically for use with |
| 193 | the Python documentation. The \code{manual} class is for large |
| 194 | documents which are sectioned into chapters, and the \code{howto} |
| 195 | class is for smaller documents. |
| 196 | |
| 197 | The \code{manual} documents are larger and are used for most of the |
| 198 | standard documents. This document class is based on the standard |
| 199 | \LaTeX{} \code{report} class and is formatted very much like a long |
Fred Drake | 698d520 | 1999-11-10 15:54:57 +0000 | [diff] [blame^] | 200 | technical report. The \citetitle[../ref/ref.html]{Python Reference |
| 201 | Manual} is a good example of a \code{manual} document, and the |
| 202 | \citetitle[../lib/lib.html]{Python Library Reference} is a large |
| 203 | example. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 204 | |
| 205 | The \code{howto} documents are shorter, and don't have the large |
| 206 | structure of the \code{manual} documents. This class is based on |
| 207 | the standard \LaTeX{} \code{article} class and is formatted somewhat |
| 208 | like the Linux Documentation Project's ``HOWTO'' series as done |
| 209 | originally using the LinuxDoc software. The original intent for the |
| 210 | document class was that it serve a similar role as the LDP's HOWTO |
| 211 | series, but the applicability of the class turns out to be somewhat |
| 212 | more broad. This class is used for ``how-to'' documents (this |
| 213 | document is an example) and for shorter reference manuals for small, |
| 214 | fairly cohesive module libraries. Examples of the later use include |
Fred Drake | 698d520 | 1999-11-10 15:54:57 +0000 | [diff] [blame^] | 215 | the standard \citetitle[../mac/mac.html]{Macintosh Library Modules} |
| 216 | and |
| 217 | \citetitle[http://starship.python.org/crew/fdrake/manuals/krb5py/krb5py.html]{Using |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 218 | Kerberos from Python}, which contains reference material for an |
| 219 | extension package. These documents are roughly equivalent to a |
| 220 | single chapter from a larger work. |
| 221 | |
| 222 | |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 223 | \section{Special Markup Constructs} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 224 | |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 225 | The Python document classes define a lot of new environments and |
| 226 | macros. This section contains the reference material for these |
| 227 | facilities. |
| 228 | |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 229 | \subsection{Information Units \label{info-units}} |
| 230 | |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 231 | XXX Explain terminology, or come up with something more ``lay.'' |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 232 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 233 | There are a number of environments used to describe specific |
| 234 | features provided by modules. Each environment requires |
| 235 | parameters needed to provide basic information about what is being |
| 236 | described, and the environment content should be the description. |
| 237 | Most of these environments make entries in the general index (if |
| 238 | one is being produced for the document); if no index entry is |
| 239 | desired, non-indexing variants are available for many of these |
| 240 | environments. The environments have names of the form |
| 241 | \code{\var{feature}desc}, and the non-indexing variants are named |
| 242 | \code{\var{feature}descni}. The available variants are explicitly |
| 243 | included in the list below. |
| 244 | |
| 245 | For each of these environments, the first parameter, \var{name}, |
| 246 | provides the name by which the feature is accessed. |
| 247 | |
| 248 | Environments which describe features of objects within a module, |
| 249 | such as object methods or data attributes, allow an optional |
| 250 | \var{type name} parameter. When the feature is an attribute of |
| 251 | class instances, \var{type name} only needs to be given if the |
| 252 | class was not the most recently described class in the module; the |
| 253 | \var{name} value from the most recent \env{classdesc} is implied. |
| 254 | For features of built-in or extension types, the \var{type name} |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 255 | value should always be provided. Another special case includes |
| 256 | methods and members of general ``protocols,'' such as the |
| 257 | formatter and writer protocols described for the |
| 258 | \module{formatter} module: these may be documented without any |
| 259 | specific implementation classes, and will always require the |
| 260 | \var{type name} parameter to be provided. |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 261 | |
| 262 | \begin{envdesc}{datadesc}{\p{name}} |
| 263 | This environment is used to document global data in a module, |
| 264 | including both variables and values used as ``defined |
| 265 | constants.'' Class and object attributes are not documented |
| 266 | using this environment. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 267 | \end{envdesc} |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 268 | \begin{envdesc}{datadescni}{\p{name}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 269 | Like \env{datadesc}, but without creating any index entries. |
| 270 | \end{envdesc} |
| 271 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 272 | \begin{envdesc}{excdesc}{\p{name}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 273 | Describe an exception. This may be either a string exception or |
| 274 | a class exception. |
| 275 | \end{envdesc} |
| 276 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 277 | \begin{envdesc}{funcdesc}{\p{name}\p{parameters}} |
| 278 | Describe a module-level function. \var{parameters} should |
| 279 | not include the parentheses used in the call syntax. Object |
| 280 | methods are not documented using this environment. Bound object |
| 281 | methods placed in the module namespace as part of the public |
| 282 | interface of the module are documented using this, as they are |
| 283 | equivalent to normal functions for most purposes. |
| 284 | |
| 285 | The description should include information about the parameters |
| 286 | required and how they are used (especially whether mutable |
| 287 | objects passed as parameters are modified), side effects, and |
| 288 | possible exceptions. A small example may be provided. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 289 | \end{envdesc} |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 290 | \begin{envdesc}{funcdescni}{\p{name}\p{parameters}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 291 | Like \env{funcdesc}, but without creating any index entries. |
| 292 | \end{envdesc} |
| 293 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 294 | \begin{envdesc}{classdesc}{\p{name}\p{constructor parameters}} |
| 295 | Describe a class and its constructor. \var{constructor |
| 296 | parameters} should not include the \var{self} parameter or |
| 297 | the parentheses used in the call syntax. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 298 | \end{envdesc} |
| 299 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 300 | \begin{envdesc}{memberdesc}{\op{type name}\p{name}} |
| 301 | Describe an object data attribute. The description should |
| 302 | include information about the type of the data to be expected |
| 303 | and whether it may be changed directly. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 304 | \end{envdesc} |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 305 | \begin{envdesc}{memberdescni}{\op{type name}\p{name}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 306 | Like \env{memberdesc}, but without creating any index entries. |
| 307 | \end{envdesc} |
| 308 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 309 | \begin{envdesc}{methoddesc}{\op{type name}\p{name}\p{parameters}} |
| 310 | Describe an object method. \var{parameters} should not include |
| 311 | the \var{self} parameter or the parentheses used in the call |
| 312 | syntax. The description should include similar information to |
| 313 | that described for \env{funcdesc}. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 314 | \end{envdesc} |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 315 | \begin{envdesc}{methoddescni}{\op{type name}\p{name}\p{parameters}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 316 | Like \env{methoddesc}, but without creating any index entries. |
| 317 | \end{envdesc} |
| 318 | |
| 319 | |
Fred Drake | 5eb992b | 1999-06-11 14:25:45 +0000 | [diff] [blame] | 320 | \subsection{Showing Code Examples} |
| 321 | |
| 322 | Examples of Python source code or interactive sessions are |
| 323 | represented as \env{verbatim} environments. This environment |
| 324 | is a standard part of \LaTeX{}. It is important to only use |
| 325 | spaces for indentation in code examples since \TeX{} drops tabs |
| 326 | instead of converting them to spaces. |
| 327 | |
| 328 | Representing an interactive session requires including the prompts |
| 329 | and output along with the Python code. No special markup is |
| 330 | required for interactive sessions. |
| 331 | |
| 332 | Within the \env{verbatim} environment, characters special to |
| 333 | \LaTeX{} do not need to be specially marked in any way. The entire |
| 334 | example will be presented in a monospaced font; no attempt at |
| 335 | ``pretty-printing'' is made, as the environment must work for |
| 336 | non-Python code and non-code displays. |
| 337 | |
| 338 | The Python Documentation Special Interest Group has discussed a |
| 339 | number of approaches to creating pretty-printed code displays and |
| 340 | interactive sessions; see the Doc-SIG area on the Python Web site |
| 341 | for more information on this topic. |
| 342 | |
| 343 | |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 344 | \subsection{Inline Markup} |
| 345 | |
Fred Drake | 87f768e | 1999-05-17 15:22:45 +0000 | [diff] [blame] | 346 | The macros described in this section are used to mark just about |
| 347 | anything interesting in the document text. They may be used in |
| 348 | headings (though anything involving hyperlinks should be avoided |
| 349 | there) as well as in the body text. |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 350 | |
| 351 | \begin{macrodesc}{bfcode}{\p{text}} |
| 352 | Like \macro{code}, but also makes the font bold-face. |
| 353 | \end{macrodesc} |
| 354 | |
| 355 | \begin{macrodesc}{cdata}{\p{name}} |
| 356 | The name of a C-language variable. |
| 357 | \end{macrodesc} |
| 358 | |
| 359 | \begin{macrodesc}{cfunction}{\p{name}} |
| 360 | The name of a C-language function. \var{name} should include the |
| 361 | function name and the trailing parentheses. |
| 362 | \end{macrodesc} |
| 363 | |
| 364 | \begin{macrodesc}{character}{\p{char}} |
| 365 | A character when discussing the character rather than a one-byte |
| 366 | string value. The character will be typeset as with \macro{samp}. |
| 367 | \end{macrodesc} |
| 368 | |
| 369 | \begin{macrodesc}{class}{\p{name}} |
| 370 | A class name; a dotted name may be used. |
| 371 | \end{macrodesc} |
| 372 | |
| 373 | \begin{macrodesc}{code}{\p{text}} |
| 374 | A short code fragment or literal constant value. Typically, it |
| 375 | should not include any spaces since no quotation marks are |
| 376 | added. |
| 377 | \end{macrodesc} |
| 378 | |
| 379 | \begin{macrodesc}{constant}{\p{name}} |
| 380 | The name of a ``defined'' constant. This may be a C-language |
| 381 | \code{\#define} or a Python variable that is not intended to be |
| 382 | changed. |
| 383 | \end{macrodesc} |
| 384 | |
| 385 | \begin{macrodesc}{ctype}{\p{name}} |
| 386 | The name of a C \keyword{typedef} or structure. For structures |
| 387 | defined without a \keyword{typedef}, use \code{\e ctype\{struct |
| 388 | struct_tag\}} to make it clear that the \keyword{struct} is |
| 389 | required. |
| 390 | \end{macrodesc} |
| 391 | |
| 392 | \begin{macrodesc}{deprecated}{\p{version}\p{what to do}} |
| 393 | Declare whatever is being described as being deprecated starting |
| 394 | with release \var{version}. The text given as \var{what to do} |
| 395 | should recommend something to use instead. |
| 396 | \end{macrodesc} |
| 397 | |
| 398 | \begin{macrodesc}{dfn}{\p{term}} |
| 399 | Mark the defining instance of \var{term} in the text. (No index |
| 400 | entries are generated.) |
| 401 | \end{macrodesc} |
| 402 | |
Fred Drake | d1fb779 | 1999-05-17 16:33:54 +0000 | [diff] [blame] | 403 | \begin{macrodesc}{e}{} |
| 404 | Produces a backslash. This is convenient in \macro{code} and |
| 405 | similar macros. |
| 406 | \end{macrodesc} |
| 407 | |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 408 | \begin{macrodesc}{email}{\p{address}} |
| 409 | An email address. Note that this is \emph{not} hyperlinked in |
| 410 | any of the possible output formats. |
| 411 | \end{macrodesc} |
| 412 | |
| 413 | \begin{macrodesc}{emph}{\p{text}} |
| 414 | Emphasized text; this will be presented in an italic font. |
| 415 | \end{macrodesc} |
| 416 | |
| 417 | \begin{macrodesc}{envvar}{\p{name}} |
| 418 | An environment variable. Index entries are generated. |
| 419 | \end{macrodesc} |
| 420 | |
| 421 | \begin{macrodesc}{exception}{\p{name}} |
| 422 | The name of an exception. A dotted name may be used. |
| 423 | \end{macrodesc} |
| 424 | |
| 425 | \begin{macrodesc}{file}{\p{file or dir}} |
| 426 | The name of a file or directory. In the PDF and PostScript |
| 427 | outputs, single quotes and a font change are used to indicate |
| 428 | the file name, but no quotes are used in the HTML output. |
| 429 | \end{macrodesc} |
| 430 | |
| 431 | \begin{macrodesc}{filenq}{\p{file or dir}} |
| 432 | Like \macro{file}, but single quotes are never used. This can |
| 433 | be used in conjunction with tables if a column will only contain |
| 434 | file or directory names. |
| 435 | \end{macrodesc} |
| 436 | |
| 437 | \begin{macrodesc}{function}{\p{name}} |
| 438 | The name of a Python function; dotted names may be used. |
| 439 | \end{macrodesc} |
| 440 | |
| 441 | \begin{macrodesc}{kbd}{\p{key sequence}} |
| 442 | Mark a sequence of keystrokes. What form \var{key sequence} |
| 443 | takes may depend on platform- or application-specific |
| 444 | conventions. For example, an \program{xemacs} key sequence |
| 445 | may be marked like \code{\e kbd\{C-x C-f\}}. |
| 446 | \end{macrodesc} |
| 447 | |
| 448 | \begin{macrodesc}{keyword}{\p{name}} |
| 449 | The name of a keyword in a programming language. |
| 450 | \end{macrodesc} |
| 451 | |
| 452 | \begin{macrodesc}{makevar}{\p{name}} |
| 453 | The name of a \program{make} variable. |
| 454 | \end{macrodesc} |
| 455 | |
| 456 | \begin{macrodesc}{manpage}{\p{name}\p{section}} |
| 457 | A reference to a \UNIX{} manual page. |
| 458 | \end{macrodesc} |
| 459 | |
| 460 | \begin{macrodesc}{member}{\p{name}} |
| 461 | The name of a data attribute of an object. |
| 462 | \end{macrodesc} |
| 463 | |
| 464 | \begin{macrodesc}{method}{\p{name}} |
| 465 | The name of a method of an object. \var{name} should include the |
| 466 | method name and the trailing parentheses. A dotted name may be |
| 467 | used. |
| 468 | \end{macrodesc} |
| 469 | |
| 470 | \begin{macrodesc}{mimetype}{\p{name}} |
| 471 | The name of a MIME type. |
| 472 | \end{macrodesc} |
| 473 | |
| 474 | \begin{macrodesc}{module}{\p{name}} |
| 475 | The name of a module; a dotted name may be used. |
| 476 | \end{macrodesc} |
| 477 | |
| 478 | \begin{macrodesc}{newsgroup}{\p{name}} |
| 479 | The name of a USENET newsgroup. |
| 480 | \end{macrodesc} |
| 481 | |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 482 | \begin{macrodesc}{program}{\p{name}} |
| 483 | The name of an executable program. This may differ from the |
| 484 | file name for the executable for some platforms. In particular, |
| 485 | the \file{.exe} (or other) extension should be omitted for DOS |
| 486 | and Windows programs. |
| 487 | \end{macrodesc} |
| 488 | |
| 489 | \begin{macrodesc}{refmodule}{\op{key}\p{name}} |
| 490 | Like \macro{module}, but create a hyperlink to the documentation |
| 491 | for the named module. Note that the corresponding |
| 492 | \macro{declaremodule} must be in the same document. If the |
| 493 | \macro{declaremodule} defines a module key different from the |
| 494 | module name, it must also be provided as \var{key} to the |
| 495 | \macro{refmodule} macro. |
| 496 | \end{macrodesc} |
| 497 | |
| 498 | \begin{macrodesc}{regexp}{\p{string}} |
| 499 | Mark a regular expression. |
| 500 | \end{macrodesc} |
| 501 | |
| 502 | \begin{macrodesc}{rfc}{\p{number}} |
| 503 | A reference to an Internet Request for Comments. This generates |
| 504 | appropriate index entries. The text \samp{RFC \var{number}} is |
| 505 | generated; in the HTML output, this text is a hyperlink to an |
| 506 | online copy of the specified RFC. |
| 507 | \end{macrodesc} |
| 508 | |
| 509 | \begin{macrodesc}{samp}{\p{text}} |
| 510 | A short code sample, but possibly longer than would be given |
| 511 | using \macro{code}. Since quotation marks are added, spaces are |
| 512 | acceptable. |
| 513 | \end{macrodesc} |
| 514 | |
| 515 | \begin{macrodesc}{strong}{\p{text}} |
| 516 | Strongly emphasized text; this will be presented using a bold |
| 517 | font. |
| 518 | \end{macrodesc} |
| 519 | |
Fred Drake | d1fb779 | 1999-05-17 16:33:54 +0000 | [diff] [blame] | 520 | \begin{macrodesc}{url}{\p{url}} |
| 521 | A URL (or URN). The URL will be presented as text. In the HTML |
| 522 | and PDF formatted versions, the URL will also be a hyperlink. |
| 523 | This can be used when referring to external resources. Note |
| 524 | that many characters are special to \LaTeX{} and this macro |
| 525 | does not always do the right thing. In particular, the tilde |
| 526 | character (\character{\~}) is mis-handled; encoding it as a |
| 527 | hex-sequence does work, use \samp{\%7e} in place of the tilde |
| 528 | character. |
| 529 | \end{macrodesc} |
| 530 | |
Fred Drake | 2f4bebd | 1999-04-28 16:43:11 +0000 | [diff] [blame] | 531 | \begin{macrodesc}{var}{\p{name}} |
| 532 | The name of a variable or formal parameter in running text. |
| 533 | \end{macrodesc} |
| 534 | |
| 535 | \begin{macrodesc}{version}{} |
| 536 | The version number for the documentation, as specified using |
| 537 | \macro{release} in the preamble. |
| 538 | \end{macrodesc} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 539 | |
| 540 | |
| 541 | \subsection{Module-specific Markup} |
| 542 | |
| 543 | The markup described in this section is used to provide information |
| 544 | about a module being documented. A typical use of this markup |
| 545 | appears at the top of the section used to document a module. A |
| 546 | typical example might look like this: |
| 547 | |
| 548 | \begin{verbatim} |
| 549 | \section{\module{spam} --- |
| 550 | Access to the SPAM facility} |
| 551 | |
| 552 | \declaremodule{extension}{spam} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 553 | \platform{Unix} |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 554 | \modulesynopsis{Access to the SPAM facility of \UNIX{}.} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 555 | \moduleauthor{Jane Doe}{jane.doe@frobnitz.org} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 556 | \end{verbatim} |
| 557 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 558 | \begin{macrodesc}{declaremodule}{\op{key}\p{type}\p{name}} |
Fred Drake | 87f768e | 1999-05-17 15:22:45 +0000 | [diff] [blame] | 559 | Requires two parameters: module type (\samp{standard}, |
| 560 | \samp{builtin}, \samp{extension}, or \samp{}), and the module |
| 561 | name. An optional parameter should be given as the basis for the |
| 562 | module's ``key'' used for linking to or referencing the section. |
| 563 | The ``key'' should only be given if the module's name contains any |
| 564 | underscores, and should be the name with the underscores stripped. |
| 565 | Note that the \var{type} parameter must be one of the values |
| 566 | listed above or an error will be printed. For modules which are |
| 567 | contained in packages, the fully-qualified name should be given as |
| 568 | \var{name} parameter. This should be the first thing after the |
| 569 | \macro{section} used to introduce the module. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 570 | \end{macrodesc} |
| 571 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 572 | \begin{macrodesc}{platform}{\p{specifier}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 573 | Specifies the portability of the module. \var{specifier} is a |
| 574 | comma-separated list of keys that specify what platforms the |
| 575 | module is available on. The keys are short identifiers; |
| 576 | examples that are in use include \samp{IRIX}, \samp{Mac}, |
| 577 | \samp{Windows}, and \samp{Unix}. It is important to use a key |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 578 | which has already been used when applicable. This is used to |
| 579 | provide annotations in the Module Index and the HTML and GNU info |
| 580 | output. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 581 | \end{macrodesc} |
| 582 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 583 | \begin{macrodesc}{modulesynopsis}{\p{text}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 584 | The \var{text} is a short, ``one line'' description of the |
| 585 | module that can be used as part of the chapter introduction. |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 586 | This is must be placed after \macro{declaremodule}. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 587 | The synopsis is used in building the contents of the table |
| 588 | inserted as the \macro{localmoduletable}. No text is |
| 589 | produced at the point of the markup. |
| 590 | \end{macrodesc} |
| 591 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 592 | \begin{macrodesc}{moduleauthor}{\p{name}\p{email}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 593 | This macro is used to encode information about who authored a |
| 594 | module. This is currently not used to generate output, but can be |
| 595 | used to help determine the origin of the module. |
| 596 | \end{macrodesc} |
| 597 | |
| 598 | |
| 599 | \subsection{Library-level Markup} |
| 600 | |
| 601 | This markup is used when describing a selection of modules. For |
Fred Drake | 698d520 | 1999-11-10 15:54:57 +0000 | [diff] [blame^] | 602 | example, the \citetitle[../mac/mac.html]{Macintosh Library |
| 603 | Modules} document uses this to help provide an overview of the |
| 604 | modules in the collection, and many chapters in the |
| 605 | \citetitle[../lib/lib.html]{Python Library Reference} use it for |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 606 | the same purpose. |
| 607 | |
| 608 | \begin{macrodesc}{localmoduletable}{} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 609 | If a \file{.syn} file exists for the current |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 610 | chapter (or for the entire document in \code{howto} documents), a |
| 611 | \env{synopsistable} is created with the contents loaded from the |
| 612 | \file{.syn} file. |
| 613 | \end{macrodesc} |
| 614 | |
| 615 | |
| 616 | \subsection{Table Markup} |
| 617 | |
| 618 | There are three general-purpose table environments defined which |
| 619 | should be used whenever possible. These environments are defined |
| 620 | to provide tables of specific widths and some convenience for |
| 621 | formatting. These environments are not meant to be general |
| 622 | replacements for the standard \LaTeX{} table environments, but can |
| 623 | be used for an advantage when the documents are processed using |
| 624 | the tools for Python documentation processing. In particular, the |
| 625 | generated HTML looks good! There is also an advantage for the |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 626 | eventual conversion of the documentation to SGML (see section |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 627 | \ref{futures}, ``Future Directions''). |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 628 | |
| 629 | Each environment is named \env{table\var{cols}}, where \var{cols} |
| 630 | is the number of columns in the table specified in lower-case |
| 631 | Roman numerals. Within each of these environments, an additional |
| 632 | macro, \macro{line\var{cols}}, is defined, where \var{cols} |
| 633 | matches the \var{cols} value of the corresponding table |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 634 | environment. These are supported for \var{cols} values of |
| 635 | \code{ii}, \code{iii}, and \code{iv}. These environments are all |
| 636 | built on top of the \env{tabular} environment. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 637 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 638 | \begin{envdesc}{tableii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 639 | Create a two-column table using the \LaTeX{} column specifier |
| 640 | \var{colspec}. The column specifier should indicate vertical |
| 641 | bars between columns as appropriate for the specific table, but |
| 642 | should not specify vertical bars on the outside of the table |
| 643 | (that is considered a stylesheet issue). The \var{col1font} |
| 644 | parameter is used as a stylistic treatment of the first column |
| 645 | of the table: the first column is presented as |
| 646 | \code{\e\var{col1font}\{column1\}}. To avoid treating the first |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 647 | column specially, \var{col1font} may be \samp{textrm}. The |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 648 | column headings are taken from the values \var{heading1} and |
| 649 | \var{heading2}. |
| 650 | \end{envdesc} |
| 651 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 652 | \begin{macrodesc}{lineii}{\p{column1}\p{column2}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 653 | Create a single table row within a \env{tableii} environment. |
| 654 | The text for the first column will be generated by applying the |
| 655 | macro named by the \var{col1font} value when the \env{tableii} |
| 656 | was opened. |
| 657 | \end{macrodesc} |
| 658 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 659 | \begin{envdesc}{tableiii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 660 | Like the \env{tableii} environment, but with a third column. |
| 661 | The heading for the third column is given by \var{heading3}. |
| 662 | \end{envdesc} |
| 663 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 664 | \begin{macrodesc}{lineiii}{\p{column1}\p{column2}\p{column3}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 665 | Like the \macro{lineii} macro, but with a third column. The |
| 666 | text for the third column is given by \var{column3}. |
| 667 | \end{macrodesc} |
| 668 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 669 | \begin{envdesc}{tableiv}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}\p{heading4}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 670 | Like the \env{tableiii} environment, but with a fourth column. |
| 671 | The heading for the fourth column is given by \var{heading4}. |
| 672 | \end{envdesc} |
| 673 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 674 | \begin{macrodesc}{lineiv}{\p{column1}\p{column2}\p{column3}\p{column4}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 675 | Like the \macro{lineiii} macro, but with a fourth column. The |
| 676 | text for the fourth column is given by \var{column4}. |
| 677 | \end{macrodesc} |
| 678 | |
| 679 | |
| 680 | An additional table-like environment is \env{synopsistable}. The |
| 681 | table generated by this environment contains two columns, and each |
| 682 | row is defined by an alternate definition of |
| 683 | \macro{modulesynopsis}. This environment is not normally use by |
| 684 | the user, but is created by the \macro{localmoduletable} macro. |
| 685 | |
| 686 | |
| 687 | \subsection{Reference List Markup \label{references}} |
| 688 | |
| 689 | Many sections include a list of references to module documentation |
| 690 | or external documents. These lists are created using the |
| 691 | \env{seealso} environment. This environment defines some |
| 692 | additional macros to support creating reference entries in a |
| 693 | reasonable manner. |
| 694 | |
| 695 | \begin{envdesc}{seealso}{} |
| 696 | This environment creates a ``See also:'' heading and defines the |
| 697 | markup used to describe individual references. |
| 698 | \end{envdesc} |
| 699 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 700 | \begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 701 | Refer to another module. \var{why} should be a brief |
| 702 | explanation of why the reference may be interesting. The module |
| 703 | name is given in \var{name}, with the link key given in |
| 704 | \var{key} if necessary. In the HTML and PDF conversions, the |
| 705 | module name will be a hyperlink to the referred-to module. |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 706 | \strong{Note:} The module must be documented in the same |
| 707 | document (the corresponding \macro{declaremodule} is required). |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 708 | \end{macrodesc} |
| 709 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 710 | \begin{macrodesc}{seetext}{\p{text}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 711 | Add arbitrary text \var{text} to the ``See also:'' list. This |
| 712 | can be used to refer to off-line materials or on-line materials |
| 713 | using the \macro{url} macro. |
| 714 | \end{macrodesc} |
| 715 | |
| 716 | |
| 717 | \subsection{Index-generating Markup \label{indexing}} |
| 718 | |
| 719 | Effective index generation for technical documents can be very |
| 720 | difficult, especially for someone familliar with the topic but not |
| 721 | the creation of indexes. Much of the difficulty arises in the |
| 722 | area of terminology: including the terms an expert would use for a |
| 723 | concept is not sufficient. Coming up with the terms that a novice |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 724 | would look up is fairly difficult for an author who, typically, is |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 725 | an expert in the area she is writing on. |
| 726 | |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 727 | The truly difficult aspects of index generation are not areas with |
| 728 | which the documentation tools can help. However, ease |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 729 | of producing the index once content decisions are make is within |
| 730 | the scope of the tools. Markup is provided which the processing |
| 731 | software is able to use to generate a variety of kinds of index |
| 732 | entry with minimal effort. Additionally, many of the environments |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 733 | described in section \ref{info-units}, ``Information Units,'' will |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 734 | generate appropriate entries into the general and module indexes. |
| 735 | |
| 736 | The following macro can be used to control the generation of index |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 737 | data, and should be used in the document preamble: |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 738 | |
| 739 | \begin{macrodesc}{makemodindex}{} |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 740 | This should be used in the document preamble if a ``Module |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 741 | Index'' is desired for a document containing reference material |
| 742 | on many modules. This causes a data file |
Fred Drake | d1fb779 | 1999-05-17 16:33:54 +0000 | [diff] [blame] | 743 | \code{lib\var{jobname}.idx} to be created from the |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 744 | \macro{declaremodule} macros. This file can be processed by the |
| 745 | \program{makeindex} program to generate a file which can be |
| 746 | \macro{input} into the document at the desired location of the |
| 747 | module index. |
| 748 | \end{macrodesc} |
| 749 | |
| 750 | There are a number of macros that are useful for adding index |
| 751 | entries for particular concepts, many of which are specific to |
| 752 | programming languages or even Python. |
| 753 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 754 | \begin{macrodesc}{bifuncindex}{\p{name}} |
Fred Drake | ec8b905 | 1999-04-23 20:01:17 +0000 | [diff] [blame] | 755 | Add an index entry referring to a built-in function named |
| 756 | \var{name}; parentheses should not be included after |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 757 | \var{name}. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 758 | \end{macrodesc} |
| 759 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 760 | \begin{macrodesc}{exindex}{\p{exception}} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 761 | Add a reference to an exception named \var{exception}. The |
| 762 | exception may be either string- or class-based. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 763 | \end{macrodesc} |
| 764 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 765 | \begin{macrodesc}{kwindex}{\p{keyword}} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 766 | Add a reference to a language keyword (not a keyword parameter |
| 767 | in a function or method call). |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 768 | \end{macrodesc} |
| 769 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 770 | \begin{macrodesc}{obindex}{\p{object type}} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 771 | Add an index entry for a built-in object type. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 772 | \end{macrodesc} |
| 773 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 774 | \begin{macrodesc}{opindex}{\p{operator}} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 775 | Add a reference to an operator, such as \samp{+}. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 776 | \end{macrodesc} |
| 777 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 778 | \begin{macrodesc}{refmodindex}{\op{key}\p{module}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 779 | Add an index entry for module \var{module}; if \var{module} |
| 780 | contains an underscore, the optional parameter \var{key} should |
| 781 | be provided as the same string with underscores removed. An |
| 782 | index entry ``\var{module} (module)'' will be generated. This |
| 783 | is intended for use with non-standard modules implemented in |
| 784 | Python. |
| 785 | \end{macrodesc} |
| 786 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 787 | \begin{macrodesc}{refexmodindex}{\op{key}\p{module}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 788 | As for \macro{refmodindex}, but the index entry will be |
| 789 | ``\var{module} (extension module).'' This is intended for use |
| 790 | with non-standard modules not implemented in Python. |
| 791 | \end{macrodesc} |
| 792 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 793 | \begin{macrodesc}{refbimodindex}{\op{key}\p{module}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 794 | As for \macro{refmodindex}, but the index entry will be |
| 795 | ``\var{module} (built-in module).'' This is intended for use |
| 796 | with standard modules not implemented in Python. |
| 797 | \end{macrodesc} |
| 798 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 799 | \begin{macrodesc}{refstmodindex}{\op{key}\p{module}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 800 | As for \macro{refmodindex}, but the index entry will be |
| 801 | ``\var{module} (standard module).'' This is intended for use |
| 802 | with standard modules implemented in Python. |
| 803 | \end{macrodesc} |
| 804 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 805 | \begin{macrodesc}{stindex}{\p{statement}} |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 806 | Add an index entry for a statement type, such as \keyword{print} |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 807 | or \keyword{try}/\keyword{finally}. |
| 808 | |
| 809 | XXX Need better examples of difference from \macro{kwindex}. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 810 | \end{macrodesc} |
| 811 | |
| 812 | |
| 813 | Additional macros are provided which are useful for conveniently |
| 814 | creating general index entries which should appear at many places |
| 815 | in the index by rotating a list of words. These are simple macros |
| 816 | that simply use \macro{index} to build some number of index |
| 817 | entries. Index entries build using these macros contain both |
| 818 | primary and secondary text. |
| 819 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 820 | \begin{macrodesc}{indexii}{\p{word1}\p{word2}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 821 | Build two index entries. This is exactly equivalent to using |
| 822 | \code{\e index\{\var{word1}!\var{word2}\}} and |
| 823 | \code{\e index\{\var{word2}!\var{word1}\}}. |
| 824 | \end{macrodesc} |
| 825 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 826 | \begin{macrodesc}{indexiii}{\p{word1}\p{word2}\p{word3}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 827 | Build three index entries. This is exactly equivalent to using |
| 828 | \code{\e index\{\var{word1}!\var{word2} \var{word3}\}}, |
| 829 | \code{\e index\{\var{word2}!\var{word3}, \var{word1}\}}, and |
| 830 | \code{\e index\{\var{word3}!\var{word1} \var{word2}\}}. |
| 831 | \end{macrodesc} |
| 832 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 833 | \begin{macrodesc}{indexiv}{\p{word1}\p{word2}\p{word3}\p{word4}} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 834 | Build four index entries. This is exactly equivalent to using |
| 835 | \code{\e index\{\var{word1}!\var{word2} \var{word3} \var{word4}\}}, |
| 836 | \code{\e index\{\var{word2}!\var{word3} \var{word4}, \var{word1}\}}, |
| 837 | \code{\e index\{\var{word3}!\var{word4}, \var{word1} \var{word2}\}}, |
| 838 | and |
| 839 | \code{\e index\{\var{word4}!\var{word1} \var{word2} \var{word3}\}}. |
| 840 | \end{macrodesc} |
| 841 | |
| 842 | |
| 843 | \section{Special Names} |
| 844 | |
| 845 | Many special names are used in the Python documentation, including |
| 846 | the names of operating systems, programming languages, standards |
| 847 | bodies, and the like. Many of these were assigned \LaTeX{} macros |
| 848 | at some point in the distant past, and these macros lived on long |
| 849 | past their usefulness. In the current markup, these entities are |
| 850 | not assigned any special markup, but the preferred spellings are |
| 851 | given here to aid authors in maintaining the consistency of |
| 852 | presentation in the Python documentation. |
| 853 | |
| 854 | \begin{description} |
| 855 | \item[POSIX] |
| 856 | The name assigned to a particular group of standards. This is |
| 857 | always uppercase. |
| 858 | |
| 859 | \item[Python] |
| 860 | The name of our favorite programming language is always |
| 861 | capitalized. |
| 862 | \end{description} |
| 863 | |
| 864 | |
| 865 | \section{Processing Tools} |
| 866 | |
| 867 | \subsection{External Tools} |
| 868 | |
| 869 | Many tools are needed to be able to process the Python |
| 870 | documentation if all supported formats are required. This |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 871 | section lists the tools used and when each is required. Consult |
| 872 | the \file{Doc/README} file to see if there are specific version |
| 873 | requirements for any of these. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 874 | |
| 875 | \begin{description} |
| 876 | \item[\program{dvips}] |
| 877 | This program is a typical part of \TeX{} installations. It is |
| 878 | used to generate PostScript from the ``device independent'' |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 879 | \file{.dvi} files. It is needed for the conversion to |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 880 | PostScript. |
| 881 | |
| 882 | \item[\program{emacs}] |
| 883 | Emacs is the kitchen sink of programmers' editors, and a damn |
| 884 | fine kitchen sink it is. It also comes with some of the |
| 885 | processing needed to support the proper menu structures for |
| 886 | Texinfo documents when an info conversion is desired. This is |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 887 | needed for the info conversion. Using \program{xemacs} |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 888 | instead of FSF \program{emacs} may lead to instability in the |
| 889 | conversion, but that's because nobody seems to maintain the |
| 890 | Emacs Texinfo code in a portable manner. |
| 891 | |
| 892 | \item[\program{latex}] |
| 893 | This is a world-class typesetter by Donald Knuth. It is used |
| 894 | for the conversion to PostScript, and is needed for the HTML |
| 895 | conversion as well (\LaTeX2HTML requires one of the |
| 896 | intermediate files it creates). |
| 897 | |
| 898 | \item[\program{latex2html}] |
| 899 | Probably the longest Perl script anyone ever attempted to |
| 900 | maintain. This converts \LaTeX{} documents to HTML documents, |
| 901 | and does a pretty reasonable job. It is required for the |
| 902 | conversions to HTML and GNU info. |
| 903 | |
| 904 | \item[\program{lynx}] |
| 905 | This is a text-mode Web browser which includes an |
| 906 | HTML-to-plain text conversion. This is used to convert |
| 907 | \code{howto} documents to text. |
| 908 | |
| 909 | \item[\program{make}] |
| 910 | Just about any version should work for the standard documents, |
| 911 | but GNU \program{make} is required for the experimental |
| 912 | processes in \file{Doc/tools/sgmlconv/}, at least while |
| 913 | they're experimental. |
| 914 | |
| 915 | \item[\program{makeindex}] |
| 916 | This is a standard program for converting \LaTeX{} index data |
| 917 | to a formatted index; it should be included with all \LaTeX{} |
| 918 | installations. It is needed for the PDF and PostScript |
| 919 | conversions. |
| 920 | |
| 921 | \item[\program{makeinfo}] |
| 922 | GNU \program{makeinfo} is used to convert Texinfo documents to |
| 923 | GNU info files. Since Texinfo is used as an intermediate |
| 924 | format in the info conversion, this program is needed in that |
| 925 | conversion. |
| 926 | |
| 927 | \item[\program{pdflatex}] |
| 928 | pdf\TeX{} is a relatively new variant of \TeX, and is used to |
| 929 | generate the PDF version of the manuals. It is typically |
| 930 | installed as part of most of the large \TeX{} distributions. |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 931 | \program{pdflatex} is pdf\TeX{} using the \LaTeX{} format. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 932 | |
| 933 | \item[\program{perl}] |
| 934 | Perl is required for \LaTeX2HTML{} and one of the scripts used |
| 935 | to post-process \LaTeX2HTML output, as well as the |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 936 | HTML-to-Texinfo conversion. This is required for |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 937 | the HTML and GNU info conversions. |
| 938 | |
| 939 | \item[\program{python}] |
| 940 | Python is used for many of the scripts in the |
| 941 | \file{Doc/tools/} directory; it is required for all |
| 942 | conversions. This shouldn't be a problem if you're interested |
| 943 | in writing documentation for Python! |
| 944 | \end{description} |
| 945 | |
| 946 | |
| 947 | \subsection{Internal Tools} |
| 948 | |
| 949 | This section describes the various scripts that are used to |
| 950 | implement various stages of document processing or to orchestrate |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 951 | entire build sequences. Most of these tools are only useful |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 952 | in the context of building the standard documentation, but some |
| 953 | are more general. |
| 954 | |
| 955 | \begin{description} |
| 956 | \item[\program{mkhowto}] |
Fred Drake | 87f768e | 1999-05-17 15:22:45 +0000 | [diff] [blame] | 957 | This is the primary script used to format third-party |
| 958 | documents. It contains all the logic needed to ``get it |
| 959 | right.'' The proper way to use this script is to make a |
| 960 | symbolic link to it or run it in place; the actual script file |
| 961 | must be stored as part of the documentation source tree, |
| 962 | though it may be used to format documents outside the |
Fred Drake | d290c10 | 1999-11-09 18:03:00 +0000 | [diff] [blame] | 963 | tree. Use \program{mkhowto} \programopt{-}\programopt{-help} |
| 964 | for a list of |
Fred Drake | d2a727f | 1999-05-27 21:45:54 +0000 | [diff] [blame] | 965 | command line options. |
Fred Drake | 87f768e | 1999-05-17 15:22:45 +0000 | [diff] [blame] | 966 | |
Fred Drake | d1fb779 | 1999-05-17 16:33:54 +0000 | [diff] [blame] | 967 | \program{mkhowto} can be used for both \code{howto} and |
| 968 | \code{manual} class documents. (For the later, be sure to get |
| 969 | the latest version from the Python CVS repository rather than |
| 970 | the version distributed in the \file{latex-1.5.2.tgz} source |
| 971 | archive.) |
| 972 | |
Fred Drake | 87f768e | 1999-05-17 15:22:45 +0000 | [diff] [blame] | 973 | XXX Need more here. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 974 | \end{description} |
| 975 | |
| 976 | |
| 977 | \section{Future Directions \label{futures}} |
| 978 | |
| 979 | The history of the Python documentation is full of changes, most of |
| 980 | which have been fairly small and evolutionary. There has been a |
| 981 | great deal of discussion about making large changes in the markup |
| 982 | languages and tools used to process the documentation. This section |
| 983 | deals with the nature of the changes and what appears to be the most |
| 984 | likely path of future development. |
| 985 | |
| 986 | \subsection{Structured Documentation \label{structured}} |
| 987 | |
| 988 | Most of the small changes to the \LaTeX{} markup have been made |
| 989 | with an eye to divorcing the markup from the presentation, making |
| 990 | both a bit more maintainable. Over the course of 1998, a large |
| 991 | number of changes were made with exactly this in mind; previously, |
| 992 | changes had been made but in a less systematic manner and with |
| 993 | more concern for not needing to update the existing content. The |
| 994 | result has been a highly structured and semantically loaded markup |
| 995 | language implemented in \LaTeX. With almost no basic \TeX{} or |
| 996 | \LaTeX{} markup in use, however, the markup syntax is about the |
| 997 | only evidence of \LaTeX{} in the actual document sources. |
| 998 | |
| 999 | One side effect of this is that while we've been able to use |
| 1000 | standard ``engines'' for manipulating the documents, such as |
| 1001 | \LaTeX{} and \LaTeX2HTML, most of the actual transformations have |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 1002 | been created specifically for Python. The \LaTeX{} document |
| 1003 | classes and \LaTeX2HTML support are both complete implementations |
| 1004 | of the specific markup designed for these documents. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 1005 | |
| 1006 | Combining highly customized markup with the somewhat esoteric |
| 1007 | systems used to process the documents leads us to ask some |
| 1008 | questions: Can we do this more easily? and, Can we do this |
| 1009 | better? After a great deal of discussion with the community, we |
| 1010 | have determined that actively pursuing modern structured |
Fred Drake | 2c4e009 | 1999-03-29 14:55:55 +0000 | [diff] [blame] | 1011 | documentation systems is worth some investment of time. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 1012 | |
| 1013 | There appear to be two real contenders in this arena: the Standard |
| 1014 | General Markup Language (SGML), and the Extensible Markup Language |
| 1015 | (XML). Both of these standards have advantages and disadvantages, |
| 1016 | and many advantages are shared. |
| 1017 | |
| 1018 | SGML offers advantages which may appeal most to authors, |
| 1019 | especially those using ordinary text editors. There are also |
| 1020 | additional abilities to define content models. A number of |
| 1021 | high-quality tools with demonstrated maturity is available, but |
| 1022 | most are not free; for those which are, portability issues remain |
| 1023 | a problem. |
| 1024 | |
| 1025 | The advantages of XML include the availability of a large number |
| 1026 | of evolving tools. Unfortunately, many of the associated |
| 1027 | standards are still evolving, and the tools will have to follow |
| 1028 | along. This means that developing a robust tool set that uses |
| 1029 | more than the basic XML 1.0 recommendation is not possible in the |
| 1030 | short term. The promised availability of a wide variety of |
| 1031 | high-quality tools which support some of the most important |
| 1032 | related standards is not immediate. Many tools are likely to be |
| 1033 | free. |
| 1034 | |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 1035 | XXX Eventual migration to SGML/XML. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 1036 | |
| 1037 | \subsection{Discussion Forums \label{discussion}} |
| 1038 | |
| 1039 | Discussion of the future of the Python documentation and related |
Fred Drake | 7a737df | 1999-04-23 14:41:44 +0000 | [diff] [blame] | 1040 | topics takes place in the Documentation Special Interest Group, or |
| 1041 | ``Doc-SIG.'' Information on the group, including mailing list |
| 1042 | archives and subscription information, is available at |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 1043 | \url{http://www.python.org/sigs/doc-sig/}. The SIG is open to all |
| 1044 | interested parties. |
| 1045 | |
| 1046 | Comments and bug reports on the standard documents should be sent |
| 1047 | to \email{python-docs@python.org}. This may include comments |
Fred Drake | adade92 | 1999-04-22 13:05:27 +0000 | [diff] [blame] | 1048 | about formatting, content, grammatical and spelling errors, or |
Fred Drake | d1fb779 | 1999-05-17 16:33:54 +0000 | [diff] [blame] | 1049 | this document. You can also send comments on this document |
| 1050 | directly to the author at \email{fdrake@acm.org}. |
Fred Drake | acffaee | 1999-03-16 16:09:13 +0000 | [diff] [blame] | 1051 | |
| 1052 | \end{document} |