[Docutils-checkins] r4976 - trunk/sandbox/codeintro/codeintro.txt

[<joh...@us...>]

Author: johnmulder
Date: 2007-03-01 19:11:52 +0100 (Thu, 01 Mar 2007)
New Revision: 4976

Modified:
   trunk/sandbox/codeintro/codeintro.txt
Log:
Improved the description of the flow of execution.

Modified: trunk/sandbox/codeintro/codeintro.txt
===================================================================
--- trunk/sandbox/codeintro/codeintro.txt	2007-03-01 18:08:32 UTC (rev 4975)
+++ trunk/sandbox/codeintro/codeintro.txt	2007-03-01 18:11:52 UTC (rev 4976)
@@ -31,33 +31,39 @@
 .. _repository instructions: 
   http://docutils.sourceforge.net/docs/dev/repository.html
 
-Organization of the Docutils Code
-=================================
-Within the docutils directory, the package for docutils is in a 
-subdirectory also called docutils. This contains both
-modules and subpackages.
+Docutils Flow of Execution
+==========================
+The flow of a document through a docutils utility starts with a 
+`Publisher` object from `docutils/core.py`. The publisher then 
+calls the following:
 
-The flow of a document through a docutils utility, like the ones included
-in `docutils/tools` is as follows:
+1. Reader in: `docutils/readers`
 
-1. Reader defined in: `docutils/readers`
+   a. Scan input text from file, string, or pre-proccessed document
+      tree. Uses a subclass of `Input` in:
+      `docutils/io.py`
+   b. Parse text into document tree. The parser chosen depends on
+      the document format of the input. Uses a parser in:
+      `docutils/parsers/`
 
-   a. input from file
-   b. parse text into document tree, using a parser in:
-      `docutils/parsers/`
-   c. apply transform(s) to the document tree as needed for the specific
-      input format, using transforms in:
+2. Transformer in: `docutils/transforms/__init__.py`
+   a. Apply transforms to the document tree as
+      determined by the reader and writer. Uses transforms in:
       `docutils/transforms/`
 
-2. Writer defined in: `docutils/writer`
+3. Writer in: `docutils/writer`
 
-   a. takes document tree as input
-   b. using a subclass of `docutils.nodes.NodeVisitor`, perform
-      traverse of the doctree using the `Node.walkabout()` function in:
+   a. Takes document tree as input.
+   b. Instanciates a subclass of `docutils.nodes.NodeVisitor` which
+      traverses the doctree using the `Node.walkabout()` function in:
       `docutils/nodes/nodes.py`
+
+Organization of the Docutils Code
+=================================
+Within the docutils directory, the package for docutils is in a 
+subdirectory also called docutils. This contains both
+modules and subpackages.
       
-   
-   
 Modules in Docutils
 ===================
 __init__.py