Feature request: simplify usage of special blocks (for beamer)

Feature request: simplify usage of special blocks (for beamer)

[Carlos Pita]

Hi all!

The standard mapping from org structures to beamer structures
introduces boilerplate:

1. At the bare minimum a properties drawer.
2. Then there is the tag.
3. But above all the need to add an ignoreheading subsection (with its
drawer and everything) to introduce a little text between, say, two
definition blocks.

Now, there are special blocks [1] also, and it's a pity they are not
suggested for beamer blocks nor in the org manual nor in the org
beamer tutorial. IMO they are a better fit for simple beamer blocks.
They don't nest, so org headings still have a purpose here for complex
layouts, but they close naturally without the need of
ignoreheading-like tricks, and this covers most cases of practical
importance.

Now, that it's great but the way they take their options is more
clunky than it could be. You need to add a #+ATTR_LATEX: options:...
line above, burying the block title into syntactical noise. It would
be nice it they took their options directly instead, as src blocks do.
For example:

#+BEGIN_definition :options [I'm the definiendum]
I'm the definition
#+END_definition

So my request would be:

1. Allow for special blocks to take an :options argument.

2. Mention the possibility of using special blocks to represent beamer
blocks, be it in the manual or in the tutorial.

Best regards
--
Carlos

[1] https://orgmode.org/manual/Special-blocks-in-LaTeX-export.html

Re: Feature request: simplify usage of special blocks (for beamer)

[Eric S Fraga]

On Saturday,  1 Dec 2018 at 13:24, Carlos Pita wrote:
> Now, there are special blocks [1] also, and it's a pity they are not

[...]

> So my request would be:
>
> 1. Allow for special blocks to take an :options argument.

Although I agree that this would be nice, I imagine the difficulty would be that it would be difficult to cater for multiple backends.

> 2. Mention the possibility of using special blocks to represent beamer
> blocks, be it in the manual or in the tutorial.

Given that beamer inherits everything that the LaTeX exporter supports, is the special blocks section in the LaTeX exporter documentation not already enough?

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.1.14-1035-gfeb442

Re: Feature request: simplify usage of special blocks (for beamer)

[Carlos Pita]

> > 1. Allow for special blocks to take an :options argument.
>
> Although I agree that this would be nice, I imagine the difficulty would be that it would be difficult to cater for multiple backends.

It's not really difficult, more on the trivial side. For example, as
an end user I already can install a filter like:

(defun my-special-block-parse-filter (tree backend symbol)
  (when (org-export-derived-backend-p backend 'latex)
    (org-element-map tree 'special-block
      (lambda (element)
        (save-excursion
          (goto-char (org-element-property :begin element))
          (when (looking-at "[ \t]*#\\+BEGIN_\\S-+[ \t]+\\(\\S-+\\)")
            (let ((options (format ":options [%s]"
(match-string-no-properties 1))))
              (org-element-put-property element :attr_latex (list
options)))))))))

And then write:

#+BEGIN_definition Special Block
A block mostly left uninterpreted by core org for the sake of backends
#+END_definition

This is as devoid of boilerplate as possible.

Notice the filter only applies to latex derived backends and won't
take effect if there is an #+ATTR_LATEX clause before the block (this
because it's considered part of the element the regexp won't match
it).

Obviously this can be implemented in a cleaner way by changing
org-latex-special-block in ox-latex.el. Again, the change would be
trivial.

> > 2. Mention the possibility of using special blocks to represent beamer
> > blocks, be it in the manual or in the tutorial.
>
> Given that beamer inherits everything that the LaTeX exporter supports, is the special blocks section in the LaTeX exporter documentation not already enough?

Not much users seem to be aware of the ablity of using special blocks
for beamer. No example, answer, tutorial out there even mentioned the
possibility. Given its convenience, I would say the beamer export
section should explicitly suggest the alternative.

Best regards
--
Carlos

Re: Feature request: simplify usage of special blocks (for beamer)

[Carlos Pita]

