[Python-checkins] CVS: python/dist/src/Tools/compiler/doc compiler.tex,1.3,1.4

Fred L. Drake fdrake@users.sourceforge.net
2001年8月15日 10:01:36 -0700

• Previous message: [Python-checkins] CVS: python/dist/src/Tools/compiler/doc asttable.tex,1.1,1.2
• Next message: [Python-checkins] CVS: python/dist/src configure,1.237,1.238 configure.in,1.246,1.247 pyconfig.h.in,1.4,1.5
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

---

Update of /cvsroot/python/python/dist/src/Tools/compiler/doc
In directory usw-pr-cvs1:/tmp/cvs-serv22501
Modified Files:
	compiler.tex 
Log Message:
Use the "howto" document class rather than the "manual" class.
Remove the module index; there aren't enough modules documented yet
for this to make sense.
Add a couple more index entries, fixed a few typos, and adjusted a few
more things for consistency.
Index: compiler.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Tools/compiler/doc/compiler.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** compiler.tex	2001年08月15日 14:35:13	1.3
--- compiler.tex	2001年08月15日 17:01:34	1.4
***************
*** 6,10 ****
 % http://www.python.org/doc/current/doc/doc.html
 
! \documentclass{manual}
 
 \title{Python compiler package}
--- 6,10 ----
 % http://www.python.org/doc/current/doc/doc.html
 
! \documentclass{howto}
 
 \title{Python compiler package}
***************
*** 16,20 ****
 \authoraddress{
 PythonLabs \\
! Zope Corp. \\
 Email: \email{jeremy@zope.com}
 }
--- 16,20 ----
 \authoraddress{
 PythonLabs \\
! Zope Corporation \\
 Email: \email{jeremy@zope.com}
 }
***************
*** 37,47 ****
 \maketitle
 
- % This makes the contents more accessible from the front page of the HTML.
- \ifhtml
- \chapter*{Front Matter\label{front}}
- \fi
- 
- %\input{copyright}
- 
 \begin{abstract}
 
--- 37,40 ----
***************
*** 56,60 ****
 \tableofcontents
 
! \chapter{Introduction\label{Introduction}}
 
 XXX Need basic intro
--- 49,54 ----
 \tableofcontents
 
! 
! \section{Introduction\label{Introduction}}
 
 XXX Need basic intro
***************
*** 63,68 ****
--- 57,65 ----
 closer to the python source...
 
+ 
 \section{The basic interface}
 
+ \declaremodule{}{compiler}
+ 
 The top-level of the package defines four functions.
 
***************
*** 80,97 ****
 \end{funcdesc}
 
! \begin{funcdesc}{walk}{ast, visitor, \optional{verbose=None}}
 Do a pre-order walk over the abstract syntax tree \var{ast}. Call the
 appropriate method on the \var{visitor} instance for each node
! encountered. 
 \end{funcdesc}
 
! \begin{funcdesc}{compile}{filename}
! Compile the file \var{filename} and generated \var{filename}.pyc.
 \end{funcdesc}
 
 The \module{compiler} package contains the following modules:
! \module{ast}, \module{consts}, \module{future}, \module{misc},
! \module{pyassem}, \module{pycodegen}, \module{symbols},
! \module{transformer}, and \module{visitor}.
 
 \section{Limitations}
--- 77,96 ----
 \end{funcdesc}
 
! \begin{funcdesc}{walk}{ast, visitor\optional{, verbose}}
 Do a pre-order walk over the abstract syntax tree \var{ast}. Call the
 appropriate method on the \var{visitor} instance for each node
! encountered.
 \end{funcdesc}
 
! \begin{funcdesc}{compile}{path}
! Compile the file \var{path} and generate the corresponding \file{.pyc}
! file.
 \end{funcdesc}
 
 The \module{compiler} package contains the following modules:
! \refmodule[compiler.ast]{ast}, \module{consts}, \module{future},
! \module{misc}, \module{pyassem}, \module{pycodegen}, \module{symbols},
! \module{transformer}, and \refmodule[compiler.visitor]{visitor}.
! 
 
 \section{Limitations}
***************
*** 107,113 ****
 \code{def f(x, x): ...}
 
- \chapter{Python Abstract Syntax}
 
! \section{Introduction}
 
 The \module{compiler.ast} module defines an abstract syntax for
--- 106,111 ----
 \code{def f(x, x): ...}
 
 
! \section{Python Abstract Syntax}
 
 The \module{compiler.ast} module defines an abstract syntax for
***************
*** 116,125 ****
 
 The abstract syntax offers a higher level interface to parsed Python
! source code. The \module{parser} module and the compiler written in C
! for the Python interpreter use a concrete syntax tree. The concrete
! syntax is tied closely to the grammar description used for the Python
! parser. Instead of a single node for a construct, there are often
! several levels of nested nodes that are introduced by Python's
! precedence rules.
 
 The abstract syntax tree is created by the
