[Docutils-users] docutils-xml.py chokes on this document

[Paul T. <pht...@ea...>]

I'm not sure what is happening, but when I run docutils-xml.py on the
document (below), it seems to get stuck. I wait and wait for this small
document to get processed, and nothing happens.

I also ran it with the --debug option, and printed the result as well.

Thanks

Paul



***********************************************************
document that caused the choke
***********************************************************

rst2docbook
^^^^^^^^^^^

:author:

  :first: Paul

  :surname: Tremblay

  :email: pht...@ea...


:revision:

  :revnumber: .1

  :date: 2003-06-17

  :revremark: First working copy in cvs.

========
Overview
========

The script rst2docbook converst rst documents to docbook. It does so by first
using the docutils-xml.py script to convert the file to XML. It then further
converts inline markup (if any exists) to XML inline markup, using my script
docutils-nest-xml.py. Last, it uses an xslt processor and my own style sheets
to convert the XML document produced by the docuitls-nest-xml.py into
docbook.xml.

============
Installation
============

Requirements
============

1. An xslt processor. So far, the script supports xmllint ("xsltproc" from the command line); 4suite; and xalan. Saxxon is not yet supported, thought I will probably add support soon.

2. Python. 

3. The docuitls module. 

4. The docutils_nest module, found at the same place as this module.

Installation
============

1. Download the cvs directory. 

   :command:

     cvs -z3 -d:pserver:ano...@cv...:/cvsroot/docutils co sandbox/    paultremblay

2. Install the module nested_utils. (Follow the instructions provided in this module.)

3. Change to the directory sandbox/paultremblay/rst_to_docbook. 

4. Configure your setup. You need to tell the script where you want the
   configuration files, and what type of XSLT processor you will use. For
   example, if you want to put your configuration files in the directory
   "/etc", and you want to use xmllint as your XSLT processor, you type:

   :command:

     python configure --target /etc --processor xmllint

   This command will creates the directory "/etc/.rst_to_docbook". 

   You can also use the abbrevieted forms, where -t is identical to --target,
   and -p is identical to --processor. The following command is identical to
   the one above:

   :command:

    python configure -t /etc -p xmllint


   You can choose no argument at all when you configure:

   :command: python configure

   However, if you choose no options, the setup script will try to create a
   directory /etc/.rst_to_docbook, and will try to use xmllint as your
   processor. If the dirctory /etc does not exist on your system, or if you
   do not have write permission to it, the setup will also fail. If you do not
   have xmllint installed, the configure script will fail, and you cannot
   install rst2xml.

   You must have an accpeptable XSLT processor in order for the setup to work!
   Acceptable XSLT processors are xmllint, xalan, and 4suite.

5. Build and install in the normal way for python:

   :command: python setup.py build

   :command: python setup.py install

===
Use
===

The script rst2xml is a command-line utility. It must be run from the shell, and has no graphical user interface. (That means you will see now windows with buttons, and cannot use your mouse to control any commands.) 

In order to convert an rst document to docbook, type:

  :command:

    rst2docbook --output output.xml my_documents.rst

This command creates a new document, output.xml. If the document output.xml already existed, then it will be overwritten. *You must specify an --output option in order for the script to work!*

WARNING: Do not use the "-o" as a substitute for "--output". The "-o" option is used by the docutils-xml.py script, the main processing script for converting to docbook. 

Options
-------

rst2docbook
^^^^^^^^^^^
The script rst2docbook allows only one other option, "--debug-doc". This option
creates the debug directory in the .rst_to_docbook directory, and makes a copy
of the the file as it is processed at each step. If the .rst_to_docbook/debug
already exists, rst2docbook removes all the files in it before it begins
processing the documents.

docutils-xml.py
^^^^^^^^^^^^^^^

Since rst2docbook uses docutils-xml.py to do most of the parsing, you can use any of the optiosn available to the docutils-xml.py script. For example, if you wanted to use indents, you type:

  :command:

    rst2docbook --output output.xml --indents my_doc.rst

If you want a list of all the options for docutils-xml.py, type:

  :command: docutils-xml.py --help
    



******************************************************************
End of the document
******************************************************************

******************************************************************
output from docuitils-xml.py --debug rst2docbook.rst)
******************************************************************





