Thread: [Docutils-users] \usepackage?

I'm trying:

rst2latex stats.rst > stats.tex

from current svn.

I need to add \usepackage{cmlgc} (because current texlive is a bit broken).

I found that I can do:

rst2latex stats.rst  --stylesheet=cmlgc > stats.tex

where:
--cmlgc
\usepackage{cmlgc}

Is this the best approach (seems a bit silly)

On 28.02.08, Neal Becker wrote:
> I'm trying:

> rst2latex stats.rst > stats.tex

> from current svn.

> I need to add \usepackage{cmlgc} (because current texlive is a bit broken).

> I found that I can do:

> rst2latex stats.rst  --stylesheet=cmlgc > stats.tex

> where:
> --cmlgc
> \usepackage{cmlgc}

> Is this the best approach (seems a bit silly)

It is not that bad. You can of course also use::

  rst2latex --stylesheet=cmlgc stats.rst stats.tex

or even set the stylesheet in a ~/.docutils or ./docutils.conf file (see
http://docutils.sourceforge.net/docs/user/config.html)


Did you think about a special option like

  --usepackage=cmlgc
  
or

  --add-to-preamble="\usepackage{cmlgc}"
  
? This seems not to be present currently, and given the mass of options to
rst2latex2e seems not to be the best idea either (IMO).
  
Günter  

G. Milde wrote:

> On 28.02.08, Neal Becker wrote:
>> I'm trying:
> 
>> rst2latex stats.rst > stats.tex
> 
>> from current svn.
> 
>> I need to add \usepackage{cmlgc} (because current texlive is a bit
>> broken).
> 
>> I found that I can do:
> 
>> rst2latex stats.rst  --stylesheet=cmlgc > stats.tex
> 
>> where:
>> --cmlgc
>> \usepackage{cmlgc}
> 
>> Is this the best approach (seems a bit silly)
> 
> It is not that bad. You can of course also use::
> 
>   rst2latex --stylesheet=cmlgc stats.rst stats.tex
> 
> or even set the stylesheet in a ~/.docutils or ./docutils.conf file (see
> http://docutils.sourceforge.net/docs/user/config.html)
> 
> 
> Did you think about a special option like
> 
>   --usepackage=cmlgc
>   
> or
> 
>   --add-to-preamble="\usepackage{cmlgc}"
>   
> ? This seems not to be present currently, and given the mass of options to
> rst2latex2e seems not to be the best idea either (IMO).
>   

I like the idea of --usepackage or --add-to-preamble.  I don't agree that
there are too many options.

On Fri, 29 Feb 2008, Neal Becker wrote:

> G. Milde wrote:
>
>> On 28.02.08, Neal Becker wrote:
>>> I'm trying:
>>
>>> rst2latex stats.rst > stats.tex
>>
>>> from current svn.
>>
>>> I need to add \usepackage{cmlgc} (because current texlive is a bit
>>> broken).
>>
>>> I found that I can do:
>>
>>> rst2latex stats.rst  --stylesheet=cmlgc > stats.tex
>>
>>> where:
>>> --cmlgc
>>> \usepackage{cmlgc}
>>
>>> Is this the best approach (seems a bit silly)
>>
>> It is not that bad. You can of course also use::
>>
>>   rst2latex --stylesheet=cmlgc stats.rst stats.tex
>>
>> or even set the stylesheet in a ~/.docutils or ./docutils.conf file (see
>> http://docutils.sourceforge.net/docs/user/config.html)
>>
>>
>> Did you think about a special option like
>>
>>   --usepackage=cmlgc
>>
>> or
>>
>>   --add-to-preamble="\usepackage{cmlgc}"
>>
>> ? This seems not to be present currently, and given the mass of options to
>> rst2latex2e seems not to be the best idea either (IMO).
>>
>
> I like the idea of --usepackage or --add-to-preamble.  I don't agree that
> there are too many options.

and what should these do ?
obviously add a package !
where in the preamble ? before after inside of ... ?

the design as documented is

the writer produces a preamble and there is an option to insert a 
stylesheet after this to get the ability to overwrite settings.
for things that have to be configured in the generated preamble there
are options.

why not simply put ``\usepackage{cmlgc}`` into your standard stylesheet ?

if texlive is broken i might rather think about putting cmlgc into the
standard stylesheet.

cheers

-- 

On Fri, 29 Feb 2008, (CET) gr...@us... apparently wrote:
> the writer produces a preamble and there is an option to insert a 
> stylesheet after this to get the ability to overwrite settings. 
> for things that have to be configured in the generated preamble there 
> are options. 
> why not simply put ``\usepackage{cmlgc}`` into your standard stylesheet ? 

Fwiw, I agree that the existing functionality is great in 
this respect.

But do you like the ``--literal-block-env`` idea?

Cheers,
Alan Isaac

On Fri, 29 Feb 2008, Alan G Isaac wrote:

> On Fri, 29 Feb 2008, (CET) gr...@us... apparently wrote:
>> the writer produces a preamble and there is an option to insert a
>> stylesheet after this to get the ability to overwrite settings.
>> for things that have to be configured in the generated preamble there
>> are options.
>> why not simply put ``\usepackage{cmlgc}`` into your standard stylesheet ?
>
> Fwiw, I agree that the existing functionality is great in
> this respect.
>
> But do you like the ``--literal-block-env`` idea?

from what i can remember i could not see the solution.
i will try to look it up again (else nag me , please)

-- 

> On Fri, 29 Feb 2008, Alan G Isaac wrote:
>> But do you like the ``--literal-block-env`` idea? 

On Fri, 29 Feb 2008, (CET) gr...@us... wrote:
> from what i can remember i could not see the solution.  
> i will try to look it up again (else nag me , please)

Sure, I will.
Just to recall the issue and the idea.

Issue: literal blocks are often code,
and when they are, the best environment
(now at least) is lstlisting.

Currently there is an option ::

        --use-verbatim-when-possible

that switches from the mbox to the verbatim environment for 
literal blocks.  The request is to allow specifying the 
environment for literal blocks.  That is, replace the above 
option with ::

        --literal-block-env=verbatim

and allow

        --literal-block-env=lstlisting

instead.  As an extra treat, it would be nice to be able to 
say ::

        --literal-block-env=lstlisting[language=Python]

to get literal blocks inside of ::

        \begin{lstlisting}{language=Python]
        \end{lstlisting}

As always, thanks so much for thinking about such proposals.

Cheers,
Alan

On Fri, 29 Feb 2008, Alan G Isaac wrote:

>> On Fri, 29 Feb 2008, Alan G Isaac wrote:
>>> But do you like the ``--literal-block-env`` idea?
>
> On Fri, 29 Feb 2008, (CET) gr...@us... wrote:
>> from what i can remember i could not see the solution.
>> i will try to look it up again (else nag me , please)
>
> Sure, I will.
> Just to recall the issue and the idea.
>
> Issue: literal blocks are often code,
> and when they are, the best environment
> (now at least) is lstlisting.
>
> Currently there is an option ::
>
>        --use-verbatim-when-possible
>
> that switches from the mbox to the verbatim environment for
> literal blocks.  The request is to allow specifying the
> environment for literal blocks.  That is, replace the above
> option with ::
>
>        --literal-block-env=verbatim
>
> and allow
>
>        --literal-block-env=lstlisting
>
> instead.

currently verbatim would be used otherwise mbox (i did not look at the 
code, so this is from faint memory) now when this is replaced
where is the "when-possible"

keep ::

   --use-verbatim-when-possible

add ::

   --verbatim-env=

to specify the environment that is used when it is possible .

would this work ?

>  As an extra treat, it would be nice to be able to
> say ::
>
>        --literal-block-env=lstlisting[language=Python]
>
> to get literal blocks inside of ::
>
>        \begin{lstlisting}{language=Python]
>        \end{lstlisting}
>
> As always, thanks so much for thinking about such proposals.


-- 

On Sat, 1 Mar 2008, (CET) gr...@us... wrote:
> currently verbatim would be used otherwise mbox (i did not look at the 
> code, so this is from faint memory) now when this is replaced 
> where is the "when-possible"

> keep ::

>    --use-verbatim-when-possible

> add ::

>    --verbatim-env=

> to specify the environment that is used when it is possible . 

> would this work ? 


Yes, but it seems redundant to me.
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.

But whatever: I care about the functionality much more than
the interface.

Thanks!
Alan

On Sat, 1 Mar 2008, Alan G Isaac wrote:

> On Sat, 1 Mar 2008, (CET) gr...@us... wrote:
>> currently verbatim would be used otherwise mbox (i did not look at the
>> code, so this is from faint memory) now when this is replaced
>> where is the "when-possible"
>
>> keep ::
>
>>    --use-verbatim-when-possible
>
>> add ::
>
>>    --verbatim-env=
>
>> to specify the environment that is used when it is possible .
>
>> would this work ?
>
>
> Yes, but it seems redundant to me.
> 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.

yes this could possibly work.

the question is if we should could drop the when possible.
AFAIR the problem is that the writer can not distinguish between
literal and parsed-literal.

inside verbatim bold does not work inside lstlisting it does not make much 
sense , am i correct ?

> But whatever: I care about the functionality much more than
> the interface.

that distinguishes you and me :-)


-- 

On Sat, 1 Mar 2008, (CET) gr...@us... apparently wrote:
> the question is if we should could drop the when possible.  
> AFAIR the problem is that the writer can not distinguish 
> between literal and parsed-literal. 

I meant only that that point could be made in the 
documentation of the  ``--verbatim-env`` option,
since it is *always* a constraint (if i understand).

> inside verbatim bold does not work inside lstlisting it 
> does not make much sense , am i correct ? 

Yes.  Verbatim is verbatim.
AFAIK, the same restricting applied to listings.

Cheers,
Alan

On Sat, 1 Mar 2008, Alan G Isaac wrote:

> On Sat, 1 Mar 2008, (CET) gr...@us... apparently wrote:
>> the question is if we should could drop the when possible.
>> AFAIR the problem is that the writer can not distinguish
>> between literal and parsed-literal.
>
> I meant only that that point could be made in the
> documentation of the  ``--verbatim-env`` option,
> since it is *always* a constraint (if i understand).
>
>> inside verbatim bold does not work inside lstlisting it
>> does not make much sense , am i correct ?
>
> Yes.  Verbatim is verbatim.
> AFAIK, the same restricting applied to listings.

now ``--literal-block-env``

also with options

could you try it out


-- 

On  2.03.08, gr...@us... wrote:

> now ``--literal-block-env``

> also with options

> could you try it out

I had a look at # $Id: __init__.py 5525 2008-03-02 02:35:31Z grubert $
and found the definition of the --literal-block-env option.

However, I did not find the place where it is used.


For an example code using the verbatim environment, see

file:///home/milde/Code/Python/docutils-svn/sandbox/latex-variants/latex2e_listings/latex2e_listings.py

and for a summary of the "can of worms" see

file:///home/milde/Code/Python/docutils-svn/sandbox/latex-variants/docs/syntax-highlight-with-listings.html

Guenter

On  3.03.08, G. Milde wrote:
> On  2.03.08, gr...@us... wrote:

> > now ``--literal-block-env``

> > also with options

> > could you try it out

> I had a look at # $Id: __init__.py 5525 2008-03-02 02:35:31Z grubert $
> and found the definition of the --literal-block-env option.

> However, I did not find the place where it is used.

Found it now. It does not load the lstlistings package.



May I propose an alternative implementation?
(not yet tested but time is running out now. more tomorrow.)


Günter


--- /home/milde/Code/Python/docutils-svn/docutils/docutils/writers/latex2e/__init__.py	2008-03-03 15:36:43.000000000 +0100
+++ /home/milde/Code/Python/docutils-svn/docutils/docutils/writers/latex2e/latex2e_with_literate_env_option.py	2008-03-03 18:16:17.000000000 +0100
@@ -117,11 +117,13 @@
           ['--section-enumerator-separator'],
           {'default': '-', 'metavar': '<char>'}),
          ('When possibile, use the specified environment for literal-blocks. '
-          'Default is to always use the mbox environment.',
+          'Default is the quote environment and quoting of special chars.',
           ['--literal-block-env'],
-          {'default': '', }),
+          {'choices': ['verbatim', 'Verbatim', 'verbatimtab', 
+                       'listing', 'lstlisting'], 
+           'default': ''}),
          ('When possibile, use verbatim for literal-blocks. '
-          'Default is to always use the mbox environment.',
+          'Backwards compatibility alias for --literal-block-env=verbatim',
           ['--use-verbatim-when-possible'],
           {'default': 0, 'action': 'store_true',
            'validator': frontend.validate_boolean}),
