src blocks in texinfo export

src blocks in texinfo export

[Dario Hamidi]

[-- Attachment #1: Type: text/plain, Size: 524 bytes --]

Hello, 

I discovered a problem when exporting source blocks containing braces to
texinfo using `ox-texinfo'.  The texinfo exporter wraps source blocks
into a `example' environment, which takes care of source block
indentation but doesn't allow any braces to occur in the contained text,
since braces have a special meaning in TeX.

After reading the `texinfo' manual, it became clear that literal examples
should be exported also in a `verbatim' environment.  A patch making
this change to the exporter is attached.

Dario

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: ox-texinfo.el.patch --]
[-- Type: text/x-patch, Size: 474 bytes --]

diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index 8bc3520..211bf01 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -1409,7 +1409,7 @@ contextual information."
 	      (org-export-format-code-default src-block info)))
      ;; Case 2.  Other blocks
      (t
-      (format "@example\n%s@end example"
+      (format "@example\n@verbatim\n%s@end verbatim\n@end example"
 	      (org-export-format-code-default src-block info))))))
 
 ;;; Statistics Cookie

Re: src blocks in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1: Type: text/plain, Size: 1310 bytes --]

Hello Dario,

On 12 February 2013 10:36, Dario Hamidi <dario.hamidi@gmail.com> wrote:

> Hello,
>
> I discovered a problem when exporting source blocks containing braces to
> texinfo using `ox-texinfo'.  The texinfo exporter wraps source blocks
> into a `example' environment, which takes care of source block
> indentation but doesn't allow any braces to occur in the contained text,
> since braces have a special meaning in TeX.
>
> After reading the `texinfo' manual, it became clear that literal examples
> should be exported also in a `verbatim' environment.  A patch making
> this change to the exporter is attached.
>


Using your patch as is would wrap the source blocks in both example and
verbatim blocks.  If going with verbatim it would be better to remove all
references to @example/@end example.

I had chosen to go with @example rather than @verbatim because it does state
that lisp blocks should be wrapped in @lisp which is synonymous to @example.

It should be possible to escape any braces or @ before inserting them into
the
example block to ensure there is no expansion.

The only differences in using @verbatim over escaping any characters in
@example are the following:
  - Tabs are treated as tabs and not as single spaces
  - The code block is not indented.

Regards,
Jon


>  Dario
>

[-- Attachment #2: Type: text/html, Size: 2035 bytes --]

Re: src blocks in texinfo export

[Dario Hamidi]

Hello Jonathan,

> Using your patch as is would wrap the source blocks in both example and
> verbatim blocks.  If going with verbatim it would be better to remove all
> references to @example/@end example.

I don't understand where the problem lies with having a `@verbatim'
within a `@example'. Could you maybe explain to me why this is
problematic?

Using both environments seems to achieve the goal of having an idented
source block in the resulting info file without having to further
process the source block before export.

Consider exporting 

    #+BEGIN_SRC sh
    function fails
    {
        echo "this causes an error with makeinfo"
    }
    #+END_SRC

with only the verbatim environment:

    File: test.info,  Node: Top,  Up: (dir)
    
    Manual
    ******
    
    function fails
    {
        echo "this causes an error with makeinfo"
    }

and with verbatim in example:

    File: test.info,  Node: Top,  Up: (dir)
    
    Manual
    ******
    
         function fails
         {
             echo "this causes an error with makeinfo"
         }

> It should be possible to escape any braces or @ before inserting them into
> the
> example block to ensure there is no expansion.

While it certainly is possible, it would also mean to properly escape
*all* characters with a special meaning to TeX.  I suppose that making
text containing such characters visible in a document without having to
escape them is what the verbatim environment is for.

> The only differences in using @verbatim over escaping any characters in
> @example are the following:
>   - Tabs are treated as tabs and not as single spaces
>   - The code block is not indented.

Preserving whitespace seems like a good idea when displaying python
source code or makefiles.

Dario

Re: src blocks in texinfo export

[Jonathan Leech-Pepin]

[-- Attachment #1: Type: text/plain, Size: 2348 bytes --]

Hello Dario,

On 12 February 2013 17:09, Dario Hamidi <dario.hamidi@gmail.com> wrote:

>
> Hello Jonathan,
>
> > Using your patch as is would wrap the source blocks in both example and
> > verbatim blocks.  If going with verbatim it would be better to remove all
> > references to @example/@end example.
>
> I don't understand where the problem lies with having a `@verbatim'
> within a `@example'. Could you maybe explain to me why this is
> problematic?
>
> Using both environments seems to achieve the goal of having an idented
> source block in the resulting info file without having to further
> process the source block before export.
>
> Consider exporting
>
>     #+BEGIN_SRC sh
>     function fails
>     {
>         echo "this causes an error with makeinfo"
>     }
>     #+END_SRC
>
> with only the verbatim environment:
>
>     File: test.info,  Node: Top,  Up: (dir)
>
>     Manual
>     ******
>
>     function fails
>     {
>         echo "this causes an error with makeinfo"
>     }
>
> and with verbatim in example:
>
>     File: test.info,  Node: Top,  Up: (dir)
>
>     Manual
>     ******
>
>          function fails
>          {
>              echo "this causes an error with makeinfo"
>          }
>
> > It should be possible to escape any braces or @ before inserting them
> into
> > the
> > example block to ensure there is no expansion.
>
> While it certainly is possible, it would also mean to properly escape
> *all* characters with a special meaning to TeX.  I suppose that making
> text containing such characters visible in a document without having to
> escape them is what the verbatim environment is for.
>
> > The only differences in using @verbatim over escaping any characters in
> > @example are the following:
> >   - Tabs are treated as tabs and not as single spaces
> >   - The code block is not indented.
>
> Preserving whitespace seems like a good idea when displaying python
> source code or makefiles.
>
> Dario
>

I've implemented a fix for this that should resolve the issue.  `@ { }` are
now
properly escaped before export within source blocks.  I didn't wrap the one
block in the other since the issue also existed within lisp blocks (where
inserting a verbatim block within a lisp block would have likely caused
issues
had someone wanted to extract any @lisp code from the info file.

Regards,

Jon

[-- Attachment #2: Type: text/html, Size: 3206 bytes --]