Re: [Docutils-users] literal-blocks and LaTeX verbatim

[David G. <go...@py...>]

On 4/4/07, G. Milde <mi...@us...> wrote:
> This explains the problems the LaTeX writer has with
> ``literal_block`` document tree elements. It has to take precautions
> that are only needed if the origin is ".. parsed-literal::" also in
> the (presumably more common) case of "::" blocks.

That is the wrong way to think about this.  Forget about the origins.
The writer should not care.  The writer only cares about the document
tree.

>> If there is a different LaTeX environment to use for literal blocks
>> with inline markup versus literal blocks without inline markup,
>> it's up to the writer to examine the contents of the literal block.
>
> This is a pity, as examining the contents for information that was
> in the syntax seems like a waste of resources and is not fail-proof
> to regain the original information.

It's a very simple operation: just examine the literal_block element
for child elements, and switch on the result.  It's not a big deal.

> I hope there will be a code-block directive in the standard docutils
> one day.

Me too.  However, the implementations I've seen so far are
insufficiently generic.  I admit I haven't gone through the latest
batch though.

> I also hope, that in the future the "role" of the ``::`` syntax will
> be configurable similar to the "role" of interpreted text.

Examining that proposal is also on my to-do list.

On 4/20/07, G. Milde <mi...@us...> wrote:
> Why is there a common doctree element for parsed and verbatim
> literal blocks but a specific doctree element for doctest blocks?

No particular reason, other than historical.  The doctest_block
element could be deprecated and removed.

> Feature request
> ===============
>
> Please let the docutils reader pass on the context information about
> origin of a literal_block element ("::" syntax or
> ".. parsed-literal::" directive) as a class attribute to the
> literal_block element.

I don't want to do this, because it's fragile and could be deceptive.
For example, an application could modify a <literal_block
class="verbatim"> by adding some inline markup, and not change the
class attribute.  A missing or inaccurate class attribute should not
break the document (it should gracefully degrade).  A check for child
elements is simple, accurate, and robust.

I'm not a LaTeX user, but it seems to me that
--use-verbatim-when-possible should be the default (perhaps even
remove the setting).  The writer already has all the information it
needs to decide.

There are always going to be disconnects between the various document
models (Docutils, LaTeX, HTML, ODF, etc.).  We must be wary and keep
the tail from wag the dog (IOW, don't let the output format dictate
the Docutils document model).  Otherwise, the document model becomes
painfully complex and fragile.

-- 
David Goodger <http://python.net/~goodger>