@@ -601,6 +603,15 @@
 
     # default link color
     hyperlink_color = "blue"
+    
+    # packages providing verbatim environments
+    literal_block_package = {"verbatim": "",
+                             "Verbatim": "\RequirePackage{fancyvrb}",
+                             "verbatimtab": "\RequirePackage{moreverb}",
+                             "listing": "\RequirePackage{moreverb}",   
+                             "lstlisting": "\RequirePackage{listings}"}
+
+
 
     def __init__(self, document):
         nodes.NodeVisitor.__init__(self, document)
@@ -623,6 +634,9 @@
             self.colorlinks = 'false'
         else:
             self.colorlinks = 'true'
+        self.literal_block_env = settings.literal_block_env
+        if self.use_verbtim_when_possible:
+            self.settings.literal_block_env = 'verbatim'
 
         if self.settings.use_bibtex:
             self.bibtex = self.settings.use_bibtex.split(",",1)
@@ -687,6 +701,8 @@
               '\\usepackage{tabularx}\n',
               '\\usepackage{longtable}\n',
               self.active_table.used_packages(),
+              # package providing the literal block environment
+              self.literal_block_package[self.literal_block_env],
               # possible other packages.
               # * fancyhdr
               # * ltxtable is a combination of tabularx and longtable (pagebreaks).
