[ANN] Beamer back-end for org-export in contrib/

[ANN] Beamer back-end for org-export in contrib/

[Nicolas Goaziou]

Hello,

For the adventurous among you, I installed org-e-beamer.el in contrib.
Quoting file comments:

This library implements both a Beamer back-end, derived from the LaTeX
one and a minor mode easing structure edition of the document.

Depending on the desired output format, three commands are provided for
export: `org-e-beamer-export-as-latex' (temporary buffer),
`org-e-beamer-export-to-latex' ("tex" file) and
`org-e-beamer-export-to-pdf' ("pdf" file).

On top of buffer keywords supported by `e-latex' back-end (see
`org-e-latex-options-alist'), this back-end introduces the following
keywords: "BEAMER_THEME", "BEAMER_COLOR_THEME", "BEAMER_FONT_THEME",
"BEAMER_INNER_THEME" and "BEAMER_OUTER_THEME".  All accept options in
square brackets.

Moreover, headlines now fall into three categories: sectioning elements,
frames and blocks.

- Like `e-latex' back-end sectioning elements are still set through
  `org-e-latex-classes' variable.

- Headlines become frames when their level is equal to
  `org-e-beamer-frame-level' (or "H" value in the OPTIONS line).
  Though, if an headline in the current tree has a "BEAMER_env" (see
  below) property set to "frame", its level overrides the variable.

- All frames' children become block environments.  Special block types
  can be enforced by setting headline's "BEAMER_env" property to an
  appropriate value (see `org-e-beamer-environments-default' for
  supported value and `org-e-beamer-environments-extra' for adding
  more).

- As a special case, if the "BEAMER_env" property is set to either
  "appendix", "note" or "noteNH", the headline will become,
  respectively, an appendix, a note (within frame or between frame,
  depending on its level) and a note with its title ignored.

  Also, an headline with an "ignoreheading" value will have its contents
  only inserted in the output.  This special value is useful to have
  data between frames, or to properly close a "column" environment.

Along with "BEAMER_env", headlines also support "BEAMER_act" and
"BEAMER_opt" properties.  The former is translated as an overlay/action
specification (or a default overlay specification when enclosed within
square brackets) whereas the latter specifies options for the current
frame ("fragile" option is added automatically, though).

Every plain list has support for `:overlay' attribute (through
ATTR_BEAMER affiliated keyword).  Also, ordered (resp. description)
lists make use of `:template' (resp. `:long-text') attribute.

Eventually, an export snippet with a value enclosed within angular
brackets put at the beginning of an element or object whose type is
among `bold', `item', `link', `radio-target' and `target' will control
its overlay specifications.  As an example[fn:1],

  *@@e-beamer:<2->@@some emphasized text*

will be translated as

  \alert<2->{some emphasized text}


You can call `org-e-beamer-export-as-latex' on any document, but you may
want to add a "beamer" entry in `org-e-latex-classes' with:

  (add-to-list 'org-e-latex-classes
             '("beamer"
               "\\documentclass\[presentation\]\{beamer\}"
               ("\\section\{%s\}" . "\\section*\{%s\}")
               ("\\subsection\{%s\}" . "\\subsection*\{%s\}")
               ("\\subsubsection\{%s\}" . "\\subsubsection*\{%s\}")))

Then use #+LATEX_CLASS: beamer in your document.

Also, on the minor changes list, syntax for BEAMER_THEME and alike is,
for example:

  #+BEAMER_THEME: Rochester [height=20pt]
  
or,

  #+BEAMER_THEME: Madrid

I've dropped the BEAMER_extra property for headlines and
`org-beamer-inherited-properties' as I wasn't sure to completely
understand their goal.  I will insert them back if someone can provide
examples.

Feedback is welcome.


Regards,

[fn:1] Note that `org-export-snippet-translation-alist' can help
shortening the syntax to something like: @@b:<2->@@

-- 
Nicolas Goaziou

Re: [ANN] Beamer back-end for org-export in contrib/

[suvayu ali]

Hi Nicolas,

On Sat, Jun 30, 2012 at 4:59 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Hello,
>

[...]

