Including setupfile settings during subtree export (new exporter)

Including setupfile settings during subtree export (new exporter)

[John Hendy]

In the past, exporting a subtree seemed to pull options from my
#+setupfile line.

I've updated the line to the proper new syntax (#+include:
"/path/to/setupfile.org"), but subtree export doesn't seem to be using
the options set there (using =C-c C-e C-s l p= for LaTeX/PDF export).

I tried using =#+include: "file"= as well as =#+setupfile: file=
inside the subtree properties drawer without success.

If I mark the same subtree with :export: tag (no other trees are
marked), it works properly and uses my setupfile options.

Any suggestions? If this was an oversight, my vote would be that a
buffer-set setupfile would apply to subtree exports unless overridden
by a property-drawer setting (even though I don't currently know that
the property draw setting is for a setupfile).


Thanks,
John

Re: Including setupfile settings during subtree export (new exporter)

[Nicolas Goaziou]

Hello,

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

> In the past, exporting a subtree seemed to pull options from my
> #+setupfile line.

And it should still do.

> I've updated the line to the proper new syntax (#+include:
> "/path/to/setupfile.org"), but subtree export doesn't seem to be using
> the options set there (using =C-c C-e C-s l p= for LaTeX/PDF export).
>
> I tried using =#+include: "file"= as well as =#+setupfile: file=
> inside the subtree properties drawer without success.

Inside the property drawer? A property drawer can only contain node
properties, e.g.:

  :PROP: value

> If I mark the same subtree with :export: tag (no other trees are
> marked), it works properly and uses my setupfile options.
>
> Any suggestions? If this was an oversight, my vote would be that a
> buffer-set setupfile would apply to subtree exports unless overridden
> by a property-drawer setting (even though I don't currently know that
> the property draw setting is for a setupfile).

I think I need an ECM to understand the problem you're describing.


Regards,

-- 
Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[John Hendy]

On Fri, Mar 22, 2013 at 10:27 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Hello,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> In the past, exporting a subtree seemed to pull options from my
>> #+setupfile line.
>
> And it should still do.
>
>> I've updated the line to the proper new syntax (#+include:
>> "/path/to/setupfile.org"), but subtree export doesn't seem to be using
>> the options set there (using =C-c C-e C-s l p= for LaTeX/PDF export).
>>
>> I tried using =#+include: "file"= as well as =#+setupfile: file=
>> inside the subtree properties drawer without success.
>
> Inside the property drawer? A property drawer can only contain node
> properties, e.g.:
>
>   :PROP: value

Yeah, I didn't really know... was just going by this recent post which
featured that, so since it was fresh in my mind, I tried:
- http://www.mail-archive.com/emacs-orgmode@gnu.org/msg68321.html

>
>> If I mark the same subtree with :export: tag (no other trees are
>> marked), it works properly and uses my setupfile options.
>>
>> Any suggestions? If this was an oversight, my vote would be that a
>> buffer-set setupfile would apply to subtree exports unless overridden
>> by a property-drawer setting (even though I don't currently know that
>> the property draw setting is for a setupfile).
>
> I think I need an ECM to understand the problem you're describing.

Sure. Try this:

#+begin_src setupfile

#+AUTHOR:    John Henderson
#+latex_header: \usepackage[hmargin=2.5cm,vmargin=2.5cm]{geometry}
#+latex_header: \usepackage{mathpazo}

#+end_src


#+begin_src test-setupfile.org

#+include: "/path/to/setupfile"

* Heading 1

Some text in the form of a longer paragraph to test the margin
settings using the
=geometry= package. Some text in the form of a longer paragraph to
test the margin settings using the
=geometry= package. Some text in the form of a longer paragraph to
test the margin settings using the
=geometry= package.

List:

- item 1
- item 2
- item 3

#+end_src


#+begin_src minimal-config