@@ -726,10 +742,7 @@
         # TODO conditionally if no hyperref is used dont include
         self.head_prefix.append( self.linking % (
                     self.colorlinks, self.hyperlink_color, self.hyperlink_color))
-
         # 
-        if self.settings.literal_block_env != '':
-            self.settings.use_verbatim_when_possible = True
         if self.linking: # and maybe check for pdf
             self.pdfinfo = [ ]
             self.pdfauthor = None
@@ -967,17 +980,6 @@
             text = self.ensure_math(text)
         return text
 
-    def literal_block_env(self, begin_or_end):
-        env = 'verbatim'
-        opt = ''
-        if self.settings.literal_block_env != '':
-            (none, env, opt, none) = re.split("(\w+)(.*)",
-                                        self.settings.literal_block_env)
-        if begin_or_end == 'begin':
-            return '\\begin{%s}%s\n' % (env, opt)
-        return '\n\\end{%s}\n' % (env, )
-
-        
 
     def attval(self, text,
                whitespace=re.compile('[\n\r\t\v\f]')):
@@ -1731,50 +1733,47 @@
         """
         Render a literal-block.
 
-        Literal blocks are used for "::"-prefixed literal-indented
-        blocks of text, where the inline markup is not recognized,
+        Literal-blocks doctree elements are used for "::"-prefixed 
+        indented blocks of text, where the inline markup is not recognized,
         but are also the product of the parsed-literal directive,
         where the markup is respected.
         """
         # In both cases, we want to use a typewriter/monospaced typeface.
         # For "real" literal-blocks, we can use \verbatim, while for all
