Docutils: Documentation Utilities

grubert@... wrote:
> you are talking from the internal represantation i am talking of the
> output structure.

We started out talking about internationalization, doing lookups in
language modules.  That smells like internal representation to me.

The point is, when you have a document which begins with this::

    :Author: John Doe
    :Web Site: http://www.example.com/

The internal document (fragment) tree looks like this::

    <docinfo>
        <author>
            John Doe
        <field>
            <field_name>
                Web Site
            <field_body>
                <paragraph>
                    <reference refuri="http://www.example.com/">
                        http://www.example.com/

The structures for the "Author" field (specific) and the "Web Site"
field (generic) are completely different, and therefore require
different processing.  You can't ignore that.

> "Web site" and "Author" both end up in the documents docinfo.
> this means: if i donot want to put formatting information
> into two places one needs a function for it.

Fine, separate the formatting into a separate method.  Just don't do
language lookups for fields that don't need them.  Do the language
lookup, and send the *result* to the formatting method.

>>> the pre (literal) environment in latex is verbatim.  how does one
>>> get the input with parsing: astext() removes the reST markup ?
>>
>> I don't understand the question.  Examples, please.
> 
> ::
>    This is *some* thing
> 
> this.astext() gives the text without stars.

Untrue.  Perhaps the lack of a blank line after "::" is causing
trouble?  Literal blocks do not touch the characters inside::

    $ quicktest.py << EOF
    > ::
    > 
    >     This is *some* thing
    > EOF
    <document source="<stdin>">
        <literal_block xml:space="preserve">
            This is *some* thing

The astext() method doesn't touch the characters either.  However,
astext() should only be used sparingly and carefully.  If there is any
structure in the node, ``node.astext()`` will ignore it.

Why are you using astext() anyway?  Just let the tree traversal do the
work.  From latex2e.py's LaTeXTranslator class::

    def visit_literal_block(self, node):
        self.use_verbatim_for_literal = 1
        if (self.use_verbatim_for_literal):
            self.body.append('\\begin{verbatim}\n')
            self.body.append(node.astext())
            self.body.append('\n\\end{verbatim}\n')
            raise nodes.SkipNode
        else:
            self.body.append('{\\obeylines\\obeyspaces\\ttfamily\n')

I don't see why you need to short-circuit the traversal.  The "if"
statement is not really conditional: it will always evaluate to true.
That should be cleaned up.  Shouldn't
``self.body.append(node.astext())`` also call ``self.encode()``?  That
may be the source of the problem.

This is exactly the kind of bug that arises when the tree traversal
isn't allowed to complete properly.  Look at the html4css1.py writer;
``raise nodes.SkipNode`` is only used 5 times, and each time there is
a good reason.  I've added some comments where it may have been
unclear.  Could you add comments wherever you ``raise nodes.SkipNode``
in latex2e.py, justifying the exceptions?

-- 
David Goodger  <goodger@...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/