StateMachine.run: input_lines (line_offset=-1):
| rst2docbook
| ^^^^^^^^^^^
| 
| :author:
| 
|   :first: Paul
| 
|   :surname: Tremblay
| 
|   :email: pht...@ea...
| 
| 
| :revision:
| 
|   :revnumber: .1
| 
|   :date: 2003-06-17
| 
|   :revremark: First working copy in cvs.
| 
| ========
| Overview
| ========
| 
| The script rst2docbook converst rst documents to docbook. It does so by first
| using the docutils-xml.py script to convert the file to XML. It then further
| converts inline markup (if any exists) to XML inline markup, using my script
| docutils-nest-xml.py. Last, it uses an xslt processor and my own style sheets
| to convert the XML document produced by the docuitls-nest-xml.py into
| docbook.xml.
| 
| ============
| Installation
| ============
| 
| Requirements
| ============
| 
| 1. An xslt processor. So far, the script supports xmllint ("xsltproc" from the command line); 4suite; and xalan. Saxxon is not yet supported, thought I will probably add support soon.
| 
| 2. Python. 
| 
| 3. The docuitls module. 
| 
| 4. The docutils_nest module, found at the same place as this module.
| 
| Installation
| ============
| 
| 1. Download the cvs directory. 
| 
|    :command:
| 
|      cvs -z3 -d:pserver:ano...@cv...:/cvsroot/docutils co sandbox/    paultremblay
| 
| 2. Install the module nested_utils. (Follow the instructions provided in this module.)
| 
| 3. Change to the directory sandbox/paultremblay/rst_to_docbook. 
| 
| 4. Configure your setup. You need to tell the script where you want the
|    configuration files, and what type of XSLT processor you will use. For
|    example, if you want to put your configuration files in the directory
|    "/etc", and you want to use xmllint as your XSLT processor, you type:
| 
|    :command:
| 
|      python configure --target /etc --processor xmllint
| 
|    This command will creates the directory "/etc/.rst_to_docbook". 
| 
|    You can also use the abbrevieted forms, where -t is identical to --target,
|    and -p is identical to --processor. The following command is identical to
|    the one above:
| 
|    :command:
| 
|     python configure -t /etc -p xmllint
| 
| 
|    You can choose no argument at all when you configure:
| 
|    :command: python configure
| 
|    However, if you choose no options, the setup script will try to create a
|    directory /etc/.rst_to_docbook, and will try to use xmllint as your
|    processor. If the dirctory /etc does not exist on your system, or if you
|    do not have write permission to it, the setup will also fail. If you do not
|    have xmllint installed, the configure script will fail, and you cannot
|    install rst2xml.
| 
|    You must have an accpeptable XSLT processor in order for the setup to work!
|    Acceptable XSLT processors are xmllint, xalan, and 4suite.
| 
| 5. Build and install in the normal way for python:
| 
|    :command: python setup.py build
| 
|    :command: python setup.py install
| 
| ===
| Use
| ===
| 
| The script rst2xml is a command-line utility. It must be run from the shell, and has no graphical user interface. (That means you will see now windows with buttons, and cannot use your mouse to control any commands.) 
| 
| In order to convert an rst document to docbook, type:
| 
|   :command:
| 
|     rst2docbook --output output.xml my_documents.rst
| 
| This command creates a new document, output.xml. If the document output.xml already existed, then it will be overwritten. *You must specify an --output option in order for the script to work!*
| 
| WARNING: Do not use the "-o" as a substitute for "--output". The "-o" option is used by the docutils-xml.py script, the main processing script for converting to docbook. 
| 
| Options
| -------
| 
| rst2docbook
| ^^^^^^^^^^^
| The script rst2docbook allows only one other option, "--debug". This option
| creates the debug directory in the .rst_to_docbook directory, and makes a copy
| of the the file as it is processed at each step. If the .rst_to_docbook/debug
| already exists, rst2docbook removes all the files in it before it begins
| processing the documents.
| 
| docutils-xml.py
| ^^^^^^^^^^^^^^^
| 
| Since rst2docbook uses docutils-xml.py to do most of the parsing, you can use any of the optiosn available to the docutils-xml.py script. For example, if you wanted to use indents, you type:
| 
|   :command:
| 
|     rst2docbook --output output.xml --indents my_doc.rst
| 
| If you want a list of all the options for docutils-xml.py, type:
| 
|   :command: docutils-xml.py --help
|     
| 
| 

StateMachine.run: bof transition

StateMachine.run: line (source='rst2docbook.rst', offset=0):
| rst2docbook

StateMachine.check_line: state="Body", transitions=['blank', 'indent', 'bullet', 'enumerator', 'field_marker', 'option_marker', 'doctest', 'grid_table_top', 'simple_table_top', 'explicit_markup', 'anonymous', 'line', 'text'].

StateMachine.check_line: Matched transition "text" in state "Body".

StateMachine.get_state: Changing state from "Body" to "Text" (input line 1).

StateMachine.run: line (source='rst2docbook.rst', offset=1):
| ^^^^^^^^^^^

StateMachine.check_line: state="Text", transitions=['blank', 'indent', 'underline', 'text'].

StateMachine.check_line: Matched transition "underline" in state "Text".

StateMachine.run: input_lines (line_offset=-1):
| 
| :author:
| 
|   :first: Paul
| 
|   :surname: Tremblay
| 
|   :email: pht...@ea...
| 
| 
| :revision:
| 
|   :revnumber: .1
| 
|   :date: 2003-06-17
| 
|   :revremark: First working copy in cvs.
| 
| ========
| Overview
| ========
| 
| The script rst2docbook converst rst documents to docbook. It does so by first
| using the docutils-xml.py script to convert the file to XML. It then further
| converts inline markup (if any exists) to XML inline markup, using my script
| docutils-nest-xml.py. Last, it uses an xslt processor and my own style sheets
| to convert the XML document produced by the docuitls-nest-xml.py into
| docbook.xml.
| 
| ============
| Installation
| ============
| 
| Requirements
| ============
| 
| 1. An xslt processor. So far, the script supports xmllint ("xsltproc" from the command line); 4suite; and xalan. Saxxon is not yet supported, thought I will probably add support soon.
| 

And so on.. The pattern keeps repeating itself.



-- 

************************
*Paul Tremblay         *
*pht...@ea...*
************************