-        # the others we must use \mbox.
+        # the others we must use the `alltt` environment.
         #
         # We can distinguish between the two kinds by the number of
         # siblings that compose this node: if it is composed by a
         # single element, it's surely either a real one or a
         # parsed-literal that does not contain any markup.
         #
-        if not self.active_table.is_open():
-            # no quote inside tables, to avoid vertical space between
-            # table border and literal block.
-            # BUG: fails if normal text preceeds the literal block.
-            self.body.append('\\begin{quote}')
-            self.context.append('\\end{quote}\n')
-        else:
-            self.body.append('\n')
-            self.context.append('\n')
-        if (self.settings.use_verbatim_when_possible and (len(node) == 1)
-              # in case of a parsed-literal containing just a "**bold**" word:
-              and isinstance(node[0], nodes.Text)):
+        if ((len(node) == 1)
+            # in case of a parsed-literal containing just a "**bold**" word:
+            and isinstance(node[0], nodes.Text)):
             self.verbatim = 1
-            self.body.append(self.literal_block_env('begin'))
+            self.body.append('\\begin{%s}\n' % self.literal_block_env)
+            self.context.append('\\end{%s}\n' % self.literal_block_env)
         else:
             self.literal_block = 1
             self.insert_none_breaking_blanks = 1
+            if self.active_table.is_open():
+                # no quote inside tables, to avoid vertical space between
+                # table border and literal block.
+                # BUG: fails if normal text preceeds the literal block.
+                self.body.append('\n')
+                self.context.append('\n')
+            else:
+                self.body.append('\\begin{quote}\n')
+                self.context.append('\\end{quote}\n')
+            # TODO: use alltt environment
             self.body.append('{\\ttfamily \\raggedright \\noindent\n')
             # * obey..: is from julien and never worked for me (grubert).
             #   self.body.append('{\\obeylines\\obeyspaces\\ttfamily\n')
 
     def depart_literal_block(self, node):
