Confusion about attr_latex and new exporter

Confusion about attr_latex and new exporter

[John Hendy]

Just making the transition to the new exporter, finally, today. Just
some notes regarding the documentation that I wanted to pass along. I
think there's some possibly conflicting information (or at least
ambiguous) out there.

- From the Worg page on transitioning to the new exporter
(http://orgmode.org/worg/org-8.0.html):
#+begin_quote

Attribute lines now take plists:
#+attr_latex :width "5cm"
#+attr_beamer :options "width=5cm"

#+end_quote

However, from a previous email, I think a caveat should be added, as I
found the above misleading in trying my first test drive of the new
exporter. I recalled an earlier response on the mailing list to an
inquiry I had about the old exporter, which evolved into some
discussion about the new one:
- http://lists.gnu.org/archive/html/emacs-orgmode/2013-02/msg00850.html

So, as this pertains to the transitioning guide: using =:width= as an
example of the new syntax is perhaps a bad idea since it's heavily
associated with #+attr_latex: width=Xcm for images and yet is
incorrect for image attributes. At the very least, some further
specification of the :width option should probably be referenced right
then and there.

Another fantastic quote one might consider adding, which really helped
make things "click" for me is from the same thread a bit later:
- http://lists.gnu.org/archive/html/emacs-orgmode/2013-02/msg00882.html

#+begin_quote Nicolas

An argument within curly brackets gets its own keyword. Optional arguments
are stuffed within an `:options' keyword.

#+end_quote

That's quite helpful!
- \begin{tabular}{align=blah} --> :align "blah" (curly gets :keyword)
- \includegraphics[width=blah]{file.jpg} --> :options "width=blah"
(optional gets :options)

Now, even having digested some of this a bit better, using any syntax
option (at least that I can tell is correct from the above) with
quotes yields quotes in the resulting .tex file and a resultant fail
of pdflatex compilation.

In other words:

- Org:
attr_latex: :options "width=5cm"
[[file.jpg]]

- LaTeX:
\includegraphics["width=5cm"]{file.jpg}

- Org
attr_latex: :align "lp{4cm}"
| column 1 | column 2 |

- LaTeX:
\begin{tabular}{"lp{4cm}"}

I also tried =:width "5cm"= for images. Despite this being options and
sounding like it needs to be in the :options string instead of :width,
it still works but quoted parts still get quotes =[width="5cm"]= in
the resultant .tex file. If I remove quotes, it works. That's fine,
but not sure if I'll ever run into any multi-word option occurrences
where I'll possibly need quotes to differentiate one set of option
values from another (don't think I've run into this before, but just
thinking out loud).

Am I doing something wrong if this is the behavior I'm getting, or is
the documentation incorrect and I shouldn't be quoting these options?


Thanks,
John

Re: Confusion about attr_latex and new exporter

[John Hendy]

On Sun, Mar 17, 2013 at 4:57 PM, John Hendy <jw.hendy@gmail.com> wrote:
> Just making the transition to the new exporter, finally, today. Just
> some notes regarding the documentation that I wanted to pass along. I
> think there's some possibly conflicting information (or at least
> ambiguous) out there.
>
> - From the Worg page on transitioning to the new exporter
> (http://orgmode.org/worg/org-8.0.html):
> #+begin_quote
>
> Attribute lines now take plists:
> #+attr_latex :width "5cm"
> #+attr_beamer :options "width=5cm"
>
> #+end_quote
>
> However, from a previous email, I think a caveat should be added, as I
> found the above misleading in trying my first test drive of the new
> exporter. I recalled an earlier response on the mailing list to an
> inquiry I had about the old exporter, which evolved into some
> discussion about the new one:
> - http://lists.gnu.org/archive/html/emacs-orgmode/2013-02/msg00850.html
>
> So, as this pertains to the transitioning guide: using =:width= as an
> example of the new syntax is perhaps a bad idea since it's heavily
> associated with #+attr_latex: width=Xcm for images and yet is
> incorrect for image attributes. At the very least, some further
> specification of the :width option should probably be referenced right
> then and there.
>
> Another fantastic quote one might consider adding, which really helped
> make things "click" for me is from the same thread a bit later:
> - http://lists.gnu.org/archive/html/emacs-orgmode/2013-02/msg00882.html
>
> #+begin_quote Nicolas
>
> An argument within curly brackets gets its own keyword. Optional arguments
> are stuffed within an `:options' keyword.
>
> #+end_quote
>
> That's quite helpful!
> - \begin{tabular}{align=blah} --> :align "blah" (curly gets :keyword)
> - \includegraphics[width=blah]{file.jpg} --> :options "width=blah"
> (optional gets :options)
>
> Now, even having digested some of this a bit better, using any syntax
> option (at least that I can tell is correct from the above) with
> quotes yields quotes in the resulting .tex file and a resultant fail
> of pdflatex compilation.
>
> In other words:
>
> - Org:
> attr_latex: :options "width=5cm"
> [[file.jpg]]
>
> - LaTeX:
> \includegraphics["width=5cm"]{file.jpg}
>
> - Org
> attr_latex: :align "lp{4cm}"
> | column 1 | column 2 |
>
> - LaTeX:
> \begin{tabular}{"lp{4cm}"}
>
> I also tried =:width "5cm"= for images. Despite this being options and
> sounding like it needs to be in the :options string instead of :width,
> it still works but quoted parts still get quotes =[width="5cm"]= in
> the resultant .tex file. If I remove quotes, it works. That's fine,
> but not sure if I'll ever run into any multi-word option occurrences
> where I'll possibly need quotes to differentiate one set of option
> values from another (don't think I've run into this before, but just
> thinking out loud).
>
> Am I doing something wrong if this is the behavior I'm getting, or is
> the documentation incorrect and I shouldn't be quoting these options?
>
>
> Thanks,
> John

Sigh. Just when I thought I'd done my due diligence, I [re]found this:
- http://comments.gmane.org/gmane.emacs.orgmode/68256

Which points to this:
- http://comments.gmane.org/gmane.emacs.orgmode/68011

Talk about a fairly massive amount of time to discover that it's
simply using the babel syntax =:width value= (no quotes). I'll state
that the announcement (second link above) is still confusing to me, as
Nicolas has stated:

#+begin_quote
From the user POV, it removes necessity to quote or escape characters.
For example, these are now valid:

  #+attr_latex: :font \footnotesize :align |l|c|c|
  #+attr_foo: :prop var="value" :another-prop nil

#+end_quote

Thus, I would have expected =#+attr_latex :options width="value"= to
work, but it doesn't. Seems like :width is being treated specially, or
did I just not parse =:prop var="value"= correctly?


Thanks,
John

Re: Confusion about attr_latex and new exporter

[Thomas S. Dye]

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

>
> Am I doing something wrong if this is the behavior I'm getting, or is
> the documentation incorrect and I shouldn't be quoting these options?

Nicolas cleaned up the attribute syntax recently.  Previously, quotes
were needed and backslashes were escaped.  Now, quotes are not used and
backslashes don't need to be escaped.  Multi-word options are fine
without quotes.

hth,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Confusion about attr_latex and new exporter

[John Hendy]

On Sun, Mar 17, 2013 at 5:22 PM, Thomas S. Dye <tsd@tsdye.com> wrote:
> Hi John,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>>
>> Am I doing something wrong if this is the behavior I'm getting, or is
>> the documentation incorrect and I shouldn't be quoting these options?
>
> Nicolas cleaned up the attribute syntax recently.  Previously, quotes
> were needed and backslashes were escaped.  Now, quotes are not used and
> backslashes don't need to be escaped.  Multi-word options are fine
> without quotes.
>

Thanks, Tom. Having an issue, though. From what I've read/heard...
=:width= is used for all backends now? This seems to be indicated by
this pretty recent post as well:
- http://permalink.gmane.org/gmane.emacs.orgmode/68306

#+begin_quote Aaron Ecay

Eliminating subtleties is precisely the point of this change.  All(-ish)*
backends now use :width.

* As far as I’ve checked, HTML(+ derived backends) and LaTeX(+derived
backends).  If there are any that don’t, they should probably be patched
to do so as well.

#+end_quote

Using #+attr_html :width 200px results in <img src="" :width 200px
alt="" /> for me.

Why isn't :width for html being parsed into width="200px" ?

:options width="200px" works properly... but then again, I thought we
did away with :options var="value" syntax.

Just trying to keep up!


Thanks,
John

> hth,
> Tom
>
> --
> Thomas S. Dye
> http://www.tsdye.com

Re: Confusion about attr_latex and new exporter

[Thomas S. Dye]

John Hendy <jw.hendy@gmail.com> writes:

> Thanks, Tom. Having an issue, though. From what I've read/heard...
> =:width= is used for all backends now? This seems to be indicated by
> this pretty recent post as well:
> - http://permalink.gmane.org/gmane.emacs.orgmode/68306
>
> #+begin_quote Aaron Ecay
>
> Eliminating subtleties is precisely the point of this change.  All(-ish)*
> backends now use :width.
>
> * As far as I.ve checked, HTML(+ derived backends) and LaTeX(+derived
> backends).  If there are any that don.t, they should probably be patched
> to do so as well.
>
> #+end_quote
>
> Using #+attr_html :width 200px results in <img src="" :width 200px
> alt="" /> for me.
>
> Why isn't :width for html being parsed into width="200px" ?
>
> :options width="200px" works properly... but then again, I thought we
> did away with :options var="value" syntax.
>
> Just trying to keep up!

You're ahead of me, John.  So far, I've used the latex and texinfo
exporters, but haven't looked at the others, so don't have a sense of
how uniform things might be across the backends.  I'm in awe of the
texinfo exporter, though.  It does a terrific job, AFAICT.

All the best,
Tom

-- 
T.S. Dye & Colleagues, Archaeologists
735 Bishop St, Suite 315, Honolulu, HI 96813
Tel: 808-529-0866, Fax: 808-529-0884
http://www.tsdye.com

Re: Confusion about attr_latex and new exporter

[Aaron Ecay]

Hi John,

2013ko martxoak 17an, John Hendy-ek idatzi zuen:
> 
> #+begin_quote Aaron Ecay
> 
> Eliminating subtleties is precisely the point of this change.  All(-ish)*
> backends now use :width.
> 
> * As far as I’ve checked, HTML(+ derived backends) and LaTeX(+derived
> backends).  If there are any that don’t, they should probably be patched
> to do so as well.
> 
> #+end_quote

I’m sorry, that was a mistake.  I sent a patch to the HTML backend to
enable this behavior, but forgot all about it.  Then when I checked the
code, it looked like the functionality was already there!  I’ll follow
up with Bastien about the patch, and see what its status is...

-- 
Aaron Ecay

Re: Confusion about attr_latex and new exporter

[Aaron Ecay]

Hi again,

2013ko martxoak 19an, Aaron Ecay-ek idatzi zuen:
> I’m sorry, that was a mistake.  I sent a patch to the HTML backend to
> enable this behavior, but forgot all about it.  Then when I checked the
> code, it looked like the functionality was already there!  I’ll follow
> up with Bastien about the patch, and see what its status is...

I was very confused when I wrote this.  The patches I had in mind were
for a different issue.  If
#+ATTR_HTML: :width 200
ever worked for me, it was only because of me hacking org into a
chimeric state.  I guess you should continue to use
#+ATTR_HTML: width=200
or whatever the working incantation for HTML has traditionally been.

Sorry for the noise,

-- 
Aaron Ecay

Re: Confusion about attr_latex and new exporter

[John Hendy]

On Tue, Mar 19, 2013 at 12:07 AM, Aaron Ecay <aaronecay@gmail.com> wrote:
> Hi again,
>
> 2013ko martxoak 19an, Aaron Ecay-ek idatzi zuen:
>> I’m sorry, that was a mistake.  I sent a patch to the HTML backend to
>> enable this behavior, but forgot all about it.  Then when I checked the
>> code, it looked like the functionality was already there!  I’ll follow
>> up with Bastien about the patch, and see what its status is...
>
> I was very confused when I wrote this.  The patches I had in mind were
> for a different issue.  If
> #+ATTR_HTML: :width 200
> ever worked for me, it was only because of me hacking org into a
> chimeric state.  I guess you should continue to use
> #+ATTR_HTML: width=200
> or whatever the working incantation for HTML has traditionally been.
>

Thanks for the clarification, though regardless of the current
state... what is the consensus on what it *should* be? The old lingo
was:
- #+attr_latex: width=Xcm
- #+attr_html: width="Xpx"

That made sense to me since that's how they appear in
\blah[width=Xcm]{file.png} or <img src="" width="Xpx" />.

With the move to :width value, I guess I'd rather see them work the
same or have it be obviously backend-specific vs. having :width Xcm
for LaTeX, and width=200 for html. At least make it identical to the
actual backend syntax (quotes around the 200 for html) or in pure
babel-esque language to unify (:width value, no quotes) for all.

At least that's my thought from a user's perspective.


Thanks!
John


> Sorry for the noise,
>
> --
> Aaron Ecay

Re: Confusion about attr_latex and new exporter

[Bastien]

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

> Thanks for the clarification, though regardless of the current
> state... what is the consensus on what it *should* be? The old lingo
> was:
> - #+attr_latex: width=Xcm
> - #+attr_html: width="Xpx"

... and the new lingo is

  #+attr_latex: :width Xcm
  #+attr_html: :width Xpx

for images.  Images allow :width :height :alt attributes, while other
elements like links and tables allow only the :options attribute.

I updated ox-html.el so that it respects this syntax.

Nicolas, would it be okay to make

  (org-export-read-attribute :attr_html element) 

return "title=\"Title\"" instead of nil when the element's attributes
are like this

  #+attr_html: title="Title"

?

Thanks,

-- 
 Bastien

Re: Confusion about attr_latex and new exporter

[John Hendy]

On Tue, Mar 19, 2013 at 1:49 PM, Bastien <bzg@altern.org> wrote:
> Hi John,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> Thanks for the clarification, though regardless of the current
>> state... what is the consensus on what it *should* be? The old lingo
>> was:
>> - #+attr_latex: width=Xcm
>> - #+attr_html: width="Xpx"
>
> ... and the new lingo is
>
>   #+attr_latex: :width Xcm
>   #+attr_html: :width Xpx
>
> for images.  Images allow :width :height :alt attributes, while other
> elements like links and tables allow only the :options attribute.

Upon fresh pull to Org-mode version 8.0-pre
(release_8.0-pre-146-g73fe0a), I confirm that =#+attr_html: :width
value= works as described above.

Thanks!
John

>
> I updated ox-html.el so that it respects this syntax.
>
> Nicolas, would it be okay to make
>
>   (org-export-read-attribute :attr_html element)
>
> return "title=\"Title\"" instead of nil when the element's attributes
> are like this
>
>   #+attr_html: title="Title"
>
> ?
>
> Thanks,
>
> --
>  Bastien

Re: Confusion about attr_latex and new exporter

[Bastien]

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

> I also tried =:width "5cm"= for images. Despite this being options and
> sounding like it needs to be in the :options string instead of :width,
> it still works but quoted parts still get quotes =[width="5cm"]= in
> the resultant .tex file. If I remove quotes, it works.

I removed the quotes in http://orgmode.org/worg/org-8.0.html

Thanks for reporting this,

-- 
 Bastien