Limit subtree to a specific export backend

Limit subtree to a specific export backend

[Sebastian Wiesner]

Hello,

can I limit a subtree to be exported with specific backends only?
I.e. only to HTML, but not Texinfo or LaTeX?

Background:  I am trying to simplify the documentation of one of my
projects, and combine the website and the user manual into a single
document.  Naturally, there is some content on the website that should
not appear in the manual and vice versa.

So long,
Sebastian Wiesner

Re: Limit subtree to a specific export backend

[Sebastien Vauban]

Sebastian Wiesner wrote:
> can I limit a subtree to be exported with specific backends only?
> I.e. only to HTML, but not Texinfo or LaTeX?
>
> Background:  I am trying to simplify the documentation of one of my
> projects, and combine the website and the user manual into a single
> document.  Naturally, there is some content on the website that should
> not appear in the manual and vice versa.

A partly manual solution would be to use tags for which sections to export in
which backend, make a sparse tree with the backend you're interested to export,
and export what's visible?

If working, such a thing could be automated in a ELisp block.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Limit subtree to a specific export backend

[Sebastian Wiesner]

2013/9/30 Sebastien Vauban <sva-news@mygooglest.com>:
> A partly manual solution would be to use tags for which sections to export in
> which backend, make a sparse tree with the backend you're interested to export,
> and export what's visible?

I am by far not an Org mode expert, and have never used sparse trees.
Would you mind to point me to the appropriate manual section, or give
me some details on how to create a sparse tree matching a specific tag
only?

Re: Limit subtree to a specific export backend

[Sebastien Vauban]

Hi Sebastian,

Sebastian Wiesner wrote:
> 2013/9/30 Sebastien Vauban <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>:
>> A partly manual solution would be to use tags for which sections to export
>> in which backend, make a sparse tree with the backend you're interested to
>> export, and export what's visible?
>
> I am by far not an Org mode expert, and have never used sparse trees. Would
> you mind to point me to the appropriate manual section, or give me some
> details on how to create a sparse tree matching a specific tag only?

See section 2.6 Sparse trees:

  ╭────
  │ An important feature of Org mode is the ability to construct _sparse
  │ trees_ for selected information in an outline tree, so that the entire
  │ document is folded as much as possible, but the selected information is
  │ made visible along with the headline structure above it(1).  Just try
  │ it out and you will see immediately how it works.
  │
  │    Org mode contains several commands creating such trees, all these
  │ commands can be accessed through a dispatcher:
  │
  │ `C-c /'     (`org-sparse-tree')
  │      This prompts for an extra key to select a sparse-tree creating
  │      command.
  ╰────

It will help to "expand" all entries which contain a certain keyword (see `C-c
/ /') and "collapse" all others. Though, it won't help for tagged entries:
their contents won't be opened automatically by doing `C-c / m' (match for a
tag).