-        if self.verbatim:
-            self.body.append(self.literal_block_env('end'))
-            self.verbatim = 0
-        else:
-            self.body.append('\n}')
-            self.insert_none_breaking_blanks = 0
-            self.literal_block = 0
-            # obey end: self.body.append('}\n')
+        self.verbatim = 0
+        self.insert_none_breaking_blanks = 0
+        self.literal_block = 0 
         self.body.append(self.context.pop())
 
     def visit_meta(self, node):

On  3.03.08, G. Milde wrote:
> On  3.03.08, G. Milde wrote:
> > On  2.03.08, gr...@us... wrote:

> > > now ``--literal-block-env``

> > > also with options

> > > could you try it out

It works, but requires a custom style-sheet that loads the required package.

> May I propose an alternative implementation?

I tested my implementation and it should work OK now.

* The option is named ``--literal-env`` -- a shorter but non-ambiguous name
  (as an environment is only used for literal blocks, not inline literals).

  --literal-env=LITERAL_ENV
                          When possible, use the specified environment for
                          literal-blocks. Default is quoting of white-space
                          special chars.
  
* It comes with a set of supported alternatives:

  rst2latex2e_literal_option.py: error: 
  option --literal-env: invalid choice: 'foo' 
  (choose from 'verbatim', 'Verbatim', 'verbatimtab', 'listing', 'lstlisting')

* It loads the required package (before the custom style-sheet, so
  configuring is possible)
  
* The obsolete option ``use-verbatim-when-possible`` is kept as an alias:

  --use-verbatim-when-possible
                          When possible, use verbatim for literal-blocks.
                          Backwards compatibility alias for "--literal-block-
                          env=verbatim"

* It does not support parsing of the --literal-env option string 
  (allows to edit out the `literal_block_env` method and keep it simple)
  Use a custom style-sheet to configure the literal environment.

* Remove the mentioning of \mbox from the documentation. \mbox is no longer
  used for literal blocks.
  
* Use `self.context.append` to simplify the `depart_literal_block` method
  and get a more consistent code layout.
  
TODO: * Use the alltt environment for non-verbatim typesetting of literal
        blocks.
      * Add test cases to the unit test suite.	
      * Provide template style files. (see e.g. `listings-options.sty`__)
      
__ http://docutils.sourceforge.net/sandbox/latex-variants/latex2e_listings/


I would be glad if this proposal could find its way into the latex2e writer.

Günter


--- docutils-svn/docutils/docutils/writers/latex2e/__init__.py	2008-03-03 21:53:24.000000000 +0100
+++ docutils-svn/sandbox/latex-variants/literal_option/latex2e_literal_option.py	2008-03-04 10:00:26.000000000 +0100
@@ -117,11 +117,13 @@
           ['--section-enumerator-separator'],
           {'default': '-', 'metavar': '<char>'}),
          ('When possibile, use the specified environment for literal-blocks. '
-          'Default is to always use the mbox environment.',
-          ['--literal-block-env'],
-          {'default': ''}),
+          'Default is quoting of whitespace special chars.',
+          ['--literal-env'],
+          {'choices': ['verbatim', 'Verbatim', 'verbatimtab', 
+                       'listing', 'lstlisting'], 
+           'default': ''}),
          ('When possibile, use verbatim for literal-blocks. '
-          'Default is to always use the mbox environment.',
+          'Backwards compatibility alias for "--literal-block-env=verbatim"',
           ['--use-verbatim-when-possible'],
           {'default': 0, 'action': 'store_true',
            'validator': frontend.validate_boolean}),
@@ -601,6 +603,14 @@
 
     # default link color
     hyperlink_color = "blue"
+    
+    # packages providing environments to typeset literal blocks
+    literal_package = {"": "",
+                       "verbatim": "",
+                       "Verbatim": "\\usepackage{fancyvrb}\n",
+                       "verbatimtab": "\\usepackage{moreverb}\n",
+                       "listing": "\\usepackage{moreverb}\n",   
+                       "lstlisting": "\\usepackage{listings}\n"}
 
     def __init__(self, document):
         nodes.NodeVisitor.__init__(self, document)
