[PATCH] Improve usage of odt content templates

[PATCH] Improve usage of odt content templates

[Christian Kellermann]

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

Hi all,

I have been using org-mode's odt exporter heavily for the last days
with the attached patches. These scratch an itch I have and I submit
them to this list in the hope of being useful to others.

Rationale:

I am using the odt exporter to fill in a project description document
at work with has strict specified layout and template. Fortunately
just using an existing empty document and org-mode's content template
setting is sufficient for my needs to create the OO documents without
having to touch OpenOffice. However the current master code misses
two things I need:

* Possibility to override the globally defined
org-odt-content-template-file variable in the document

* Avoid inserting the document title as the first thing in the
document contents, as there already is a title set in a title page
in the template. As org-mode already sets the title data tag this
can be used in the template to generate the correct title. However
inserting the title as text is not desireable in that scenario.

I have attached patches that address these two issues. The latter
adds yet another option to the exporter mode to suppress title
insertion.

I offer these patches as the base of a discussion as I am not sure
whether these small changes fit the overall "org-mode" way. Or maybe
there already is an easier way to achieve what I want, I don't know.

As these are my first org-mode patches I hope I have read the
guidelines for commit messages correctly. I am grateful for any
comments or advise you may have.

Kind regards,

Christian

-- 
May you be peaceful, may you live in safety, may you be free from
suffering, and may you live with ease.

[-- Attachment #2: 0001-ox-odt-Expose-content-template-file-setting.patch --]
[-- Type: text/plain, Size: 1490 bytes --]

From a6a84ae372ce1d755292da7559afde1c9bfbfc7d Mon Sep 17 00:00:00 2001
From: Christian Kellermann <ckeen@pestilenz.org>
Date: Mon, 19 May 2014 12:11:28 +0200
Subject: [PATCH 1/2] ox-odt: Expose content template file setting

* ox-odt.el (odt): Add ODT_CONTENT_TEMPLATE_FILE option.

org-odt-content-template-file is not changeable in the org
buffer.

* ox-odt.el (org-odt-template): Prefer local content template

Prefer the locally set #+ODT_CONTENT_TEMPLATE_FILE over the global
org-odt-content-template-file variable.

TINYCHANGE
---
 lisp/ox-odt.el | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index 4d2f257..1d4e796 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -97,6 +97,7 @@
 		(org-open-file (org-odt-export-to-odt nil s v) 'system))))))
   :options-alist
   '((:odt-styles-file "ODT_STYLES_FILE" nil nil t)
+    (:odt-content-template-file "ODT_CONTENT_TEMPLATE_FILE" nil nil t)
     ;; Redefine regular option.
     (:with-latex nil "tex" org-odt-with-latex)))
 