;; set load paths
;; set load dirs and global config options
(add-to-list 'load-path "~/.elisp/org.git/contrib/lisp/")
(add-to-list 'load-path "~/.elisp/org.git/lisp/")

(require 'ox-latex)

#+end_src


Procedure:
- emacs -Q
- M-x load-file minimal-config
- C-x C-f setupfile-test.org
- Now compare the results of =C-c C-e l p= vs. (while on * Heading 1)
=C-c C-e C-s l p=.


Best regards,
John

>
>
> Regards,
>
> --
> Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[Nicolas Goaziou]

Hello,

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

> #+begin_src setupfile
>
> #+AUTHOR:    John Henderson
> #+latex_header: \usepackage[hmargin=2.5cm,vmargin=2.5cm]{geometry}
> #+latex_header: \usepackage{mathpazo}
>
> #+end_src
> #+begin_src test-setupfile.org
>
> #+include: "/path/to/setupfile"

Use "#+setupfile:" instead of "#+include:"

There's a major difference between "setupfile" and "include" keyword
here: the former applies to the whole buffer, whereas the latter is only
expanded in the part being exported.

In your case, the INCLUDE keyword doesn't belong to the subtree, so it
is never expanded.


Regards,

-- 
Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[John Hendy]

On Sat, Mar 23, 2013 at 3:24 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Hello,
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> #+begin_src setupfile
>>
>> #+AUTHOR:    John Henderson
>> #+latex_header: \usepackage[hmargin=2.5cm,vmargin=2.5cm]{geometry}
>> #+latex_header: \usepackage{mathpazo}
>>
>> #+end_src
>> #+begin_src test-setupfile.org
>>
>> #+include: "/path/to/setupfile"
>
> Use "#+setupfile:" instead of "#+include:"
>
> There's a major difference between "setupfile" and "include" keyword
> here: the former applies to the whole buffer, whereas the latter is only
> expanded in the part being exported.

Huh, well that's interesting. I /had/ #+setupfile, and only changed
due to following the upgrade guide
(http://orgmode.org/worg/org-8.0.html)

#+begin_quote

Other important changes

#+STYLE: -> #+HTML_HEAD:
#+SETUPFILE: myfile -> =#+INCLUDE: "myfile"=

#+end_quote

That reads, to me, as though the syntax changed. Perhaps the "->"
didn't mean what I took it to mean?

>
> In your case, the INCLUDE keyword doesn't belong to the subtree, so it
> is never expanded.

Thanks for the clarification. For me (since I'm not an elisper), the
mechanics aren't too important. All I really want is the correct way
to apply org-mode settings to a buffer or a subtree by default, unless
I specify otherwise inside a subtree to override the buffer-wide
setupfile.

Based on the above, should that line be removed from the Worg update
guide? If so, I can do that. If someone has a better understanding of
why it was included (perhaps #+include is a new feature and should be
better explained), then maybe they should do it.

I'll change back to #+setupfile!


Thanks for the assistance,
John



>
> Regards,
>
> --
> Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[Nicolas Goaziou]

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

> Thanks for the clarification. For me (since I'm not an elisper), the
> mechanics aren't too important. All I really want is the correct way
> to apply org-mode settings to a buffer or a subtree by default, unless
> I specify otherwise inside a subtree to override the buffer-wide
> setupfile.

At the moment, there's no way to override a #+setupfile: keyword
locally.

> Based on the above, should that line be removed from the Worg update
> guide? If so, I can do that.

I think so.

> I'll change back to #+setupfile!

Note that LaTeX packages added through SETUPFILE can also be found
during latex fragments previewing, which isn't true for INCLUDE
keywords.


Regards,

-- 
Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[John Hendy]

On Sat, Mar 23, 2013 at 3:49 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> John Hendy <jw.hendy@gmail.com> writes:
>
>> Thanks for the clarification. For me (since I'm not an elisper), the
>> mechanics aren't too important. All I really want is the correct way
>> to apply org-mode settings to a buffer or a subtree by default, unless
>> I specify otherwise inside a subtree to override the buffer-wide
>> setupfile.
>
> At the moment, there's no way to override a #+setupfile: keyword
> locally.

I guess I don't understand the purpose of #+include, then. It seems we
have only two options:

1) #+setupfile: Will apply to entire buffer as well as subtree
exports. Cannot be overridden in subtrees.

2) #+include: Applies to entire buffer export only; does nothing for
subtree exports.

What's the preferred way to customize subtrees? Just add #+latex: or
#+latex_header: options inside the subtree? Going by the LaTeX export
guide (http://orgmode.org/worg/org-tutorials/org-latex-export.html), I
don't see recommendations for this. As a use case, perhaps I have a
subtree with beamer-compatible markup (each subtree will fit on a
slide), but that I might also include in the whole buffer, or perhaps
a different css file for the whole buffer vs. the subtree.

Can this be accomplished?

>
>> Based on the above, should that line be removed from the Worg update
>> guide? If so, I can do that.
>
> I think so.
>

Will do.

>> I'll change back to #+setupfile!
>
> Note that LaTeX packages added through SETUPFILE can also be found
> during latex fragments previewing, which isn't true for INCLUDE
> keywords.
>
>

Thanks!
John

> Regards,
>
> --
> Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[Nicolas Goaziou]

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

>> At the moment, there's no way to override a #+setupfile: keyword
>> locally.
>
> I guess I don't understand the purpose of #+include, then. It seems we
> have only two options:
>
> 1) #+setupfile: Will apply to entire buffer as well as subtree
> exports. Cannot be overridden in subtrees.
>
> 2) #+include: Applies to entire buffer export only; does nothing for
> subtree exports.

#+INCLUDE: "file" replaces keyword with "file" contents. During subtree
export, replacement will happen if the keyword is located within the
subtree being exported.

#+SETUPFILE: "file" just reads Org keywords within "file". All Org
keywords are global, this one makes no exception.

In a nutshell, SETUPFILE should be used for Org set-up. INCLUDE is very
general and can be used to build complex documents. The fact that it
also copies Org keywords from "file" in the current buffer is merely
a side-effect.

> What's the preferred way to customize subtrees? Just add #+latex: or
> #+latex_header: options inside the subtree?

#+LATEX_HEADER: is also global. Use :EXPORT_LATEX_HEADER: in property
drawer instead.

> Going by the LaTeX export guide
> (http://orgmode.org/worg/org-tutorials/org-latex-export.html), I don't
> see recommendations for this. As a use case, perhaps I have a subtree
> with beamer-compatible markup (each subtree will fit on a slide), but
> that I might also include in the whole buffer, or perhaps a different
> css file for the whole buffer vs. the subtree.
>
> Can this be accomplished?

Off the top of my head, I think there's no direct way to do it. Though,
you can define a property :MY_SETUP: setupfile in the subtree and,
within `org-export-before-processing-hook', call a function:

  - commenting every fSETUPFILE keyword
  - adding #+SETUPFILE: setupfile at the beginning of the buffer.

It involves some (simple) elisp, though.

>>> Based on the above, should that line be removed from the Worg update
>>> guide? If so, I can do that.
>>
>> I think so.
>
> Will do.

Thank you.


Regards,

-- 
Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[John Hendy]

On Sat, Mar 23, 2013 at 5:08 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> John Hendy <jw.hendy@gmail.com> writes:
>
>>> At the moment, there's no way to override a #+setupfile: keyword
>>> locally.
>>
>> I guess I don't understand the purpose of #+include, then. It seems we
>> have only two options:
>>
>> 1) #+setupfile: Will apply to entire buffer as well as subtree
>> exports. Cannot be overridden in subtrees.
>>
>> 2) #+include: Applies to entire buffer export only; does nothing for
>> subtree exports.
>
> #+INCLUDE: "file" replaces keyword with "file" contents. During subtree
> export, replacement will happen if the keyword is located within the
> subtree being exported.
>
> #+SETUPFILE: "file" just reads Org keywords within "file". All Org
> keywords are global, this one makes no exception.
>

Got it... I think :) Perhaps the Worg page should clarify this, as it
does, then, seem like #+include is the best practice for LaTeX options
and #+setupfile is just supposed to be for TODO settings? I say this
as my googling for "Org keywords org-mode" yields this:
- http://orgmode.org/manual/Per_002dfile-keywords.html

Is that the meaning of "Org keywords" (just TODO keyword/work flow
settings)? Or would you also include #+options in that group?

> In a nutshell, SETUPFILE should be used for Org set-up. INCLUDE is very
> general and can be used to build complex documents. The fact that it
> also copies Org keywords from "file" in the current buffer is merely
> a side-effect.
>
>> What's the preferred way to customize subtrees? Just add #+latex: or
>> #+latex_header: options inside the subtree?
>
> #+LATEX_HEADER: is also global. Use :EXPORT_LATEX_HEADER: in property
> drawer instead.
>

Good to know. I was unaware of that. Is there a list of these? The
only one I've run across is the new Beamer export Worg page:
- http://orgmode.org/worg/exporters/beamer/ox-beamer.html#config

That's a great table and it would be great to have that for all
properties. Or perhaps this page could link to that comprehensive list
if it exists, or let the user know how to find it:
- http://orgmode.org/manual/Special-properties.html#Special-properties

>> Going by the LaTeX export guide
>> (http://orgmode.org/worg/org-tutorials/org-latex-export.html), I don't
>> see recommendations for this. As a use case, perhaps I have a subtree
>> with beamer-compatible markup (each subtree will fit on a slide), but
>> that I might also include in the whole buffer, or perhaps a different
>> css file for the whole buffer vs. the subtree.
>>
>> Can this be accomplished?
>
> Off the top of my head, I think there's no direct way to do it. Though,
> you can define a property :MY_SETUP: setupfile in the subtree and,
> within `org-export-before-processing-hook', call a function:
>
>   - commenting every fSETUPFILE keyword
>   - adding #+SETUPFILE: setupfile at the beginning of the buffer.
>
> It involves some (simple) elisp, though.
>

I'll consider that. My setups aren't typically so complicated to
probably require something like this. Out of curiosity, would
#+include in the header of the file be overridden by #+include in the
subtree? If not, it could be as simple as having a temporary include
file that I'd modify prior to subtree export and then just comment out
the main buffer #+include prior to exporting.

>>>> Based on the above, should that line be removed from the Worg update
>>>> guide? If so, I can do that.
>>>
>>> I think so.
>>
>> Will do.
>
> Thank you.
>
>
> Regards,
>
> --
> Nicolas Goaziou


Thanks again for the clarification. I do hope I can repay those doing
work on actual code (where I lack the abilities) by getting some of
these gems out of the mailing list and into Worg for the community.


Best regards,
John

Re: Including setupfile settings during subtree export (new exporter)

[Nicolas Goaziou]

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

>> #+INCLUDE: "file" replaces keyword with "file" contents. During subtree
>> export, replacement will happen if the keyword is located within the
>> subtree being exported.
>>
>> #+SETUPFILE: "file" just reads Org keywords within "file". All Org
>> keywords are global, this one makes no exception.
>>
>
> Got it... I think :) Perhaps the Worg page should clarify this, as it
> does, then, seem like #+include is the best practice for LaTeX options
> and #+setupfile is just supposed to be for TODO settings? I say this
> as my googling for "Org keywords org-mode" yields this:
> - http://orgmode.org/manual/Per_002dfile-keywords.html
>
> Is that the meaning of "Org keywords" (just TODO keyword/work flow
> settings)? Or would you also include #+options in that group?

Org keywords are any keyword you can think of, excepted INCLUDE
keywords. Thus, it makes sense to have an OPTIONS keyword within
a SETUPFILE.

>> In a nutshell, SETUPFILE should be used for Org set-up. INCLUDE is very
>> general and can be used to build complex documents. The fact that it
>> also copies Org keywords from "file" in the current buffer is merely
>> a side-effect.
>>
>>> What's the preferred way to customize subtrees? Just add #+latex: or
>>> #+latex_header: options inside the subtree?
>>
>> #+LATEX_HEADER: is also global. Use :EXPORT_LATEX_HEADER: in property
>> drawer instead.
>>
>
> Good to know. I was unaware of that. Is there a list of these?

For each keyword related to export (e.g. AUTHOR), there's
an :EXPORT_AUTHOR: property for subtree export. It is also true for
back-end specific keywords (like Beamer's).

> Out of curiosity, would #+include in the header of the file be
> overridden by #+include in the subtree?

Not at all. Each include will be replaced by the contents of the file it
points to. You can have as many INCLUDE keywords as you want in a file.

Though, if first INCLUDE keyword adds an Org keyword (e.g. AUTHOR) and
the second one also inserts AUTHOR keyword, the last AUTHOR keyword in
the buffer will have precedence over the first one.

The same holds for SETUPFILE keywords.

> If not, it could be as simple as having a temporary include file that
> I'd modify prior to subtree export and then just comment out the main
> buffer #+include prior to exporting.

That would probably work. But, again, I highly suggest to use SETUPFILE
for setting up the export (among other things). Use INCLUDE when you
need to add contents, not only Org meta-data.


Regards,

-- 
Nicolas Goaziou

Re: Including setupfile settings during subtree export (new exporter)

[Mike McLean]

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

On Sat, Mar 23, 2013 at 4:37 PM, John Hendy <jw.hendy@gmail.com> wrote:

>
> Huh, well that's interesting. I /had/ #+setupfile, and only changed
> due to following the upgrade guide
> (http://orgmode.org/worg/org-8.0.html)
>

FWIW, I had read the same thing and made the same #+SETUPFILE → #+INCLUDE
change in my setup and noticed the same problem. I don't have “send” rights
to mailing lists at work, so had an Org mode task to write this up and post
it this weekend. You beat me to it :)

Thanks for pointing it out and thank you Nicolas for the following
discussion about what to use where.

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