Re: [Docutils-users] \usepackage?

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

On  1.03.08, gr...@us... wrote:
> On Sat, 1 Mar 2008, Alan G Isaac wrote:
> > On Sat, 1 Mar 2008, (CET) gr...@us... wrote:

> > Why cannot
> >        --verbatim-env=mbox
> > be an option (possibly default), and if set to anything
> > else, it would mean to use that something else (verbatim,
> > or lstlisting) when possible.  The docs could explain this.

> the question is if we should could drop the when possible.

I hope we can agree to drop it from the option name (to reduce typing)
and use ``--verbatim-env`` instead of ``--verbatim-env-if-possible``.

> AFAIR the problem is that the writer can not distinguish between
> literal and parsed-literal.

AFAIR, the problem is

1. The docutils documenttree definition, allows a "rich" literate block.

2. The implementation must consider that "verbatim"-like environments
   clash with literal-blocks containing inline elements and 

   a) use a fall-back non-verbatim environment (e.g. `alltt`), or

   b) 'flatten' the literal-block doctree node

   in this case.

3. The latex writer does not know, where a literate block doctree node
   origines from (it could be e.g. a literal block, a parsed-literal
   block, a doctest block as well as a (possibly parsed) sourcecode
   directive).

Point 2. is the choice between "when-possible" or "force" variants of the
"--use-verbatim" or "--verbatim-env" options.

The question is: 

  Is there a user case for overriding the parsing of a literate block in
  order to use a verbatim environment?

My current answer would be

* Not with a parsed-literal directive.

* Maybe with a future sourcecode directive, as in this case it might be
  desirable to replace a rendering by the docutils reader by the use of
  the listings environment.

Conclusion:

For the time being, it is IMO save to *replace* the
"--use-verbatim-when-possible" option with '--literal-block-env'.

If the need arises, one could supplement this with either a
'--rich-literal-block-env' or a '--force-verbatim' option.

Günter