@@ -1450,7 +1451,8 @@ original parsed data.  INFO is a plist holding export options."
 	    '("%Y-%M-%d %a" . "%Y-%M-%d %a %H:%M"))))
     (with-temp-buffer
       (insert-file-contents
-       (or org-odt-content-template-file
+       (or (plist-get info :odt-content-template-file)
+           org-odt-content-template-file
 	   (expand-file-name "OrgOdtContentTemplate.xml"
 			     org-odt-styles-dir)))
       ;; Write automatic styles.
-- 
1.9.2


[-- Attachment #3: 0002-ox-odt-Optionally-suppress-title-insertion.patch --]
[-- Type: text/plain, Size: 1652 bytes --]

From e1e171a12b0ad0d29881a27688d578fba1ac4a75 Mon Sep 17 00:00:00 2001
From: Christian Kellermann <ckeen@pestilenz.org>
Date: Mon, 19 May 2014 12:14:50 +0200
Subject: [PATCH 2/2] ox-odt: Optionally suppress title insertion

* ox-odt.el (odt): Add ODT_INSERT_TITLE to option list.

This allows the user to suppress the insertion of the document title
in the openoffice document.

* ox-odt.el (org-odt-template): optionally skip title insertion.

If ODT_INSERT_TITLE is set to a false value, skip title insertion.  As
the odt exporter also sets the title metadata tag, this allows the
user to use the title elsewhere, for example in a fancier title page.

TINYCHANGE
---
 lisp/ox-odt.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index 1d4e796..6268e51 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -97,6 +97,7 @@
 		(org-open-file (org-odt-export-to-odt nil s v) 'system))))))
   :options-alist
   '((:odt-styles-file "ODT_STYLES_FILE" nil nil t)
+    (:odt-insert-title "ODT_INSERT_TITLE" nil nil t)
     (:odt-content-template-file "ODT_CONTENT_TEMPLATE_FILE" nil nil t)
     ;; Redefine regular option.
     (:with-latex nil "tex" org-odt-with-latex)))
@@ -1504,7 +1505,7 @@ original parsed data.  INFO is a plist holding export options."
 	      (email (and (plist-get info :with-email) email)))
 	 (concat
 	  ;; Title.
-	  (when (org-string-nw-p title)
+	  (when (and (plist-get info :odt-insert-title) (org-string-nw-p title))
 	    (concat
 	     (format "\n<text:p text:style-name=\"%s\">%s</text:p>"
 		     "OrgTitle" (format "\n<text:title>%s</text:title>" title))
-- 
1.9.2

Re: [PATCH] Improve usage of odt content templates

[Nicolas Goaziou]

Hello,

Christian Kellermann <ckeen@pestilenz.org> writes:

> I have been using org-mode's odt exporter heavily for the last days
> with the attached patches. These scratch an itch I have and I submit
> them to this list in the hope of being useful to others.

Thank you for your patches.

> * Possibility to override the globally defined
> org-odt-content-template-file variable in the document

It is already possible to override the varible file-wise with:

  #+BIND: org-odt-content-template-file "somefile"

I'm not sure it is worth adding another keyword. OTOH, there's also
ODT_STYLES_FILE and they are quite symmetric, so one could expect to be
able to set both. But then, `org-odt-content-template-file''s docstring
needs to be updated, and the feature should be documented in the manual.

Also, it should be

  (:odt-content-template-file "ODT_CONTENT_TEMPLATE_FILE" nil org-odt-content-template-file t)

> * Avoid inserting the document title as the first thing in the
> document contents, as there already is a title set in a title page
> in the template. As org-mode already sets the title data tag this
> can be used in the template to generate the correct title. However
> inserting the title as text is not desireable in that scenario.

I think this is a more general issue: should we implement an

  #+OPTIONS: title:nil

feature? I think it makes some sense since we already have date:nil and
author:nil. In any case, keywords are not meant to be used for booleans.
This should be an OPTIONS item.


Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Improve usage of odt content templates

[Rasmus]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> I think this is a more general issue: should we implement an
>
>   #+OPTIONS: title:nil
>
> feature? I think it makes some sense since we already have date:nil and
> author:nil. In any case, keywords are not meant to be used for booleans.
> This should be an OPTIONS item.

That's nicer than a blank title ("#+TITLE: ").

I prefer the earlier ox-behavior where no title would be printed if
title was missing, rather than using the file-name.  The file name is
never interesting in my work flow.  If introducing a title option it
would be nice if an option is "print title if present" so that this
can be set by default.

—Rasmus

--
El Rey ha muerto. ¡Larga vida al Rey!

Re: [PATCH] Improve usage of odt content templates

[Christian Kellermann]

Rasmus <rasmus@gmx.us> writes:
> That's nicer than a blank title ("#+TITLE: ").
>
> I prefer the earlier ox-behavior where no title would be printed if
> title was missing, rather than using the file-name.  The file name is
> never interesting in my work flow.  If introducing a title option it
> would be nice if an option is "print title if present" so that this
> can be set by default.

I can second this, the filename never looks nice when doing an export.

Kind regards,

Christian

Re: [PATCH] Improve usage of odt content templates

[Eric Abrahamsen]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <n.goaziou@gmail.com> writes:
>
>> I think this is a more general issue: should we implement an
>>
>>   #+OPTIONS: title:nil
>>
>> feature? I think it makes some sense since we already have date:nil and
>> author:nil. In any case, keywords are not meant to be used for booleans.
>> This should be an OPTIONS item.
>
> That's nicer than a blank title ("#+TITLE: ").
>
> I prefer the earlier ox-behavior where no title would be printed if
> title was missing, rather than using the file-name.  The file name is
> never interesting in my work flow.  If introducing a title option it
> would be nice if an option is "print title if present" so that this
> can be set by default.

+1

I'm forever deleting the title because I forget to insert an empty
string #+TITLE option. If there was an `org-export-with-title' option
I'd set it to nil and be happy 80% of the time.

E

Re: [PATCH] Improve usage of odt content templates

[Detlef Steuer]

Am Tue, 20 May 2014 16:37:45 +0800
schrieb Eric Abrahamsen <eric@ericabrahamsen.net>:

> Rasmus <rasmus@gmx.us> writes:
> 
> > Nicolas Goaziou <n.goaziou@gmail.com> writes:
> >
> >> I think this is a more general issue: should we implement an
> >>
> >>   #+OPTIONS: title:nil
> >>
> >> feature? I think it makes some sense since we already have
> >> date:nil and author:nil. In any case, keywords are not meant to be
> >> used for booleans. This should be an OPTIONS item.
> >
> > That's nicer than a blank title ("#+TITLE: ").
> >
> > I prefer the earlier ox-behavior where no title would be printed if
> > title was missing, rather than using the file-name.  The file name
> > is never interesting in my work flow.  If introducing a title
> > option it would be nice if an option is "print title if present" so
> > that this can be set by default.
> 
> +1

+2

Have fought with "set filename as title" before, would like and use 
such an option.

Detlef

> 
> I'm forever deleting the title because I forget to insert an empty
> string #+TITLE option. If there was an `org-export-with-title' option
> I'd set it to nil and be happy 80% of the time.
> 
> E
> 
> 
> 



-- 
Detlef Steuer

---

Dr. Detlef Steuer
Helmut-Schmidt-Universität
Fakultät WiSo
Holstenhofweg 85
22043 Hamburg

Tel:  040/6541-2819
mail: steuer@hsu-hh.de

Re: [PATCH] Improve usage of odt content templates

[Christian Kellermann]

Hi!

* Nicolas Goaziou <n.goaziou@gmail.com> [140519 18:16]:
> It is already possible to override the varible file-wise with:
> 
>   #+BIND: org-odt-content-template-file "somefile"
> 
> I'm not sure it is worth adding another keyword. OTOH, there's also
> ODT_STYLES_FILE and they are quite symmetric, so one could expect to be
> able to set both. But then, `org-odt-content-template-file''s docstring
> needs to be updated, and the feature should be documented in the manual.

I first thought about using ODT_STYLES_FILE in the list form and
pick out the content.xml from there, but maybe that's a bit unexpected
as one might use a different content than from the style.

But the control flow as it is now would need to be refactored to
make this a nice patch too.

I shall resend this patch with proper docstrings and manual patches
if you like.

> 
> Also, it should be
> 
>   (:odt-content-template-file "ODT_CONTENT_TEMPLATE_FILE" nil org-odt-content-template-file t)

Ah of course.

> 
> > * Avoid inserting the document title as the first thing in the
> > document contents, as there already is a title set in a title page
> > in the template. As org-mode already sets the title data tag this
> > can be used in the template to generate the correct title. However
> > inserting the title as text is not desireable in that scenario.
> 
> I think this is a more general issue: should we implement an
> 
>   #+OPTIONS: title:nil
> 
> feature? I think it makes some sense since we already have date:nil and
> author:nil. In any case, keywords are not meant to be used for booleans.
> This should be an OPTIONS item.

I don't feel qualified to decide on this. I can provide the needed
patches though.

Thanks for your review!

Regards,

Christian

-- 
May you be peaceful, may you live in safety, may you be free from
suffering, and may you live with ease.

Re: [PATCH] Improve usage of odt content templates

[Nicolas Goaziou]

Hello,

Christian Kellermann <ckeen@pestilenz.org> writes:

> I first thought about using ODT_STYLES_FILE in the list form and
> pick out the content.xml from there, but maybe that's a bit unexpected
> as one might use a different content than from the style.
>
> But the control flow as it is now would need to be refactored to
> make this a nice patch too.
>
> I shall resend this patch with proper docstrings and manual patches
> if you like.

Please do.

>> I think this is a more general issue: should we implement an
>> 
>>   #+OPTIONS: title:nil
>> 
>> feature? I think it makes some sense since we already have date:nil and
>> author:nil. In any case, keywords are not meant to be used for booleans.
>> This should be an OPTIONS item.
>
> I don't feel qualified to decide on this. I can provide the needed
> patches though.

Introducing the item is easy, but making something out of it in each
back-end is not, as it requires to define what title:nil means there. In
particular, should it be "an empty title" or something else?

For example, ascii back-end provides a banner as its title. Should
title:nil remove the title from the banner or should it remove the
banner altogether, thus overriding date:t and author:t items.

Likewise, should title:nil insert "\title{}" in a LaTeX document header,
remove the "\maketitle{}" line, or perhaps, both?

It seems that you answered to that question regarding ODT back-end
though.

WDYT?


Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Improve usage of odt content templates

[Detlef Steuer]

Am Wed, 21 May 2014 14:47:37 +0200
schrieb Nicolas Goaziou <n.goaziou@gmail.com>:

> Hello,
> 
> Christian Kellermann <ckeen@pestilenz.org> writes:
> 
> > I first thought about using ODT_STYLES_FILE in the list form and
> > pick out the content.xml from there, but maybe that's a bit
> > unexpected as one might use a different content than from the style.
> >
> > But the control flow as it is now would need to be refactored to
> > make this a nice patch too.
> >
> > I shall resend this patch with proper docstrings and manual patches
> > if you like.
> 
> Please do.
> 
> >> I think this is a more general issue: should we implement an
> >> 
> >>   #+OPTIONS: title:nil
> >> 
> >> feature? I think it makes some sense since we already have
> >> date:nil and author:nil. In any case, keywords are not meant to be
> >> used for booleans. This should be an OPTIONS item.
> >
> > I don't feel qualified to decide on this. I can provide the needed
> > patches though.
> 
> Introducing the item is easy, but making something out of it in each
> back-end is not, as it requires to define what title:nil means there.
> In particular, should it be "an empty title" or something else?
> 
> For example, ascii back-end provides a banner as its title. Should
> title:nil remove the title from the banner or should it remove the
> banner altogether, thus overriding date:t and author:t items.
> 
> Likewise, should title:nil insert "\title{}" in a LaTeX document
> header, remove the "\maketitle{}" line, or perhaps, both?

To be consistent over backends I think it should be implemented as
an empty title string. If date:t or/and author:t are specified these
should show up somewhere.

\maketitle{} should be removed only, if a titlepage would appear empty 
in the exported document.

Just the usual 2c worth of opinion.

Detlef


> 
> It seems that you answered to that question regarding ODT back-end
> though.
> 
> WDYT?
> 
> 
> Regards,
> 

Re: [PATCH] Improve usage of odt content templates

[Rasmus]

Detlef Steuer <detlef.steuer@gmx.de> writes:

>> Introducing the item is easy, but making something out of it in each
>> back-end is not, as it requires to define what title:nil means there.
>> In particular, should it be "an empty title" or something else?
>> 
>> For example, ascii back-end provides a banner as its title. Should
>> title:nil remove the title from the banner or should it remove the
>> banner altogether, thus overriding date:t and author:t items.
>> 
>> Likewise, should title:nil insert "\title{}" in a LaTeX document
>> header, remove the "\maketitle{}" line, or perhaps, both?
>
> To be consistent over backends I think it should be implemented as
> an empty title string. If date:t or/and author:t are specified these
> should show up somewhere.
>
> \maketitle{} should be removed only, if a titlepage would appear empty 
> in the exported document.
>
> Just the usual 2c worth of opinion.

IMO, it just shouldn't set title in LaTeX.  When I use author:nil
\author{·} is simply not set and could be loaded via another file.  I
would also remove the \maketitle command.  I don't have any
particularly good argument for this, other than it feels right. . .
Alternatively, there could be a yet another option maketitle:if-title,
maketitle:always. . .

With the text backend.  I would make the banner dependent on the
presence of a title.  I.e. I'd probably go for no title, no banner.
Though it's less clear here to what extend a title-less banner makes
sense here.

—Rasmus

-- 
When in doubt, do it!

Re: [PATCH] Improve usage of odt content templates

[Bastien]

Hi Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> I think this is a more general issue: should we implement an
>
>   #+OPTIONS: title:nil
>
> feature? I think it makes some sense since we already have date:nil and
> author:nil. In any case, keywords are not meant to be used for booleans.
> This should be an OPTIONS item.

+1!

-- 
 Bastien