>           (when (looking-at "[ \t]*#\\+BEGIN_\\S-+[ \t]+\\(\\S-+\\)")

Sorry, it obviously should have been \\(.+\\) at the end.

One thing the core parser could do is to put the remaining of the
opening line of a special block into an :args or similar property of
the special block element, leaving it otherwise unparsed. This is in
the same spirit than what it already do for the affiliated attrs_X
element. It's not a lot of help but it would at least spare backends
from having to parse the remaining of the opening line as I did. They
would still have to parse :args exactly as they now parse :attrs_X,
but there are helper functions for that task. The idea is that stuff
that is very specific to a backend X would be in :attrs_X, but stuff
that is related to what makes the block semantically special could be
in :args. Nevertheless special blocks will probably be backend
specific in most cases.

Re: Feature request: simplify usage of special blocks (for beamer)

[Eric S Fraga]

On Saturday,  1 Dec 2018 at 15:41, Carlos Pita wrote:
>> > 1. Allow for special blocks to take an :options argument.
>>
>> Although I agree that this would be nice, I imagine the difficulty
>> would be that it would be difficult to cater for multiple backends.
>
> It's not really difficult, more on the trivial side. For example, as
> an end user I already can install a filter like:

My point is that LaTeX is not the only export target for org, not that
implementing it would be difficult for a specific target.  That is why
you are expected to use target specific attributes.

>> Given that beamer inherits everything that the LaTeX exporter
>> supports, is the special blocks section in the LaTeX exporter
>> documentation not already enough?
>
> Not much users seem to be aware of the ablity of using special blocks
> for beamer. No example, answer, tutorial out there even mentioned the
> possibility. Given its convenience, I would say the beamer export
> section should explicitly suggest the alternative.

I've been using special blocks in beamer from the start but there's no
harm in having an explicit mention in the beamer section of the manula,
of course.  So maybe please suggest the change in the manual (i.e. post
a patch)?  The manual written in org these days so easy to update.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.1.14-1035-gfeb442

Re: Feature request: simplify usage of special blocks (for beamer)

[Eric S Fraga]

On Saturday,  1 Dec 2018 at 16:23, Carlos Pita wrote:
> The idea is that stuff that is very specific to a backend X would be
> in :attrs_X, but stuff that is related to what makes the block
> semantically special could be in :args. 

And this is where the challenge lies!  The whole point of special blocks is that org knows nothing of their semantics.  They are a "black box" and it would be difficult to identify export specific elements and general elements on this basis.

> Nevertheless special blocks will probably be backend specific in most
> cases.

Many but not all.  And hence the difficulty.

Sorry for being negative.  I sympathize fully with your aims as I use special blocks all the time and don't particularly like the attr lines either.  But I see no general solution to this.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.1.14-1035-gfeb442

Re: Feature request: simplify usage of special blocks (for beamer)

[Carlos Pita]

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

Hi Eric,

And this is where the challenge lies!  The whole point of special blocks is
> that org knows nothing of their semantics.  They are a "black box" and it
> would be difficult to identify export specific elements and general
> elements on this basis.
>

I partially agree with this just because TIL that the html backend is
already exporting special blocks as divs with an appropriate css class.

But facilitating powerful backend specific mechanisms to the user that
prefer to exploit the advantages of a particular backend, by somehow
hindering his/her ability to later export to a different format, that's
important too. And, besides backend-specific stuff, don't forget there are
user-specific extensions, as mine above, that deliberately sacrifice
generality. All this is in the best open-close spirit I would say and org
already fully embraces it by its superb backend and filter interfaces.

The same than the core parser is exposing a block "special type" it could
also expose the block "special argument" as an uninterpreted string for the
backend to interpret it. To emphasize this point: I'm not proposing that
the core parser understands the arguments to the special block but that it
passes opaque content for the backend and/or end user to process. I would
have gladly avoided that save-excursion-goto-char-re-search-forwars cruft
to focus in parsing a string cleanly passed down by the parser.

Notice that, up to this point, I've not proposed any modification to the
latex backend. But, to be honest, I see no harm in interpreting this
special argument as :options if it's well understood that, by doing so,
ability to export to another backends may be compromised. I understand this
proposal could be more controversial, tough.

So I think it's better to distinctly state the different but related
suggestions I made:

1. Mention special blocks in the beamer export documentation as an
alternative to subsectioning.

2. Make the core parser pass an :args or similar property as part of the
element for the sake of backends providing specific extensions or end users
filtering the tree to tailor the syntax to their needs, thus empowering
special blocks as an extension mechanism.

3. Make the latex backend interpret this :args property as options for the
underlying latex environment.

Best regards
--
Carlos

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

Re: Feature request: simplify usage of special blocks (for beamer)

[Carlos Pita]

I would also like to elaborate on another aspect of this.

#+ATTR_xxx serves two purposes:

a. As a syntactical means of attaching extra information to
syntactically constrained elements (as tables or images). For this
purpose the _xxx part is irrelevant, only the affiliation to an
element matters.

b. As a way of differentiating between different sets of attributes
and thus dispatching the appropriate set to the appropriate backend.

In the case of special blocks, which are syntactically capable of
directly taking arguments, just as SRC blocks do, (a) doesn't apply.
This brings about the possibility of a syntactic shortcut at the cost
of (b). So, a general rule could be:

i. A backend xxx interprets the argument to a special block as if it
were the argument to an affiliated ATTR_xxx.

ii. In case of conflict ATTR_xxx wins.

iii. It's well understood (and documented!) that, by doing so, ability
to export to other backends (point 2 above) may be compromised.

Thus the user would take advantage of this shortcut only when he/she
is already stuck with some particular output format. Also, for users
implementing kinda DSLs, having this special blocks with special
arguments is a handy feature.

Let's add this to my list of suggestions as proposal (4), again
related to but mostly independent of the other ones, although it's
expected that something like (2) would have to be implemented in order
to get (3) or (4).

Best regards
--
Carlos

Re: Feature request: simplify usage of special blocks (for beamer)

[Nicolas Goaziou]

Hello,

Carlos Pita <carlosjosepita@gmail.com> writes:

> One thing the core parser could do is to put the remaining of the
> opening line of a special block into an :args or similar property of
> the special block element, leaving it otherwise unparsed.

I thought about it a long time ago. However, I could not, and still
cannot, find an interesting use case for it in Org. This is a good
indicator that we do not need the feature.

> This is in the same spirit than what it already do for the affiliated
> attrs_X element.

Not really. 

For source blocks, arguments on the same line as the opening string
"BEGIN_SRC" are treated as a "HEADER" affiliated argument, which is
specific to Babel. OTOH, although almost every element type can have
affiliated keywords, only a small part could accept such "special
parameters". In a nutshell, this isn't symmetrical.

> It's not a lot of help but it would at least spare
> backends from having to parse the remaining of the opening line as
> I did.

So far, none of our back-ends need this, even though they are relatively
complex.

So, we could use the room there if one day, we need it for something,
but until then, I don't think we should extend syntax just because we
can do it.


Regards,

-- 
Nicolas Goaziou

Re: Feature request: simplify usage of special blocks (for beamer)

[Carlos Pita]

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

Hi Nicolas,

fair enough if you feel it's not worth the hassle.

I'm pasting here a simple filter implementing the rule I described
above (use the special arg if present and if it doesn't conflict with
any ATTR directive for the current backend) for anyone interested, if
any at all:

(defun my-org-special-block-filter (tree backend _symbol)
  (pcase-let ((`(,prop ,fmt)
               (cond ((org-export-derived-backend-p backend 'latex)
                      '(:attr_latex ":options [%s]")))))
    (when prop
      (org-element-map tree 'special-block
        (lambda (element)
          (unless (org-element-property prop element)
            (save-excursion
              (goto-char (org-element-property :begin element))
              (when (re-search-forward "#\\+BEGIN_\\S-+[ \t]+\\(.+\\)" nil t)
                (let ((attr (format fmt (match-string-no-properties 1))))
                  (org-element-put-property element prop (list attr))))))
          nil)))))

It can easily be extended to other backends by just adding a new
clause to the cond at the beginning.

This plus a little extra font locking allows me to edit my
presentations like the attached screenshot shows. I think it's quite
an improvement over subsectioning and ignoreheading cruft but it must
be said that, although it looks nicer, it's only a marginal
improvement over special blocks plus affiliated ATTRs.

Best regards
--
Carlos

[-- Attachment #2: Screenshot_2018-12-02_18:00:22.png --]
[-- Type: image/png, Size: 51957 bytes --]