Thanks for the answer David.

I am using standard versions of docutils and python. By standard I mean the ones provided by macports with no modifications.

python version is 2.6.1
docutils version is 0.5

But you are right when you said that I modified the default configuration. here is a minimal code that reproduces the problem:

a ReST file named a.rst  contains just :
RFC 1234

a Python script :

import docutils.parsers.rst
text = open('a.rst').read()
parser = docutils.parsers.rst.Parser()
doc = docutils.utils.new_document('doc')
doc.settings.tab_width = 4
doc.settings.pep_references = 1
doc.settings.rfc_references = 1
parser.parse(text, doc)

The problem was partially solved by forcing
doc.settings.rfc_references = 0

With doc.settings.rfc_references = 0, a file containing a bare RFC 1234 string is parsed normally. But the problem remains when using the text role :RFC:`1234`.

Then, I had the idea to add :
doc.settings.rfc_base_url = ''

Which solved the problem. This is when I understood that my problem came from the fact that my default configuration is incomplete. In fact :

import docutils.parsers.rst
doc = docutils.utils.new_document('doc')
print(dir (doc.settings))


['__cmp__', '__doc__', '__init__', '__module__', '__repr__', '__str__', '_config_files', '_destination', '_disable_config', '_source', '_update', '_update_careful', '_update_loose', 'auto_id_prefix', 'config', 'copy', 'datestamp', 'debug', 'dump_internals', 'dump_pseudo_xml', 'dump_settings', 'dump_transforms', 'ensure_value', 'error_encoding', 'error_encoding_error_handler', 'exit_status_level', 'expose_internals', 'footnote_backlinks', 'generator', 'halt_level', 'id_prefix', 'input_encoding', 'input_encoding_error_handler', 'language_code', 'output_encoding', 'output_encoding_error_handler', 'read_file', 'read_module', 'record_dependencies', 'report_level', 'sectnum_xform', 'source_link', 'source_url', 'strict_visitor', 'strip_classes', 'strip_comments', 'strip_elements_with_classes', 'title', 'toc_backlinks', 'traceback', 'update', 'warning_stream']

As you can see, rfc_references (among others) is missing.

Right now,  I don't know if the problem comes from my code (i.e. I have to tell new_document() to use the default conf explicitely) or if it comes from the distribution (macports).

I did not understand everything but I tried :

import docutils.parsers.rst
from docutils.frontend import OptionParser
settings = OptionParser().get_default_values()
doc = docutils.utils.new_document('doc', settings)
print(dir (doc.settings))

with no success (had the same outout).

Any clue or a code snippet ?

Thanks in advance,


On Mon, Feb 23, 2009 at 3:57 AM, David Goodger <> wrote:
On Sun, Feb 22, 2009 at 20:39, Rayene Ben Rayana
<> wrote:
> Well, this one was hard to find out.
> I had a long document that failed at parsing just because it contained the
> word "RFC" followed by a number.

Works for me ... by which I mean, "RFC 1234" in a document does nothing special.

> After some googling I found that there is a text role especially for RFCs
> I think that docutils is trying to parse my  "RFC 2462"  as if it was "
> :RFC:`2462` " . Am I right ?

Implicit RFC parsing is an optional feature, which you can turn on,
but is off by default.

Are you using standard Docutils tools, or your own code? I suspect the
latter, and that you're not using runtime settings properly. See

Please send a minimal doc & code, otherwise all we can do is speculate.

David Goodger <>