> - Headlines become frames when their level is equal to
>  `org-e-beamer-frame-level' (or "H" value in the OPTIONS line).
>  Though, if an headline in the current tree has a "BEAMER_env" (see
>  below) property set to "frame", its level overrides the variable.

The sectioning works wonderfully!

[...]

> On top of buffer keywords supported by `e-latex' back-end (see
> `org-e-latex-options-alist'), this back-end introduces the following
> keywords: "BEAMER_THEME", "BEAMER_COLOR_THEME", "BEAMER_FONT_THEME",
> "BEAMER_INNER_THEME" and "BEAMER_OUTER_THEME".  All accept options in
> square brackets.
>

I tried a few of these out, works very well.

[...]

> Along with "BEAMER_env", headlines also support "BEAMER_act" and
> "BEAMER_opt" properties.  The former is translated as an overlay/action
> specification (or a default overlay specification when enclosed within
> square brackets) whereas the latter specifies options for the current
> frame ("fragile" option is added automatically, though).
>

I tried a few these too, works well. I recall you saying you would add
more overlay support gradually; I would like to say it would be nice if
there is support for replace-like overlays (e.g. \only or \onslide). It
would be great if I can wrap blocks in these. To illustrate what I mean,
I can produce the above effect with the following ugly hack:

  #+OPTIONS: H:2

  * Section
  ** Frame title
  Some more text

  #+LATEX: \only<1>{%
  *** Example block 					     :B_exampleblock:
      :PROPERTIES:
      :BEAMER_env: exampleblock
      :END:
  Some example text

  *** ignore 						    :B_ignoreheading:
      :PROPERTIES:
      :BEAMER_env: ignoreheading
      :END:
  #+LATEX: }

  #+LATEX: \only<2>{%
  *** Theorem block						  :B_theorem:
      :PROPERTIES:
      :BEAMER_env: theorem
      :END:
  Some bla bla ∀ \mathcal{R}

  *** ignore 						    :B_ignoreheading:
      :PROPERTIES:
      :BEAMER_env: ignoreheading
      :END:
  #+LATEX: }

> Every plain list has support for `:overlay' attribute (through
> ATTR_BEAMER affiliated keyword).  Also, ordered (resp. description)
> lists make use of `:template' (resp. `:long-text') attribute.
>

I wasn't clear what you meant here. Could you give an example? Did you
mean I can specify overlay specification for list items with the above
mechanism? I'm not clear on the syntax here.

I have another feature request (for the distant future) with regards to
lists; I would like to put tikz nodes in list items. I have tried that
in the past with very limited success. For an example, you can look
here:

<http://www.texample.net/tikz/examples/connecting-text-and-graphics/>

> Eventually, an export snippet with a value enclosed within angular
> brackets put at the beginning of an element or object whose type is
> among `bold', `item', `link', `radio-target' and `target' will control
> its overlay specifications.  As an example[fn:1],
>
>  *@@e-beamer:<2->@@some emphasized text*
>
> will be translated as
>
>  \alert<2->{some emphasized text}
>

Again, this works wonderfully.

[...]

> Also, on the minor changes list, syntax for BEAMER_THEME and alike is,
> for example:
>
>  #+BEAMER_THEME: Rochester [height=20pt]
>
I presume the beamer options go like the following?

  #+LATEX_CLASS_OPTIONS: [smaller,presentation]

I have a question; are subtree exports supported yet?

Great work!

Cheers,

--
Suvayu

Open source is the future. It sets us free.

Re: [ANN] Beamer back-end for org-export in contrib/

[Nicolas Goaziou]

Hello,

suvayu ali <fatkasuvayu+linux@gmail.com> writes:

> I recall you saying you would add more overlay support gradually;
> I would like to say it would be nice if there is support for
> replace-like overlays (e.g. \only or \onslide). It would be great if
> I can wrap blocks in these. To illustrate what I mean, I can produce
> the above effect with the following ugly hack:
>
>   #+OPTIONS: H:2
>
>   * Section 
>   ** Frame title Some more text
>
>   #+LATEX: \only<1>{%
>   *** Example block 					     :B_exampleblock:
>       :PROPERTIES:
>       :BEAMER_env: exampleblock
>       :END:
>   Some example text
>
>   *** ignore 						    :B_ignoreheading:
>       :PROPERTIES:
>       :BEAMER_env: ignoreheading
>       :END:
>   #+LATEX: }
>
>   #+LATEX: \only<2>{%
>   *** Theorem block						  :B_theorem:
>       :PROPERTIES:
>       :BEAMER_env: theorem
>       :END:
>   Some bla bla ∀ \mathcal{R}
>
>   *** ignore 						    :B_ignoreheading:
>       :PROPERTIES:
>       :BEAMER_env: ignoreheading
>       :END:
>   #+LATEX: }