--- 114,124 ----
 
 The abstract syntax offers a higher level interface to parsed Python
! source code. The \ulink{\module{parser}}
! {http://www.python.org/doc/current/lib/module-parser.html}
! module and the compiler written in C for the Python interpreter use a
! concrete syntax tree. The concrete syntax is tied closely to the
! grammar description used for the Python parser. Instead of a single
! node for a construct, there are often several levels of nested nodes
! that are introduced by Python's precedence rules.
 
 The abstract syntax tree is created by the
***************
*** 128,143 ****
 generates an abstract syntax tree from the concrete tree. 
 
! The \module{transformer} module was created by Greg Stein and Bill
! Tutt for the Python-to-C compiler. The current version contains a
 number of modifications and improvements, but the basic form of the
 abstract syntax and of the transformer are due to Stein and Tutt.
 
 \section{AST Nodes}
 
! The \module{ast} module is generated from a text file that describes
! each node type and its elements. Each node type is represented as a
! class that inherits from the abstract base class \class{ast.Node} and
! defines a set of named attributes for child nodes.
 
 \begin{classdesc}{Node}{}
 
--- 127,147 ----
 generates an abstract syntax tree from the concrete tree. 
 
! The \module{transformer} module was created by Greg
! Stein\index{Stein, Greg} and Bill Tutt\index{Tutt, Bill} for an
! experimental Python-to-C compiler. The current version contains a
 number of modifications and improvements, but the basic form of the
 abstract syntax and of the transformer are due to Stein and Tutt.
 
+ 
 \section{AST Nodes}
 
! \declaremodule{}{compiler.ast}
 
+ The \module{compiler.ast} module is generated from a text file that
+ describes each node type and its elements. Each node type is
+ represented as a class that inherits from the abstract base class
+ \class{compiler.ast.Node} and defines a set of named attributes for
+ child nodes.
+ 
 \begin{classdesc}{Node}{}
 
***************
*** 154,177 ****
 be \code{None}. XXX Not sure what the rules are for which nodes
 will have a useful lineno.
 
! \begin{methoddesc}{getChildren}{}
! Returns a flattened list of the child nodes and objects in the
! order they occur. Specifically, the order of the nodes is the
! order in which they appear in the Python grammar. Not all of the
! children are \class{Node} instances. The names of functions and
! classes, for example, are plain strings.
! \end{methoddesc}
 
! \begin{methoddesc}{getChildNodes}{}
! Returns a flattened list of the child nodes in the order they
! occur. This method is like \method{getChildNodes()}, except that it
! only returns those children that are \class{Node} instances.
! \end{methoddesc}
 
! \end{classdesc}
 
 Two examples illustrate the general structure of \class{Node}
! classes. The while statement is defined by the following grammar
! production: 
 
 \begin{verbatim}
--- 158,182 ----
 be \code{None}. XXX Not sure what the rules are for which nodes
 will have a useful lineno.
+ \end{classdesc}
 
! All \class{Node} objects offer the following methods:
 
! \begin{methoddesc}{getChildren}{}
! Returns a flattened list of the child nodes and objects in the
! order they occur. Specifically, the order of the nodes is the
! order in which they appear in the Python grammar. Not all of the
! children are \class{Node} instances. The names of functions and
! classes, for example, are plain strings.
! \end{methoddesc}
 
! \begin{methoddesc}{getChildNodes}{}
! Returns a flattened list of the child nodes in the order they
! occur. This method is like \method{getChildren()}, except that it
! only returns those children that are \class{Node} instances.
! \end{methoddesc}
 
 Two examples illustrate the general structure of \class{Node}
! classes. The \keyword{while} statement is defined by the following
! grammar production: 
 
 \begin{verbatim}
***************
*** 183,191 ****
 \member{body}, and \member{else_}. (If the natural name for an
 attribute is also a Python reserved word, it can't be used as an
! attribute name. An underscore is appended to the word to make it
! legal, hence \code{else_} instead of \code{else}.)
 
! The if statement is more complicated because it can include several
! tests. 
 
 \begin{verbatim}
--- 188,196 ----
 \member{body}, and \member{else_}. (If the natural name for an
 attribute is also a Python reserved word, it can't be used as an
! attribute name. An underscore is appended to the word to make it a
! legal identifier, hence \member{else_} instead of \keyword{else}.)
 
! The \keyword{if} statement is more complicated because it can include
! several tests. 
 
 \begin{verbatim}
***************
*** 195,208 ****
 The \class{If} node only defines two attributes: \member{tests} and
 \member{else_}. The \member{tests} attribute is a sequence of test
! expression, consequent body pairs. There is one pair of each if/elif
! clause. The first element of the pair is the test expression. The
! second elements is a \class{Stmt} node that contains the code to
! execute if the test is true.
 
 The \method{getChildren()} method of \class{If} returns a flat list of
! child nodes. If there are three if/elif clauses and no else clause,
! then \method{getChildren()} will return a list of six elements: the
! first test expression, the first \class{Stmt}, the second text
! expression, etc.
 
 The following table lists each of the \class{Node} subclasses defined
--- 200,213 ----
 The \class{If} node only defines two attributes: \member{tests} and
 \member{else_}. The \member{tests} attribute is a sequence of test
! expression, consequent body pairs. There is one pair for each
! \keyword{if}/\keyword{elif} clause. The first element of the pair is
! the test expression. The second elements is a \class{Stmt} node that
! contains the code to execute if the test is true.
 
 The \method{getChildren()} method of \class{If} returns a flat list of
! child nodes. If there are three \keyword{if}/\keyword{elif} clauses
! and no \keyword{else} clause, then \method{getChildren()} will return
! a list of six elements: the first test expression, the first
! \class{Stmt}, the second text expression, etc.
 
 The following table lists each of the \class{Node} subclasses defined
***************
*** 216,219 ****
--- 221,225 ----
 \input{asttable}
 
+ 
 \section{Assignment nodes}
 
***************
*** 230,236 ****
 as an example. Explain what the flags are for.
 
- \chapter{Using Visitors to Walk ASTs}
 
! The visitor pattern is ... The \module{compiler} package uses a
 variant on the visitor pattern that takes advantage of Python's
 introspection features to elminiate the need for much of the visitor's
--- 236,245 ----
 as an example. Explain what the flags are for.
 
 
! \section{Using Visitors to Walk ASTs}
! 
! \declaremodule{}{compiler.visitor}
! 
! The visitor pattern is ... The \refmodule{compiler} package uses a
 variant on the visitor pattern that takes advantage of Python's
 introspection features to elminiate the need for much of the visitor's
***************
*** 244,247 ****
--- 253,259 ----
 XXX The magic \method{visit()} method for visitors.
 
+ \begin{funcdesc}{walk}{tree, visitor\optional{, verbose}}
+ \end{funcdesc}
+ 
 \begin{classdesc}{ASTVisitor}{}
 
***************
*** 260,270 ****
 found for a particular node type, the \method{default()} method is
 called. 
 
 XXX describe extra arguments
 
! \begin{methoddesc}{default}{node\optional{, *args}}
 \end{methoddesc}
 
! \begin{methoddesc}{dispatch}{node\optional{, *args}}
 \end{methoddesc}
 
--- 272,285 ----
 found for a particular node type, the \method{default()} method is
 called. 
+ \end{classdesc}
 
+ \class{ASTVisitor} objects have the following methods:
+ 
 XXX describe extra arguments
 
! \begin{methoddesc}{default}{node\optional{, \moreargs}}
 \end{methoddesc}
 
! \begin{methoddesc}{dispatch}{node\optional{, \moreargs}}
 \end{methoddesc}
 
***************
*** 272,283 ****
 \end{methoddesc}
 
- \end{classdesc}
 
! \begin{funcdesc}{walk}{tree, visitor\optional{, verbose=None}}
! \end{funcdesc}
! 
! \chapter{Bytecode Generation}
 
! The code generator is a visit that emits bytecodes. Each visit method
 can call the \method{emit()} method to emit a new bytecode. The basic
 code generator is specialized for modules, classes, and functions. An
--- 287,294 ----
 \end{methoddesc}
 
 
! \section{Bytecode Generation}
 
! The code generator is a visitor that emits bytecodes. Each visit method
 can call the \method{emit()} method to emit a new bytecode. The basic
 code generator is specialized for modules, classes, and functions. An
***************
*** 286,306 ****
 objects and calculation of jump offsets.
 
- %
- % The ugly "%begin{latexonly}" pseudo-environments are really just to
- % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
- % not really valuable.
- %
- % If you don't want the Module Index, you can remove all of this up
- % until the second \input line.
- %
- %begin{latexonly}
- \renewcommand{\indexname}{Module Index}
- %end{latexonly}
- \input{mod\jobname.ind} % Module Index
 
! %begin{latexonly}
! \renewcommand{\indexname}{Index}
! %end{latexonly}
! \input{\jobname.ind} % Index
 
 \end{document}
--- 297,302 ----
 objects and calculation of jump offsets.
 
 
! \input{compiler.ind} % Index
 
 \end{document}

---

• Previous message: [Python-checkins] CVS: python/dist/src/Tools/compiler/doc asttable.tex,1.1,1.2
• Next message: [Python-checkins] CVS: python/dist/src configure,1.237,1.238 configure.in,1.246,1.247 pyconfig.h.in,1.4,1.5
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]