Anyway, `C-c /' is a very interesting (set of) commands to know!

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Limit subtree to a specific export backend

[Rasmus]

Hi Sebastian,

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> can I limit a subtree to be exported with specific backends only?
> I.e. only to HTML, but not Texinfo or LaTeX?
>
> Background:  I am trying to simplify the documentation of one of my
> projects, and combine the website and the user manual into a single
> document.  Naturally, there is some content on the website that should
> not appear in the manual and vice versa.

As Sebastien suggests, if you can identify export status depending on
tags you can do it with a filter.

Here's an example that's perhaps a bit too verbose and not thoroughly
tested:

#+BEGIN_SRC Org
#+TITLE: Conditional export
#+options: tags:nil
* Common intro
  txt
** Pdf heading                                                        :latex:
   the math is really pretty!
** HTML heading                                                        :html:
   the text features hyperlinks!
** More common notes
   Intro over
   
* Code                                                             :noexport:
#+begin_src emacs-lisp
  (defun rasmus/conditional-export (settings backend)
    "Change SETTINGS to include dynamically set export-tags.
  
    Enable the use of BACKEND as EXPORT_TAGS.  A derived backend is
    treated as its parent."
    (let ((backends (remove-duplicates
                     (mapcar (lambda (x)
                               (or (org-export-backend-parent x)
                                   (org-export-backend-name x)))
                             org-export--registered-backends)))
          ;; for treating derived backend and parent backends differently: 
          ;; (backend-or-parent backend)
          (backend-or-parent (dolist (b org-export--registered-backends return)
                               (when  (eq (org-export-backend-name b) backend)
                                 (return (or (org-export-backend-parent b)
                                             (org-export-backend-name b)))))))
      (plist-put 
       settings :exclude-tags 
       (append (plist-get settings :exclude-tags)
               (mapcar 'symbol-name
                       (remove backend-or-parent backends))))))

  (add-to-list 'org-export-filter-options-functions 'rasmus/conditional-export)
#+end_src
#+END_SRC


-- 
Enough with the bla bla!

Re: Limit subtree to a specific export backend

[Sebastian Wiesner]

2013/9/30 Rasmus <rasmus@gmx.us>:
> Hi Sebastian,
>
> Sebastian Wiesner <lunaryorn@gmail.com> writes:
>
>> can I limit a subtree to be exported with specific backends only?
>> I.e. only to HTML, but not Texinfo or LaTeX?
>>
>> Background:  I am trying to simplify the documentation of one of my
>> projects, and combine the website and the user manual into a single
>> document.  Naturally, there is some content on the website that should
>> not appear in the manual and vice versa.
>
> As Sebastien suggests, if you can identify export status depending on
> tags you can do it with a filter.

Great, I think I will go by this way…

I presume, I can set "org-export-filter-options-functions" as a
directory-local variable, so that this kind of export restrictions
only applies to Org mode documents in the specific project.

> Here's an example that's perhaps a bit too verbose and not thoroughly
> tested:
>
> #+BEGIN_SRC Org
> #+TITLE: Conditional export
> #+options: tags:nil
> * Common intro
>   txt
> ** Pdf heading                                                        :latex:
>    the math is really pretty!
> ** HTML heading                                                        :html:
>    the text features hyperlinks!
> ** More common notes
>    Intro over
>
> * Code                                                             :noexport:
> #+begin_src emacs-lisp
>   (defun rasmus/conditional-export (settings backend)
>     "Change SETTINGS to include dynamically set export-tags.
>
>     Enable the use of BACKEND as EXPORT_TAGS.  A derived backend is
>     treated as its parent."
>     (let ((backends (remove-duplicates
>                      (mapcar (lambda (x)
>                                (or (org-export-backend-parent x)
>                                    (org-export-backend-name x)))
>                              org-export--registered-backends)))
>           ;; for treating derived backend and parent backends differently:
>           ;; (backend-or-parent backend)
>           (backend-or-parent (dolist (b org-export--registered-backends return)
>                                (when  (eq (org-export-backend-name b) backend)
>                                  (return (or (org-export-backend-parent b)
>                                              (org-export-backend-name b)))))))
>       (plist-put
>        settings :exclude-tags
>        (append (plist-get settings :exclude-tags)
>                (mapcar 'symbol-name
>                        (remove backend-or-parent backends))))))
>
>   (add-to-list 'org-export-filter-options-functions 'rasmus/conditional-export)
> #+end_src
> #+END_SRC

Do I understand correctly, that this code adds all *other* backends to
the "exclude-tags" setting, instead of adding the current one to
"select-tags"?  Is there a specific reason to do this?

Just adding "backend" to "select-tags" seems simpler to me, and I
wonder whether "exclude-tags" even behaves correctly for headlines
with more than one tag.  As far as I understand the Org manual, it
would exclude headlines tagged as ":html:latex:" when exporting to
"html", because "latex" is added as exclude-tag, preventing the
headline from being exported.

Re: Limit subtree to a specific export backend

[Rasmus]

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> I presume, I can set "org-export-filter-options-functions" as a
> directory-local variable, so that this kind of export restrictions
> only applies to Org mode documents in the specific project.

Probably.  There was some discussions on it lately.  Check the
archive.

>> Here's an example that's perhaps a bit too verbose and not thoroughly
>> tested:
>>
>> #+BEGIN_SRC Org
>> #+TITLE: Conditional export
>> #+options: tags:nil
>> * Common intro
>>   txt
>> ** Pdf heading                                                        :latex:
>>    the math is really pretty!
>> ** HTML heading                                                        :html:
>>    the text features hyperlinks!
>> ** More common notes
>>    Intro over
>>
>> * Code                                                             :noexport:
>> #+begin_src emacs-lisp
>>   (defun rasmus/conditional-export (settings backend)
>>     "Change SETTINGS to include dynamically set export-tags.
>>
>>     Enable the use of BACKEND as EXPORT_TAGS.  A derived backend is
>>     treated as its parent."
>>     (let ((backends (remove-duplicates
>>                      (mapcar (lambda (x)
>>                                (or (org-export-backend-parent x)
>>                                    (org-export-backend-name x)))
>>                              org-export--registered-backends)))
>>           ;; for treating derived backend and parent backends differently:
>>           ;; (backend-or-parent backend)
>>           (backend-or-parent (dolist (b org-export--registered-backends return)
>>                                (when  (eq (org-export-backend-name b) backend)
>>                                  (return (or (org-export-backend-parent b)
>>                                              (org-export-backend-name b)))))))
>>       (plist-put
>>        settings :exclude-tags
>>        (append (plist-get settings :exclude-tags)
>>                (mapcar 'symbol-name
>>                        (remove backend-or-parent backends))))))
>>
>>   (add-to-list 'org-export-filter-options-functions 'rasmus/conditional-export)
>> #+end_src
>> #+END_SRC
>
> Do I understand correctly, that this code adds all *other* backends to
> the "exclude-tags" setting, instead of adding the current one to
> "select-tags"?  Is there a specific reason to do this?

Let me know if it doesn't work as desired and share your improvements.
I didn't do proper testing as I don't fully appreciate all corner
cases of the use case.


On select tag, you can use it if you like how this document works 

#+SELECT_TAGS: latex
* common intro
  test 
** html intro                                                          :html:
   html
** latex                                                              :latex:
   latex
* common next section 
  Next section

> Just adding "backend" to "select-tags" seems simpler to me, and I
> wonder whether "exclude-tags" even behaves correctly for headlines
> with more than one tag.  As far as I understand the Org manual, it
> would exclude headlines tagged as ":html:latex:" when exporting to
> "html", because "latex" is added as exclude-tag, preventing the
> headline from being exported.

You should be able to test this in a normal org document.

–Rasmus

-- 
C is for Cookie