[ox] possible to modify org-export-document-properties OTG

[ox] possible to modify org-export-document-properties OTG

[Rasmus]

Hi,

Is it possible to modify or extend org-export-document-properties on the
go?  And would it be OK?  From the docstring of ox-version version of
document-properties I would say 'yes'.  I'm not sure when reading the
docstrig of org-element version.

Or should org-element-parse-secondary-string be used with appropriate
limitations?

It would be useful 'cause it's an easy way to have a property parsed.  In
ox-koma-letter.el it would make sense to make #+SUBJECT a document
property (ATM org-syntax isn't interpreted).  In some backends it would
probably also make sense to make #+KEYWORDS parsed.  I'm also working on a
patch to add #+SUBTITLE, which would also benefit from being easily added
as a document-property.

—Rasmus

-- 
Lasciate ogni speranza, voi che leggete questo.

Re: [ox] possible to modify org-export-document-properties OTG

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> Is it possible to modify or extend org-export-document-properties on the
> go?  And would it be OK?

`org-export-document-properties' is a defconst, which is computed from
`org-element-document-properties', also a defconst. So, no, it
isn't meant for that.

Document properties are keywords where `org-element-context' is allowed
to return an object. It doesn't make sense to add random keywords
specific to some export back-ends to the list.

> Or should org-element-parse-secondary-string be used with appropriate
> limitations?

For now, I suggest to use `org-element-parse-secondary-string'.

> It would be useful 'cause it's an easy way to have a property parsed.  In
> ox-koma-letter.el it would make sense to make #+SUBJECT a document
> property (ATM org-syntax isn't interpreted).  In some backends it would
> probably also make sense to make #+KEYWORDS parsed.  I'm also working on a
> patch to add #+SUBTITLE, which would also benefit from being easily added
> as a document-property.

You can always use `org-element-parse-secondary-string' on the keyword
value and `org-export-data' or `org-export-data-with-backend' on it.

At some point, I thought about adding a `parsed' behaviour to
`org-export-options-alist' as a shortcut. Sadly, I cannot remember why
I didn't implement the idea eventually. It may be related to
`org-element-map', which couldn't map over data in such keywords, or the
fact that it would be confusing wrt `org-element-context'. E.g., if we
consider the two keywords

  #+TITLE: *boXld*
  #+PARSED_KÊYWORD_IN_SOME_BACKEND_IGNORED_IN_OTHERS: *boXld*

in the former, `org-element-context' at "X" returns a `bold' object, in
the latter, a `keyword' element. Note that I'm not arguing it should
return a `bold' object in both cases, it really shouldn't, but it can be
confusing and potentially trigger false bug reports.


Regards,

-- 
Nicolas Goaziou

Re: [ox] possible to modify org-export-document-properties OTG

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Document properties are keywords where `org-element-context' is allowed
> to return an object. It doesn't make sense to add random keywords
> specific to some export back-ends to the list.

I think something like SUBJECT in ox-koma-letter makes sense.  But what
I'm really after is an "easy" way to control org-export-data from the
backend definition.

>> Or should org-element-parse-secondary-string be used with appropriate
>> limitations?
>
> For now, I suggest to use `org-element-parse-secondary-string'.

Why I don't like this is that it feels quite low-level (purely emotional)

    (org-export-data (oe-parse-2nd-string ⋯) ⋯)

> At some point, I thought about adding a `parsed' behaviour to
> `org-export-options-alist' as a shortcut.

Presumably you'd want to be able to toggle it for elements of
export-options.

> Sadly, I cannot remember why I didn't implement the idea eventually. It
> may be related to `org-element-map', which couldn't map over data in
> such keywords, or the fact that it would be confusing wrt
> `org-element-context'. E.g., if we consider the two keywords
>
>   #+TITLE: *boXld*
>   #+PARSED_KYWORD_IN_SOME_BACKEND_IGNORED_IN_OTHERS: *boXld*
>
> in the former, `org-element-context' at "X" returns a `bold' object, in
> the latter, a `keyword' element. Note that I'm not arguing it should
> return a `bold' object in both cases, it really shouldn't, but it can be
> confusing and potentially trigger false bug reports.

I don't understand why an export setting would affect an element
interpretation such as org-element-map.  Probably I have something
different in mind than you.

–Rasmus

-- 
However beautiful the theory, you should occasionally look at the evidence

Re: [ox] possible to modify org-export-document-properties OTG

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Document properties are keywords where `org-element-context' is allowed
>> to return an object. It doesn't make sense to add random keywords
>> specific to some export back-ends to the list.
>
> I think something like SUBJECT in ox-koma-letter makes sense.

It seems we are failing to communicate. 

I have nothing against SUBJECT being parsed in "ox-koma-letter".
However, `org-element-document-properties' are keywords expected to be
parsed in _every_ export back-end. This is not for SUBJECT.

>> At some point, I thought about adding a `parsed' behaviour to
>> `org-export-options-alist' as a shortcut.
>
> Presumably you'd want to be able to toggle it for elements of
> export-options.

I mean to use `parsed' at the BEHAVIOR position in
`org-export-options-alist' entries. So, obviously, this is triggered per
keyword.

> I don't understand why an export setting would affect an element
> interpretation such as org-element-map.  Probably I have something
> different in mind than you.

If you map over a parse tree, e.g., looking for bold objects, it is
a bit tricky to tell `org-element-map' that SUBJECT is no longer
a regular keyword but now possibly contains objects.

OTOH, we can consider that SUBJECT is still a regular keyword, and that
the property the keyword sets (e.g., :koma-letter-subject) contains the
objects.

In this case, it is no longer ambiguous for `org-element-map' and al.,
and `parsed' becomes an interesting shortcut.

Regards,

Re: [ox] possible to modify org-export-document-properties OTG

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> I think something like SUBJECT in ox-koma-letter makes sense.
>
> It seems we are failing to communicate. 

Probably I'm just slower :)

> I have nothing against SUBJECT being parsed in "ox-koma-letter".
> However, `org-element-document-properties' are keywords expected to be
> parsed in _every_ export back-end. This is not for SUBJECT.

Yep.  That was why I asked if it was possible to add it on backend basis.
But the oe-parse-secondary-string is fin.  Now I know.


> I mean to use `parsed' at the BEHAVIOR position in
> `org-export-options-alist' entries. So, obviously, this is triggered per
> keyword.

I /think/ that is what I would like.  But I don't understand the what you
mean concretely: would you have something like:

     (:subject "SUBJECT" nil nil space parsed)

I don't understand how it could replace the behavior parameter.  Would it
be a cons?


> If you map over a parse tree, e.g., looking for bold objects, it is
> a bit tricky to tell `org-element-map' that SUBJECT is no longer
> a regular keyword but now possibly contains objects.
> 
> OTOH, we can consider that SUBJECT is still a regular keyword, and that
> the property the keyword sets (e.g., :koma-letter-subject) contains the
> objects.
>
> In this case, it is no longer ambiguous for `org-element-map' and al.,
> and `parsed' becomes an interesting shortcut.

I agree this is a difficult problem.  Personally, I think it is fine to
consider a keyword as a keyword and nothing more, and not consider content
within a keyword.  However, as I recall, John had a post a while back
about mapping over bold in CAPTIONS or something like that.

I think it may be a mess to interpret content of a keyword at
org-element-map level.  Consider if #+SUBJECT is interpreted with in
ox-koma-letter but not in an imaginary ox-new-letter.  Would it not be
confusing?

—Rasmus

-- 
Dung makes an excellent fertilizer

Re: [ox] possible to modify org-export-document-properties OTG

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> I /think/ that is what I would like.  But I don't understand the what you
> mean concretely: would you have something like:
>
>      (:subject "SUBJECT" nil nil space parsed)


       (:subject "SUBJECT" nil nil parsed)

`parsed' behavior implies `space' anyway, since we're talking about
secondary strings.

Basically, 

  (plist-get info :subject)

would return the same as the following, currently,

  (org-element-parse-secondary-string 
   (plist-get info :subject) (org-element-restriction 'keyword))

> I agree this is a difficult problem.  Personally, I think it is fine to
> consider a keyword as a keyword and nothing more, and not consider content
> within a keyword.  However, as I recall, John had a post a while back
> about mapping over bold in CAPTIONS or something like that.

`org-element-map' can find objects in captions, with an optional
argument.

> I think it may be a mess to interpret content of a keyword at
> org-element-map level.  Consider if #+SUBJECT is interpreted with in
> ox-koma-letter but not in an imaginary ox-new-letter.  Would it not be
> confusing?

I think so.


Regards,

Re: [ox] possible to modify org-export-document-properties OTG

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> I /think/ that is what I would like.  But I don't understand the what you
>> mean concretely: would you have something like:
>>
>>      (:subject "SUBJECT" nil nil space parsed)
>
>
>        (:subject "SUBJECT" nil nil parsed)
>
> `parsed' behavior implies `space' anyway, since we're talking about
> secondary strings.

Is that always the case?  I guess..

>> I agree this is a difficult problem.  Personally, I think it is fine to
>> consider a keyword as a keyword and nothing more, and not consider content
>> within a keyword.  However, as I recall, John had a post a while back
>> about mapping over bold in CAPTIONS or something like that.
>
> `org-element-map' can find objects in captions, with an optional
> argument.

If turns out to be important, perhaps it would also be possible to map
keyword objects with an non-default argument.


-- 
Don't panic!!!

Re: [ox] possible to modify org-export-document-properties OTG

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>>
>>        (:subject "SUBJECT" nil nil parsed)
>>
>> `parsed' behavior implies `space' anyway, since we're talking about
>> secondary strings.
>
> Is that always the case?  I guess..

There are only two ways to look at it: either it can only contain
objects, or it can contain paragraphs. The latter might make sense for,
e.g., DESCRIPTION.

In this case, we need 2 symbols for that, e.g., `parse-objects' and
`parse-elements'.

>> `org-element-map' can find objects in captions, with an optional
>> argument.
>
> If turns out to be important, perhaps it would also be possible to map
> keyword objects with an non-default argument.

This is different. Captions are already in the parse tree. Keyword
objects are added mid-way. I'd rather keep keywords as is. If you want
to map over objects in, e.g., SUBJECT, you need to explicitly call
`org-element-map' on (plist-get info :subject).

Regards,