Re: Are 'placement' and 'float' "obsolete terms" in inline images export

Re: Are 'placement' and 'float' "obsolete terms" in inline images export

[Juan Manuel Macías]

Ihor, sorry for the late reply.

Ihor Radchenko writes:

> So, the difference between :environment and :float is that :float also
> encapsulates \caption in addition to the actual environment (like
> tabularx or includegraphics) used for transcoded exported element.

> I can see how :float+:placement can be imprecise and that the existing
> :environment indeed serves a different purpose. (It might be worth
> clarifying this distinction in the manual - it seems arbitrary from
> the first glance).

> But what would be the better name then?

I think the problem is limited to images, where there is no "double"
environment as in the case of tables (float environment that encloses an
environment to generate the table, and :placement points to the correct
environment). In the case of images, I am afraid that the new features
have advanced the meaning of the old ones. Previously, :float only
supported t/nil ("figure" by default, in case of t) along with a few
explicit "float" environments, such as sidewaysfigure or wrapfigure.
Since :float now can accept any string as an environment name, Pandora's
box has been opened and the meaning of the old :float has been left
behind: for example, we can put :float minipage, and minipage is not a
float environment. Something similar has happened to :placement.

My suggestion is to add a :environment attribute next to another
:environment-options attr (or something like that, to introduce any
arbitrary LaTeX code). A LaTeX image can be enclosed in many environment
types, float or non-float. However, :float can still be useful for
certain combinations. For example, a minipage environment cannot include
a caption (it produces an error of the type "LaTeX Error: \caption
outside float"). Then you would have to put something like


#+ATTR_LaTeX: :float nil :environment minipage :environment-options {\linewidth}
#+CAPTION: caption
[[file:foo.png]]

==>

\begin{minipage}{\linewidth}
\includegraphics[width=.9\linewidth]{foo.png}
\captionof{figure}{caption}
\end{minipage}

Anyway, I find pros and cons of all this:

- pros: a intended feature is added, although with :float and :placement
  the same thing can be achieved (sometimes), but here the effect is not
  intended (in origin).

- cons: redundancy, more complexity in the code (and probably more confusion for the user?).

-- 
Juan Manuel Macías 

Re: Are 'placement' and 'float' "obsolete terms" in inline images export

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

>> So, the difference between :environment and :float is that :float also
>> encapsulates \caption in addition to the actual environment (like
>> tabularx or includegraphics) used for transcoded exported element.
>
>> I can see how :float+:placement can be imprecise and that the existing
>> :environment indeed serves a different purpose. (It might be worth
>> clarifying this distinction in the manual - it seems arbitrary from
>> the first glance).
>
>> But what would be the better name then?
>
> I think the problem is limited to images, where there is no "double"
> environment as in the case of tables (float environment that encloses an
> environment to generate the table, and :placement points to the correct
> environment).

IMHO, an equivalent of :environment for images is
\includegraphics or \includesvg.

> ... In the case of images, I am afraid that the new features
> have advanced the meaning of the old ones. Previously, :float only
> supported t/nil ("figure" by default, in case of t) along with a few
> explicit "float" environments, such as sidewaysfigure or wrapfigure.
> Since :float now can accept any string as an environment name, Pandora's
> box has been opened and the meaning of the old :float has been left
> behind: for example, we can put :float minipage, and minipage is not a
> float environment. Something similar has happened to :placement.
>
> My suggestion is to add a :environment attribute next to another
> :environment-options attr (or something like that, to introduce any
> arbitrary LaTeX code). A LaTeX image can be enclosed in many environment
> types, float or non-float.

As I said above, I feel that :environment term will be overloaded then.
What about :wrap?

> ... However, :float can still be useful for
> certain combinations. For example, a minipage environment cannot include
> a caption (it produces an error of the type "LaTeX Error: \caption
> outside float").

Do we know in advance which environments support \caption and which not?
I feel that we may handle this programmatically without creating an array
of almost-identical attributes.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Are 'placement' and 'float' "obsolete terms" in inline images export

[Juan Manuel Macías]

Ihor Radchenko writes:

>> My suggestion is to add a :environment attribute next to another
>> :environment-options attr (or something like that, to introduce any
>> arbitrary LaTeX code). A LaTeX image can be enclosed in many environment
>> types, float or non-float.
>
> As I said above, I feel that :environment term will be overloaded then.
> What about :wrap?

I like :wrap. What's more, remembering that old thread where
some questions about code before/after the image were discussed,
what if the expected value of :wrap were a kind of template? This would
allow code to be placed before and/or after (not just an environment)
the image, always within the float environment, if it exists. Something
like this:

#+ATTR_LaTeX: :float nil :wrap \begin{minipage}[b]{10pc}\small\n%s\n\end{minipage} 
#+CAPTION: caption
[[file:foo.png]]

Thus :caption with value nil does not add any higher float environment
and would enclose (always within the template) the value of #+CAPTION as
\captionof{figure}{caption}. Of course, with a float environment
declared, :wrap can still be used. An internal environment is unlikely
(I can't think of any use case right now), but you can add arbitrary
code like \captionsetup{} or \ContinuedFloat, which should always go
inside the float environment.

The result of the previous example could also be obtained with:

#+ATTR_LaTeX: :float minipage :placement [b]{10pc} :caption \captionof{figure}{caption} 
[[file:foo.png]]

I don't know if it would be appropriate to explain in the Manual that
doing so would not be... "correct"? I don't know if there is any term in
programming to designate these situations which, without being bugs, are
functionalities not consciously sought...

>> ... However, :float can still be useful for
>> certain combinations. For example, a minipage environment cannot include
>> a caption (it produces an error of the type "LaTeX Error: \caption
>> outside float").
>
> Do we know in advance which environments support \caption and which not?
> I feel that we may handle this programmatically without creating an array
> of almost-identical attributes.

I like the idea, but unfortunately, apart from the known float
environments, there are those that a user can define using the \newfloat
command from the float package.

-- 
Juan Manuel Macías

https://juanmanuelmacias.com

https://lunotipia.juanmanuelmacias.com

https://gnutas.juanmanuelmacias.com

Re: Are 'placement' and 'float' "obsolete terms" in inline images export

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

>> What about :wrap?
>
> I like :wrap. What's more, remembering that old thread where
> some questions about code before/after the image were discussed,
> what if the expected value of :wrap were a kind of template? This would
> allow code to be placed before and/or after (not just an environment)
> the image, always within the float environment, if it exists. Something
> like this:
>
> #+ATTR_LaTeX: :float nil :wrap \begin{minipage}[b]{10pc}\small\n%s\n\end{minipage} 
> #+CAPTION: caption
> [[file:foo.png]]
> ...
> #+ATTR_LaTeX: :float minipage :placement [b]{10pc} :caption \captionof{figure}{caption} 
> [[file:foo.png]]
>
> I don't know if it would be appropriate to explain in the Manual that
> doing so would not be... "correct"? I don't know if there is any term in
> programming to designate these situations which, without being bugs, are
> functionalities not consciously sought...

What about making :wrap override :float completely + obsoleting :float.
We can allow wrap to have special values like in float:

:wrap t/:wrap multicolumn/:wrap sideways

With these special values, :placement will be taken into account.

Further, we can make templates a bit more detailed.
Starting from similar to what you proposed in the above

:wrap \begin{minipage}[b]{10pc}\small\n%{body}\n\end{minipage}

to more granular control over caption, centering, comment-include,
and image-code:

%{caption} %{caption-text} %{centering} %{comment} %{comment-text}
 %{image} %{image-path}.

If the :wrap text does not contain %{...} placeholder, it will be
treated as what  :float artbirary-environment does.

We may even consider something like

#+name: latex-template
#+begin_src latex :export none
\begin{minipage}[b]{10pc}\small
%{body}
\end{minipage}
#+end_src

#+attr_latex: :wrap latex-template[]

As a bonus, :wrap may allow prepending/appending arbitrary code to
headings:

* Heading starting at a new page
:PROPERTIES:
:ATTR_LATEX: :wrap \clarpage%{default}
:END:

>>> ... However, :float can still be useful for
>>> certain combinations. For example, a minipage environment cannot include
>>> a caption (it produces an error of the type "LaTeX Error: \caption
>>> outside float").
>>
>> Do we know in advance which environments support \caption and which not?
>> I feel that we may handle this programmatically without creating an array
>> of almost-identical attributes.
>
> I like the idea, but unfortunately, apart from the known float
> environments, there are those that a user can define using the \newfloat
> command from the float package.

We might also consider :caption-template \captionof{figure}{%{caption-text}}

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Are 'placement' and 'float' "obsolete terms" in inline images export

[Juan Manuel Macías]

Apologies for my delay in answering all the interesting questions
you raised in this last message. November and December have been
horrible work days for me (all publishers are always in a hurry) and I
haven't been able to attend to the mailing list as I would like...

Ihor Radchenko writes:

> Juan Manuel Macías <maciaschain@posteo.net> writes:
>
>>> What about :wrap?
>>
>> I like :wrap. What's more, remembering that old thread where
>> some questions about code before/after the image were discussed,
>> what if the expected value of :wrap were a kind of template? This would
>> allow code to be placed before and/or after (not just an environment)
>> the image, always within the float environment, if it exists. Something
>> like this:
>>
>> #+ATTR_LaTeX: :float nil :wrap \begin{minipage}[b]{10pc}\small\n%s\n\end{minipage} 
>> #+CAPTION: caption
>> [[file:foo.png]]
>> ...
>> #+ATTR_LaTeX: :float minipage :placement [b]{10pc} :caption \captionof{figure}{caption} 
>> [[file:foo.png]]
>>
>> I don't know if it would be appropriate to explain in the Manual that
>> doing so would not be... "correct"? I don't know if there is any term in
>> programming to designate these situations which, without being bugs, are
>> functionalities not consciously sought...
>
> What about making :wrap override :float completely + obsoleting :float.
> We can allow wrap to have special values like in float:
>
> :wrap t/:wrap multicolumn/:wrap sideways
>
> With these special values, :placement will be taken into account.

+1. Great idea.

> Further, we can make templates a bit more detailed.
> Starting from similar to what you proposed in the above
>
> :wrap \begin{minipage}[b]{10pc}\small\n%{body}\n\end{minipage}
>
> to more granular control over caption, centering, comment-include,
> and image-code:
>
> %{caption} %{caption-text} %{centering} %{comment} %{comment-text}
>  %{image} %{image-path}.
>
> If the :wrap text does not contain %{...} placeholder, it will be
> treated as what  :float artbirary-environment does.
>
> We may even consider something like
>
> #+name: latex-template
> #+begin_src latex :export none
>
> \begin{minipage}[b]{10pc}\small
> %{body}
> \end{minipage}
> #+end_src
>
> #+attr_latex: :wrap latex-template[]
>
> As a bonus, :wrap may allow prepending/appending arbitrary code to
> headings:
>
> * Heading starting at a new page
> :PROPERTIES:
> :ATTR_LATEX: :wrap \clarpage%{default}
> :END:

I really like what you propose, both the idea and the syntax. I think
that such a versatile template system (with such a level of granularity
but with a clear syntax at the same time) would be a killer feature. It
wouldn't be bad to also extend it to the case of tables and other
backends, such as html. I also think it would solve a "classic" Org
syntax issue (in my opinion) which is the difficulty in 'nesting things'.
Well, it can be done currently (for example, the special blocks do their job
pretty  well), but at the cost of increasing the verbosity of the code (I am
thinking, for example, of using the LaTeX threeparttable package through
nested special blocks...)

Best regards, and  happy New Year

-- 
Juan Manuel Macías