@@ -623,6 +633,8 @@
             self.colorlinks = 'false'
         else:
             self.colorlinks = 'true'
+        if self.settings.use_verbatim_when_possible:
+            self.settings.literal_env = 'verbatim'
 
         if self.settings.use_bibtex:
             self.bibtex = self.settings.use_bibtex.split(",",1)
@@ -687,6 +699,8 @@
               '\\usepackage{tabularx}\n',
               '\\usepackage{longtable}\n',
               self.active_table.used_packages(),
+              # package providing the literal block environment
+              self.literal_package[self.settings.literal_env],
               # possible other packages.
               # * fancyhdr
               # * ltxtable is a combination of tabularx and longtable (pagebreaks).
@@ -726,10 +740,7 @@
         # TODO conditionally if no hyperref is used dont include
         self.head_prefix.append( self.linking % (
                     self.colorlinks, self.hyperlink_color, self.hyperlink_color))
-
         # 
-        if self.settings.literal_block_env != '':
-            self.settings.use_verbatim_when_possible = True
         if self.linking: # and maybe check for pdf
             self.pdfinfo = [ ]
             self.pdfauthor = None
@@ -967,17 +978,6 @@
             text = self.ensure_math(text)
         return text
 
-    def literal_block_env(self, begin_or_end):
-        env = 'verbatim'
-        opt = ''
-        if self.settings.literal_block_env != '':
-            (none, env, opt, none) = re.split("(\w+)(.*)",
-                                        self.settings.literal_block_env)
-        if begin_or_end == 'begin':
-            return '\\begin{%s}%s\n' % (env, opt)
-        return '\n\\end{%s}\n' % (env, )
-
-        
 
     def attval(self, text,
                whitespace=re.compile('[\n\r\t\v\f]')):