This should be possible with `org-e-beamer-environments-extra', i.e.

  (add-to-list 'org-e-beamer-environments-extra
               '("onlyenv" "O" "\\begin{onlyenv}%a" "\\end{onlyenv}"))

Then you set headline's BEAMER_env property to onlyenv and modify
BEAMER_act accordingly.

>> Every plain list has support for `:overlay' attribute (through
>> ATTR_BEAMER affiliated keyword).  Also, ordered (resp. description)
>> lists make use of `:template' (resp. `:long-text') attribute.
>>
>
> I wasn't clear what you meant here. Could you give an example? Did you
> mean I can specify overlay specification for list items with the above
> mechanism? I'm not clear on the syntax here.

These attributes modify the whole list. To set overlays for individual
items, use export snippets. Examples follow:

  #+ATTR_BEAMER: :template "i)" :overlay "<+->"
  1. First item
  2. Second item 

will become

  \begin{enumerate}[<+->][i)]
  \item First item
  \item Second item
  \end{enumerate}

whereas

  1. @@e-beamer:<1>@@ First item
  2. @@e-beamer:<2>@@ Second item

will become

  \begin{enumerate}
  \item<1> First item
  \item<2> Second item
  \end{enumerate}

> I have another feature request (for the distant future) with regards to
> lists; I would like to put tikz nodes in list items. I have tried that
> in the past with very limited success. For an example, you can look
> here:
>
> <http://www.texample.net/tikz/examples/connecting-text-and-graphics/>

Again, export snippets should allow this. To obtain:

  \begin{itemize}
  \item Anode \tikz[na] \coordinate (s-anode);
  \item Cathode \tikz[na] \coordinate (s-cathode);
  \item Saline bridge \tikz[na] \coordinate (s-bridge);
  \end{itemize}

You can write:

  - Anode @@e-beamer:\tikz[na] \coordinate (s-anode);@@
  - Cathode @@e-beamer:\tikz[na] \coordinate (s-cathode);@@
  - Anode @@e-beamer:\tikz[na] \coordinate (s-bridge);@@

> I presume the beamer options go like the following?
>
>   #+LATEX_CLASS_OPTIONS: [smaller,presentation]

Yes.

> I have a question; are subtree exports supported yet?

I think so. Have you tested them?

Thank you for testing the back-end.


Regards,

-- 
Nicolas Goaziou

Re: [ANN] Beamer back-end for org-export in contrib/

[suvayu ali]

Hello Nicolas,

On Mon, Jul 2, 2012 at 2:22 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>
> This should be possible with `org-e-beamer-environments-extra', i.e.
>
>   (add-to-list 'org-e-beamer-environments-extra
>                '("onlyenv" "O" "\\begin{onlyenv}%a" "\\end{onlyenv}"))
>
> Then you set headline's BEAMER_env property to onlyenv and modify
> BEAMER_act accordingly.
>

Thanks! This works very well. :)

>>> Every plain list has support for `:overlay' attribute (through
>>> ATTR_BEAMER affiliated keyword).  Also, ordered (resp. description)
>>> lists make use of `:template' (resp. `:long-text') attribute.
>>>
>>
>> I wasn't clear what you meant here. Could you give an example? Did you
>> mean I can specify overlay specification for list items with the above
>> mechanism? I'm not clear on the syntax here.
>
> These attributes modify the whole list. To set overlays for individual
> items, use export snippets. Examples follow:
>
>   #+ATTR_BEAMER: :template "i)" :overlay "<+->"

Again this works beautifully!

>> I have another feature request (for the distant future) with regards to
>> lists; I would like to put tikz nodes in list items. I have tried that
>> in the past with very limited success. For an example, you can look
>> here:
>>
>> <http://www.texample.net/tikz/examples/connecting-text-and-graphics/>
>
> Again, export snippets should allow this. To obtain:
>
>   \begin{itemize}
>   \item Anode \tikz[na] \coordinate (s-anode);
>   \item Cathode \tikz[na] \coordinate (s-cathode);
>   \item Saline bridge \tikz[na] \coordinate (s-bridge);
>   \end{itemize}
>
> You can write:
>
>   - Anode @@e-beamer:\tikz[na] \coordinate (s-anode);@@
>   - Cathode @@e-beamer:\tikz[na] \coordinate (s-cathode);@@
>   - Anode @@e-beamer:\tikz[na] \coordinate (s-bridge);@@
>

