[ox-publish] handling of white space in arguments of macros, named arguments?

[ox-publish] handling of white space in arguments of macros, named arguments?

[Stefan Vollmar]

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

Hallo,

I have just upgraded to release_8.0-pre-193-gaa7b1 and found that I needed to change a few things to get the desired results when exporting some of our org files to HTML. Our last changes were also targeted at the new exporter and everything worked fine about a month ago.

I found that I had to change HTML_STYLE to HTML_HEAD - not a problem. However, the second change is caused by our use of MACROs: we find them very helpful for generating HTML content using raw HTML templates with placeholders.

This used to work (for generating http://microformats.org/wiki/hcard information) a month ago:

{{{mhead-hcard(
Dr. Stefan Vollmar,
Stefan,
,
Vollmar,
Dr.,
stefan-vollmar.jpg,
stefan-vollmar.html,
...)}}}

with this type of macro definition:

#+macro: mhead-hcard #+html: <div id="contact" class="vcard"><p><table style="margin-left:0;margin-right:auto"><tr style="text-align: left;margin-left: 2em"><td style="padding: 5px"><img width="200px" class="photo" src="images/$6" alt="$1" /></td><td><a style="color:blue;" class="url" href="http://www.nf.mpg.de/cv/$7"><div class="fn n"><span class="honorific-prefix">$5</span> <span class="given-name">$2</span>[...]

but now the white space around the arguments is no longer stripped and/or other effects cause "<" and ">" in the macro to be exported as "&lt;" etc.

This version seems to work fine:

{{{mhead-hcard(Dr. Stefan Vollmar,Stefan,,Vollmar,Dr.,stefan-vollmar.jpg,stefan-vollmar.html,Head of IT Group\,<br/>Physicist\, Software Developer,vollmar@nf.mpg.de,it,+49 221 4726-213,+49 221 4726-298)}}}

Yes, I could use it as a workaround, but I would prefer something similar to the above version for improved readability - maybe by adding "line continuation markers" like "\"? Obviously, more complex macros (the one above has 12 individual arguments) are less than ideal anyway and the best solution (by far) would be "named arguments". Maybe there already is a better way of using (HTML) templates?

Many thanks in advance.
Warm regards,
 Stefan
-- 
Dr. Stefan Vollmar, Dipl.-Phys.
Head of IT group
Max-Planck-Institut für neurologische Forschung
Gleueler Str. 50, 50931 Köln, Germany
Tel.: +49-221-4726-213  FAX +49-221-4726-298
Tel.: +49-221-478-5713  Mobile: 0160-93874279
E-Mail: vollmar@nf.mpg.de   http://www.nf.mpg.de









[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 4409 bytes --]

Re: [ox-publish] handling of white space in arguments of macros, named arguments?

[Nicolas Goaziou]

Hello,

Stefan Vollmar <vollmar@nf.mpg.de> writes:

> However, the second change is caused by our use of MACROs: we find
> them very helpful for generating HTML content using raw HTML templates
> with placeholders.
>
> This used to work (for generating http://microformats.org/wiki/hcard information) a month ago:
>
> {{{mhead-hcard(
> Dr. Stefan Vollmar,
> Stefan,
> ,
> Vollmar,
> Dr.,
> stefan-vollmar.jpg,
> stefan-vollmar.html,
> ...)}}}
>
> with this type of macro definition:
>
> #+macro: mhead-hcard #+html: <div id="contact" class="vcard"><p><table style="margin-left:0;margin-right:auto"><tr style="text-align: left;margin-left: 2em"><td style="padding: 5px"><img width="200px" class="photo" src="images/$6" alt="$1" /></td><td><a style="color:blue;" class="url" href="http://www.nf.mpg.de/cv/$7"><div class="fn n"><span class="honorific-prefix">$5</span> <span class="given-name">$2</span>[...]
>
> but now the white space around the arguments is no longer stripped and/or other effects cause "<" and ">" in the macro to be exported as "&lt;" etc.
>
> This version seems to work fine:
>
> {{{mhead-hcard(Dr. Stefan
> Vollmar,Stefan,,Vollmar,Dr.,stefan-vollmar.jpg,stefan-vollmar.html,Head
> of IT Group\,<br/>Physicist\, Software
> Developer,vollmar@nf.mpg.de,it,+49 221 4726-213,+49 221 4726-298)}}}

I removed trimming around arguments a few days ago, since it wasn't an
explicit specification for macros. Therefore, newline characters are
inserted in your template, which means that the HTML keyword doesn't
affect all lines of the generated code and, as a consequence, some "<"
are exported as "&lt;".

I think all newline characters should be replaced with a whitespace
character in macro arguments. Indeed, macro templates are only one line
long but unwanted "\n" could be inserted by paragraph filling in
arguments.

I also don't mind trimming arguments again, provided this is added as an
explicit behaviour and there is no opposition to it.

> Yes, I could use it as a workaround, but I would prefer something
> similar to the above version for improved readability - maybe by
> adding "line continuation markers" like "\"? Obviously, more complex
> macros (the one above has 12 individual arguments) are less than ideal
> anyway and the best solution (by far) would be "named arguments".
> Maybe there already is a better way of using (HTML) templates?

I think you really shouldn't use macros for that. For example, consider
adding the following in your buffer (or, better, in the Library of
Babel):

  #+name: mhead-hcard
  #+header: :var cname="Complete Name" gname="Given Name" photo="photo.jpg" prefix=""
  #+header: :var web="web-page.html"
  #+BEGIN_SRC org :exports none
  <div id="contact" class="vcard">
    <p>
      <table style="margin-left:0;margin-right:auto">
        <tr style="text-align: left;margin-left: 2em">
          <td style="padding: 5px">
            <img width="200px" class="photo" src="images/$photo" alt="$cname" />
          </td>
          <td><a style="color:blue;" class="url" href="http://www.nf.mpg.de/cv/$web">
            <div class="fn n">
              <span class="honorific-prefix">$prefix</span>
              <span class="given-name">$gname</span>
  ...
  #+END_SRC

Then, you insert a hcard with:

  #+call: mhead-hcard(cname="Dr. Stefan Vollmar",gname="Stefan",prefix="Dr.",web="stefan-vollmar.html",photo="stefan-vollmar.jpg") :results html


Regards,

-- 
Nicolas Goaziou

Re: [ox-publish] handling of white space in arguments of macros, named arguments?

[Achim Gratz]

Am 27.03.2013 17:26, schrieb Nicolas Goaziou:
> I think all newline characters should be replaced with a whitespace
> character in macro arguments. Indeed, macro templates are only one line
> long but unwanted "\n" could be inserted by paragraph filling in
> arguments.

I'm not sure about that, it would mean that there'd need to be 
additional syntax to insert linebreaks.

> I also don't mind trimming arguments again, provided this is added as an
> explicit behaviour and there is no opposition to it.

How about making trimming explicit during the expansion of macro 
arguments?  It seems that there are a few possibilities of what trimming 
could mean, so this would be an opportunity to allow them all (n is the 
argument number):

$:n  - remove whitespace and linebreaks before argument
$.n  - remove whitespace and linebreaks after argument
$n   - same as $:.n
$+n  - replace whitespace and linebreaks inside arguments
        with a single space
$*n  - same as $:+.n
$~n  - literal argument (no trimming)


Regards,
-- 
Achim.

(on the road :-)

Re: [ox-publish] handling of white space in arguments of macros, named arguments?

[Stefan Vollmar]

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

Dear Nicolas,

On 27.03.2013, at 17:26, Nicolas Goaziou wrote:

>> ...
>> 
>> but now the white space around the arguments is no longer stripped and/or other effects cause "<" and ">" in the macro to be exported as "&lt;" etc.
>> 
>> This version seems to work fine:
>> 
>> {{{mhead-hcard(Dr. Stefan
>> Vollmar,Stefan,,Vollmar,Dr.,stefan-vollmar.jpg,stefan-vollmar.html,Head
>> of IT Group\,<br/>Physicist\, Software
>> Developer,vollmar@nf.mpg.de,it,+49 221 4726-213,+49 221 4726-298)}}}
> 
> I removed trimming around arguments a few days ago, since it wasn't an
> explicit specification for macros. Therefore, newline characters are
> inserted in your template, which means that the HTML keyword doesn't
> affect all lines of the generated code and, as a consequence, some "<"
> are exported as "&lt;".

OK, thanks - that obviously explains it. I think you are absolutely right that our previous solution was build around unspecified assumptions.

> I think all newline characters should be replaced with a whitespace
> character in macro arguments. Indeed, macro templates are only one line
> long but unwanted "\n" could be inserted by paragraph filling in
> arguments.

You are referring to some workaround that could mimick the old behaviour? Could you give an example? (Maybe this might be of interest for some simple "legacy cases" of ours)

> I also don't mind trimming arguments again, provided this is added as an explicit behaviour and there is no opposition to it.

From my point of view it would be convenient for some code we already have and do not need to change - but, on second thoughts, you are right: it is somewhat artificial.

>> Yes, I could use it as a workaround, but I would prefer something
>> similar to the above version for improved readability - maybe by
>> adding "line continuation markers" like "\"? Obviously, more complex
>> macros (the one above has 12 individual arguments) are less than ideal
>> anyway and the best solution (by far) would be "named arguments".
>> Maybe there already is a better way of using (HTML) templates?
> 
> I think you really shouldn't use macros for that. For example, consider
> adding the following in your buffer (or, better, in the Library of
> Babel):
> 
>  #+name: mhead-hcard
>  #+header: :var cname="Complete Name" gname="Given Name" photo="photo.jpg" prefix=""
>  #+header: :var web="web-page.html"
>  #+BEGIN_SRC org :exports none
>  <div id="contact" class="vcard">
>    <p>
>      <table style="margin-left:0;margin-right:auto">
>        <tr style="text-align: left;margin-left: 2em">
>          <td style="padding: 5px">
>            <img width="200px" class="photo" src="images/$photo" alt="$cname" />
>          </td>
>          <td><a style="color:blue;" class="url" href="http://www.nf.mpg.de/cv/$web">
>            <div class="fn n">
>              <span class="honorific-prefix">$prefix</span>
>              <span class="given-name">$gname</span>
>  ...
>  #+END_SRC
> 
> Then, you insert a hcard with:
> 
>  #+call: mhead-hcard(cname="Dr. Stefan Vollmar",gname="Stefan",prefix="Dr.",web="stefan-vollmar.html",photo="stefan-vollmar.jpg") :results html

EXCELLENT - this is much better than what I had hoped for. Here is another happy Babel fan!

Warm regards,
 Stefan
-- 
Dr. Stefan Vollmar, Dipl.-Phys.
Head of IT group
Max-Planck-Institut für neurologische Forschung
Gleueler Str. 50, 50931 Köln, Germany
Tel.: +49-221-4726-213  FAX +49-221-4726-298
Tel.: +49-221-478-5713  Mobile: 0160-93874279
E-Mail: vollmar@nf.mpg.de   http://www.nf.mpg.de









[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 4409 bytes --]

Re: [ox-publish] handling of white space in arguments of macros, named arguments?

[Nicolas Goaziou]

Hello,

Achim Gratz <Stromeko@Nexgo.DE> writes:

> Am 27.03.2013 17:26, schrieb Nicolas Goaziou:
>> I think all newline characters should be replaced with a whitespace
>> character in macro arguments. Indeed, macro templates are only one line
>> long but unwanted "\n" could be inserted by paragraph filling in
>> arguments.
>
> I'm not sure about that, it would mean that there'd need to be
> additional syntax to insert linebreaks.

My point is that macro templates have to fit in a single line, no
newline character allowed. As a consequence, macro arguments are
implicitly expected to fit in a single line. So a newline character in
an argument is probably wrong.

>> I also don't mind trimming arguments again, provided this is added as an
>> explicit behaviour and there is no opposition to it.
>
> How about making trimming explicit during the expansion of macro
> arguments?  It seems that there are a few possibilities of what
> trimming could mean, so this would be an opportunity to allow them all
> (n is the argument number):
>
> $:n  - remove whitespace and linebreaks before argument
> $.n  - remove whitespace and linebreaks after argument
> $n   - same as $:.n
> $+n  - replace whitespace and linebreaks inside arguments
>        with a single space
> $*n  - same as $:+.n
> $~n  - literal argument (no trimming)

The current trend for macros is to be really simple so that advanced
(and not-so advanced) tasks are done with Babel instead. IOW, macros are
only useful if they are simpler than the simplest form of Babel usage.
In every other case, Babel is a superior choice.

Your suggestion is interesting, but I think it would go backwards wrt
this.


Regards,

-- 
Nicolas Goaziou

Re: [ox-publish] handling of white space in arguments of macros, named arguments?

[Achim Gratz]

Am 28.03.2013 17:22, schrieb Nicolas Goaziou:
> My point is that macro templates have to fit in a single line, no
> newline character allowed. As a consequence, macro arguments are
> implicitly expected to fit in a single line. So a newline character in
> an argument is probably wrong.

My point is that the form of the template really doesn't tell you much 
about the (possibly recursive) expansion and since the feature is 
relatively new there is absolutely no data to determine if such an 
assumption would restrict macros too much.  I can certainly see good 
uses of linebreaks in macro expansions.

> The current trend for macros is to be really simple so that advanced
> (and not-so advanced) tasks are done with Babel instead. IOW, macros are
> only useful if they are simpler than the simplest form of Babel usage.

In this case, you probly can't or how do you get linebreaks into 
arguments of a Babel call (not using escape sequences)?

> In every other case, Babel is a superior choice.

I think that there is some middle ground to cover here.  There is no 
reason to ask for confirmation in the example you gave for the vcard 
insertion, for example.  All it does is a simple template expansion, in 
other words it acts like a multi-line macro definition with named 
parameters.

> Your suggestion is interesting, but I think it would go backwards wrt
> this.

Babel is very nice, but I don't think we should foist it onto everyone, 
there are good reasons to stick to plain Org in some situations.  The 
evaluation confirmation should get a bit smarter, too, but I don't see 
how to do that easily (I've already looked).  The way things work at the 
moment you have to globally switch off confirmation for all but the most 
simple uses of Babel.


Regards,
-- 
Achim.

(on the road :-)