@@ -1738,7 +1738,7 @@
         """
         # In both cases, we want to use a typewriter/monospaced typeface.
         # For "real" literal-blocks, we can use \verbatim, while for all
-        # the others we must use \mbox.
+        # the others we should use the `alltt` environment.
         #
         # We can distinguish between the two kinds by the number of
         # siblings that compose this node: if it is composed by a
@@ -1754,28 +1754,28 @@
         else:
             self.body.append('\n')
             self.context.append('\n')
-        if (self.settings.use_verbatim_when_possible and (len(node) == 1)
-              # in case of a parsed-literal containing just a "**bold**" word:
-              and isinstance(node[0], nodes.Text)):
+        if (self.settings.literal_env != '' 
+            and (len(node) == 1) and isinstance(node[0], nodes.Text)
+            # in case a parsed-literal containing just a "**bold**" word:
+           ):
             self.verbatim = 1
-            self.body.append(self.literal_block_env('begin'))
+            self.body.append('\n\\begin{%s}\n' % self.settings.literal_env)
+            self.context.append('\n\\end{%s}\n' % self.settings.literal_env)
         else:
             self.literal_block = 1
             self.insert_none_breaking_blanks = 1
+            # TODO: use alltt environment
             self.body.append('{\\ttfamily \\raggedright \\noindent\n')
+            self.context.append('\n}')
             # * obey..: is from julien and never worked for me (grubert).
             #   self.body.append('{\\obeylines\\obeyspaces\\ttfamily\n')
 
     def depart_literal_block(self, node):
-        if self.verbatim:
-            self.body.append(self.literal_block_env('end'))
-            self.verbatim = 0
-        else:
-            self.body.append('\n}')
-            self.insert_none_breaking_blanks = 0
-            self.literal_block = 0
-            # obey end: self.body.append('}\n')
-        self.body.append(self.context.pop())
+        self.verbatim = 0
+        self.insert_none_breaking_blanks = 0
+        self.literal_block = 0
+        self.body.append(self.context.pop())  # end verbatim env
+        self.body.append(self.context.pop())  # end quote env (dummy in table)
 
     def visit_meta(self, node):
         self.body.append('[visit_meta]\n')

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

On  1.03.08, gr...@us... wrote:
> On Fri, 29 Feb 2008, Alan G Isaac wrote:

> >  As an extra treat, it would be nice to be able to
> > say ::
> >
> >        --literal-block-env=lstlisting[language=Python]
> >
> > to get literal blocks inside of ::
> >
> >        \begin{lstlisting}{language=Python]
> >        \end{lstlisting}

I don't think this is necessary. You can set a default language for listings
in a stylesheet (and you will use a stylesheet anyway to format the listings
output, don't you?).

However, it would be nice if the class argument "Python" would translate to

> >        \begin{lstlisting}{language=Python]

and similar for all languages recognized by listings
so that you can write

.. class:: Python

::

   print "hello world"
   
.. class:: html

::

   <p> hello world </p>
   
or (after defining a source-code directive):

.. source-code:: Python

   print "hello world"
   

Guenter   
      
   
      

>> On Fri, 29 Feb 2008, Alan G Isaac wrote:
>>>        --literal-block-env=lstlisting[language=Python]

>>> to get literal blocks inside of ::

>>>        \begin{lstlisting}[language=Python]
>>>        \end{lstlisting}

On Mon, 3 Mar 2008, "G. Milde" apparently wrote:
> I don't think this is necessary. You can set a default language for listings 
> in a stylesheet (and you will use a stylesheet anyway to format the listings 
> output, don't you?). 

> However, it would be nice if the class argument "Python" would translate to 

>>>        \begin{lstlisting}[language=Python]

> and similar for all languages recognized by listings 
> so that you can write 

> .. class:: Python 

> ::

>    print "hello world"

..

> .. source-code:: Python 

>    print "hello world"


Regarding Guenter's comment about using a stylesheet to set 
a default language: this is true, since the stylesheet is 
put last in the preamble.  (But I still like what  Engelbert 
implemented.)

Regarding Guenter's proposed use of classes: whoa, ouch!
This seems to me to be asking a lot.  (But I have just a
user's perspective.)  I suspect we need a different 
approach: specifying a language as an option.  If we could 
have the ``literal`` directive, this would look like::

    .. literal::
       :language: Python
   
and similarly::

    .. include:: mycode.py
       :literal:
       :language: Python

I have the impression that the ``code`` and/or source-code 
directives are to be used in other ways?

Anyway, for now I have what I most need.  Thanks Engelbert!

Cheers,
Alan Isaac

On Mon, 3 Mar 2008, G. Milde wrote:

> On  1.03.08, gr...@us... wrote:
>> On Fri, 29 Feb 2008, Alan G Isaac wrote:
>
>>>  As an extra treat, it would be nice to be able to
>>> say ::
>>>
>>>        --literal-block-env=lstlisting[language=Python]
>>>
>>> to get literal blocks inside of ::
>>>
>>>        \begin{lstlisting}{language=Python]
>>>        \end{lstlisting}
>
> I don't think this is necessary. You can set a default language for listings
> in a stylesheet (and you will use a stylesheet anyway to format the listings
> output, don't you?).
>
> However, it would be nice if the class argument "Python" would translate to
>
>>>        \begin{lstlisting}{language=Python]
>
> and similar for all languages recognized by listings
> so that you can write

I can see the worms all over (who did open this can ?-)

currently the latex-writer does not know anything about
lstlisting this is just another text instead of verbatim

and i am not really fond of tying this in.

> .. class:: Python
>
> ::
>
>   print "hello world"
>
> .. class:: html
>
> ::
>
>   <p> hello world </p>
>
> or (after defining a source-code directive):
>
> .. source-code:: Python
>
>   print "hello world"

hard thinking ahead

is lstlisting *THE* absolute standard listing package so all and everyone 
uses it ...

cheers
-- 

On  3.03.08, gr...@us... wrote:
> On Mon, 3 Mar 2008, G. Milde wrote:

> > On  1.03.08, gr...@us... wrote:
> >> On Fri, 29 Feb 2008, Alan G Isaac wrote:
> >
> >>>        --literal-block-env=lstlisting[language=Python]
...

> > I don't think this is necessary. 
...
> > However, it would be nice if the class argument "Python" would translate to
> >
> >>>        \begin{lstlisting}{language=Python]
> >
> > and similar...

> currently the latex-writer does not know anything about
> lstlisting this is just another text instead of verbatim
> and i am not really fond of tying this in.

The good thing about class arguments it that the writer class can
choose to support it or not. So this can wait.


> hard thinking ahead

> is lstlisting *THE* absolute standard listing package 

It is AFAIK, the most advanced (and most complex) code listing package for
LaTeX and as such the "state of the art". 

> so all and everyone uses it ...

I do not know about *everyone*, but e.g. LyX (www.lyx.org) has built-in
support for it.