Again, works just right!

>
>> I have a question; are subtree exports supported yet?
>
> I think so. Have you tested them?
>

This however didn't work for me. Since the beamer export is not in the
dispatcher yet, I tried the following:

  * Lifetime acceptance WG update
    :PROPERTIES:
    :LaTeX_CLASS: beamer
    :LaTeX_CLASS_OPTIONS: [presentation,smaller]
    :EXPORT_FILE_NAME: WG_update.pdf
    :EXPORT_AUTHOR: Suvayu Ali
    :EXPORT_DATE: 05 June, 2012
    :EXPORT_OPTIONS: H:1 num:nil toc:nil ^:{}
    :END:

  ** Frame title 1

  M-: (org-e-beamer-export-to-pdf t)

The exported latex source however has the following:

  \documentclass[11pt]{article}

instead of

  \documentclass[smaller,presentation]{beamer}

Everything else in the exported tex file seemed correct though. However
I will have to admit I did not do this in a minimal Emacs instance. If
you can't reproduce the issue, I'll try to work up an ECM in a minimal
Emacs instance.

I would also like to work on some user documentation for the beamer
backend (when I do find some free time :-p). I see that org-e-beamer.el
is very well commented so I will start there, but do you have any other
pointers that might help me clearly document the supported features?

I was thinking of starting as a Worg page and then moving to the texinfo
docs once org-export moves from contrib to core. Do you, or anyone else
for that matter, have any thoughts on this? What would an appropriate
location for such a page?

> Thank you for testing the back-end.
>

I am doing this out of selfish reasons. ;) After all, a better beamer
export makes my life easier. :)

Cheers,

-- 
Suvayu

Open source is the future. It sets us free.

Re: [ANN] Beamer back-end for org-export in contrib/

[Nicolas Goaziou]

Hello,

> This however didn't work for me. Since the beamer export is not in the
> dispatcher yet, I tried the following:
>
>   * Lifetime acceptance WG update
>     :PROPERTIES:
>     :LaTeX_CLASS: beamer
>     :LaTeX_CLASS_OPTIONS: [presentation,smaller]
>     :EXPORT_FILE_NAME: WG_update.pdf
>     :EXPORT_AUTHOR: Suvayu Ali
>     :EXPORT_DATE: 05 June, 2012
>     :EXPORT_OPTIONS: H:1 num:nil toc:nil ^:{}
>     :END:
>
>   ** Frame title 1
>
>   M-: (org-e-beamer-export-to-pdf t)
>
> The exported latex source however has the following:
>
>   \documentclass[11pt]{article}

This is because "LaTeX_CLASS" and "LaTeX_CLASS_OPTIONS" properties are
not recognized as export properties. You have to use them as a buffer
keyword (#+LATEX_CLASS: beamer).

> I would also like to work on some user documentation for the beamer
> backend (when I do find some free time :-p). I see that org-e-beamer.el
> is very well commented so I will start there, but do you have any other
> pointers that might help me clearly document the supported features?

I suppose you know about Eric S Fraga's tutorial at:

  http://orgmode.org/worg/org-tutorials/org-beamer/tutorial.html

Since the back-end shares a lot with its previous incarnation, you will
find, /mutatis mutandis/, much information about it.


Regards,

-- 
Nicolas Goaziou

Re: [ANN] Beamer back-end for org-export in contrib/

[suvayu ali]

Hi Nicolas,

On Wed, Jul 4, 2012 at 6:08 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>> The exported latex source however has the following:
>>
>>   \documentclass[11pt]{article}
>
> This is because "LaTeX_CLASS" and "LaTeX_CLASS_OPTIONS" properties are
> not recognized as export properties. You have to use them as a buffer
> keyword (#+LATEX_CLASS: beamer).
>

Okay, but this brings up a use case issue for me. I usually have a org
file dedicated to a project I'm working on. Then I have notes on
different sub topics and presentations in different subtrees. As needed,
I export the subtrees. This can be simple LaTeX or html export for notes
(to share or print), or beamer export in case I want to give a
presentation.

If I understand correctly, having a buffer keyword would mean I would
need to find and update it appropriately everytime I want to export
something. I can live with this, but it would be great if there was
support these export options as properties. Then all the subtree exports
can be decoupled easily.


>> I would also like to work on some user documentation for the beamer
>> backend (when I do find some free time :-p). I see that org-e-beamer.el
>> is very well commented so I will start there, but do you have any other
>> pointers that might help me clearly document the supported features?
>
> I suppose you know about Eric S Fraga's tutorial at:
>
>   http://orgmode.org/worg/org-tutorials/org-beamer/tutorial.html
>
> Since the back-end shares a lot with its previous incarnation, you will
> find, /mutatis mutandis/, much information about it.

Okay thanks, I was also thinking something similar and started based on
that. For all the common features I'll refer to Eric's tutorial and will
outline only the new, altered or deprecated features in my file.

Thanks again for this beautiful work. :)

Cheers,

-- 
Suvayu

Open source is the future. It sets us free.

Re: [ANN] Beamer back-end for org-export in contrib/

[Nicolas Goaziou]

Hello,

suvayu ali <fatkasuvayu+linux@gmail.com> writes:

> If I understand correctly, having a buffer keyword would mean I would
> need to find and update it appropriately everytime I want to export
> something. I can live with this, but it would be great if there was
> support these export options as properties. Then all the subtree exports
> can be decoupled easily.

I agree.

Now, /every/ property set through an export keyword can also be defined
with an headline property.  That property has the same name as the
keyword, with an "EXPORT_" prefix (i.e #+DATE: and :EXPORT_DATE:).

This is also true for keywords defined by back-ends (#+LATEX_CLASS:
and :EXPORT_LATEX_CLASS:).

In order to avoid confusion, I've renamed buffer keyword setting select
tags (resp. exclude tags) from EXPORT_SELECT_TAGS
(resp. EXPORT_EXCLUDE_TAGS) to SELECT_TAGS (resp. EXCLUDE_TAGS).


Regards,

-- 
Nicolas Goaziou

Re: [ANN] Beamer back-end for org-export in contrib/

[suvayu ali]

Hi Nicolas,

Apologies for taking so long to respond.

On Thu, Jul 5, 2012 at 1:56 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Now, /every/ property set through an export keyword can also be defined
> with an headline property.  That property has the same name as the
> keyword, with an "EXPORT_" prefix (i.e #+DATE: and :EXPORT_DATE:).
>
> This is also true for keywords defined by back-ends (#+LATEX_CLASS:
> and :EXPORT_LATEX_CLASS:).

I tested this and it works just as I was expecting it to. :)

Another question, I noticed that the new exported does not have the
exported file open in Emacs after it is done. I presume it is because
the new engine doesn't work on a buffer anymore. Would it be possible to
have Emacs open the exported file in the end?

While exporting often I feel the need to see the exported result when I
am working on a fairly complicated document. Sometimes it is to check if
org did the export correctly or to check if LaTeX rendered my
figure/equation as I am expecting it to. I realise at other times this
might be undesirable and maybe even intrusive.

I guess it seems like an adhoc addition but then the option could be
user customisable (turned off by default). In any case it is a "nice to
have" request, nothing to lose sleep over. :)

Thanks again for all the hard work.

Cheers,

-- 
Suvayu

Open source is the future. It sets us free.

Re: [ANN] Beamer back-end for org-export in contrib/

[Nicolas Goaziou]

Hello,

suvayu ali <fatkasuvayu+linux@gmail.com> writes:

> Another question, I noticed that the new exported does not have the
> exported file open in Emacs after it is done.

It does here. Exporting with "l" or "d" leaves the corresponding tex
file open in a buffer.

Am I misunderstanding your request?


Regards,

-- 
Nicolas Goaziou

Re: [ANN] Beamer back-end for org-export in contrib/

[suvayu ali]

On Sat, Jul 7, 2012 at 2:32 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> It does here. Exporting with "l" or "d" leaves the corresponding tex
> file open in a buffer.
>
> Am I misunderstanding your request?

No you understood it correctly. This does not happen for me. Do you
have any idea how I can track this issue down?

PS: I tried with a minimal emacs instance.

-- 
Suvayu

Open source is the future. It sets us free.

Re: [ANN] Beamer back-end for org-export in contrib/

[Nicolas Goaziou]

suvayu ali <fatkasuvayu+linux@gmail.com> writes:

> No you understood it correctly. This does not happen for me. Do you
> have any idea how I can track this issue down?

You may try to debug `org-export-to-file'. I have no idea about what
could remove the buffer containing the tex file.